feature: implemented @current and @next iteration selection (#45)

* feature: implemented @current and @next iteration selection

To use this functionality, simply pass @current or @next as the iteration value.

* tests: added @current and @next to the test cases

* docs: added instructions how to use the @current and @next iteration

Author: leonsteinhaeuser

README.md

@@ -151,7 +151,7 @@ jobs:
 To leverage the App authentication with this action the following steps are needed:
 
 - Create a GitHub App under your user or organisation as described in the [GitHub documentation](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app), note the App ID
-- Set the needed GitHub App permissions in order for the newly create App to access and manage Org Project, as described in the [GitHub documentation](https://docs.github.com/en/developers/apps/managing-github-apps/editing-a-github-apps-permissions). The minimum required permissions are: 
+- Set the needed GitHub App permissions in order for the newly create App to access and manage Org Project, as described in the [GitHub documentation](https://docs.github.com/en/developers/apps/managing-github-apps/editing-a-github-apps-permissions). The minimum required permissions are:
   - Repo: Actions: RW
   - Repo: Checks: RO
   - Repo: Contents: RO
@@ -164,10 +164,9 @@ To leverage the App authentication with this action the following steps are need
 - Create a private key to authenticate the newly created GitHub App as described in the [GitHub documentation](https://docs.github.com/en/developers/apps/building-github-apps/authenticating-with-github-apps), treat the downloaded key as sensitive material, store it in a GitHub secret accessible by this action.
 - Install the app in the target organisation, note the installation ID
 - Configure this action with
-    - `gh_app_secret_key` containing the aforementioned private key
-    - `gh_app_ID` containing the app ID, auto-generated by GitHub in the first step
-    - `gh_app_installation_ID` containing the installation ID, auto-generated by GitHub in the previous step. Binging the App to the Org
-
+  - `gh_app_secret_key` containing the aforementioned private key
+  - `gh_app_ID` containing the app ID, auto-generated by GitHub in the first step
+  - `gh_app_installation_ID` containing the installation ID, auto-generated by GitHub in the previous step. Binging the App to the Org
 
 ## JSON-Definition
 
@@ -307,6 +306,25 @@ jobs:
           custom_field_values: ${{ env.custom_field_values }}
 ```
 
+Since version 1.3.0 the iteration field also supports the following values:
+
+- @current: the current iteration
+- @next: the next iteration
+
+Both of these values are provided by the `project-beta-automations` package. The following json provides an example of how to use these values:
+
+Next iteration:
+
+```yaml
+'[{\"name\": \"Iteration\",\"type\": \"iteration\",\"value\": \"@next\"}]'
+```
+
+Current iteration:
+
+```yaml
+'[{\"name\": \"Iteration\",\"type\": \"iteration\",\"value\": \"@current\"}]'
+```
+
 ## Detailed example
 
 Since this repository is also covered by this automation, you can take a look at the definition within the [project-automation.yml](.github/workflows/project_automations.yml) file to check how it is defined here.

gh_api_lib_organization.sh

@@ -40,10 +40,24 @@ function extractOrganizationFieldID() {
 # extractOrganizationFieldNodeIterationSettingValue returns the field node setting value id
 #   1: field name
 #   2: select value
+#
+# NOTE: If the value is @current or @next, we check the the array of iterations and return the current or next iteration id.
 function extractOrganizationFieldNodeIterationSettingValue() {
-    local fieldName=$(echo $1 | sed -e "s+\"++g") # remove quotes
-    selectValue=$(echo $2 | sed -e "s+\"++g") # remove quotes
-    jq ".data.organization.projectNext.fields.nodes[] | select(.name == \"$fieldName\").settings | fromjson.configuration.iterations[] | select(.title==\"$selectValue\") |.id" $TMP_STORE_LOCATION | sed -e "s+\"++g"
+    local field_name=$(echo $1 | sed -e "s+\"++g") # remove quotes
+    select_value=$(echo $2 | sed -e "s+\"++g") # remove quotes
+
+    iterations_for_field=$(jq ".data.organization.projectNext.fields.nodes[] | select(.name==\"$field_name\").settings | fromjson.configuration.iterations[]" $TMP_STORE_LOCATION)
+    dates=$(echo $iterations_for_field | jq -r ".start_date" | sort )
+    STRINGTEST=(${dates[@]})
+    if [ "$select_value" == "@current" ]; then
+        iteration_selected=${STRINGTEST[0]}
+        echo -e $iterations_for_field | jq "select(.start_date==\"$iteration_selected\") |.id" | sed -e "s+\"++g"
+    elif [ "$select_value" == "@next" ]; then
+        iteration_selected=${STRINGTEST[1]}
+        echo -e $iterations_for_field | jq "select(.start_date==\"$iteration_selected\") |.id" | sed -e "s+\"++g"
+    else
+        echo -e $iterations_for_field | jq "select(.title==\"$select_value\") |.id" | sed -e "s+\"++g"
+    fi
 }
 
 # extractOrganizationFieldNodeSelectSettingValue returns the field node setting value id

gh_api_lib_user.sh

@@ -40,10 +40,24 @@ function extractUserFieldID() {
 # extractUserFieldNodeIterationSettingValue returns the field node setting value id
 #   1: field name
 #   2: select value
+#
+# NOTE: If the value is @current or @next, we check the the array of iterations and return the current or next iteration id.
 function extractUserFieldNodeIterationSettingValue() {
-    local fieldName=$(echo $1 | sed -e "s+\"++g") # remove quotes
-    selectValue=$(echo $2 | sed -e "s+\"++g") # remove quotes
-    jq ".data.user.projectNext.fields.nodes[] | select(.name == \"$fieldName\").settings | fromjson.configuration.iterations[] | select(.title==\"$selectValue\") |.id" $TMP_STORE_LOCATION | sed -e "s+\"++g"
+    local field_name=$(echo $1 | sed -e "s+\"++g") # remove quotes
+    select_value=$(echo $2 | sed -e "s+\"++g") # remove quotes
+
+    iterations_for_field=$(jq ".data.user.projectNext.fields.nodes[] | select(.name==\"$field_name\").settings | fromjson.configuration.iterations[]" $TMP_STORE_LOCATION)
+    dates=$(echo $iterations_for_field | jq -r ".start_date" | sort )
+    STRINGTEST=(${dates[@]})
+    if [ "$select_value" == "@current" ]; then
+        iteration_selected=${STRINGTEST[0]}
+        echo -e $iterations_for_field | jq "select(.start_date==\"$iteration_selected\") |.id" | sed -e "s+\"++g"
+    elif [ "$select_value" == "@next" ]; then
+        iteration_selected=${STRINGTEST[1]}
+        echo -e $iterations_for_field | jq "select(.start_date==\"$iteration_selected\") |.id" | sed -e "s+\"++g"
+    else
+        echo -e $iterations_for_field | jq "select(.title==\"$select_value\") |.id" | sed -e "s+\"++g"
+    fi
 }
 
 # extractUserFieldNodeSelectSettingValue returns the field node setting value id

test_organization.sh

@@ -53,3 +53,23 @@ custom_fields="[
 ENTRYPOINT_TYPE=custom_field
 RESOURCE_NODE_VALUE=$custom_fields
 $ENTRYPOINT_SCRIPT "$ENTRYPOINT_MODE" "$ENTRYPOINT_TYPE" "$ORG_OR_USER_NAME" "$PROJECT_ID" "$RESOURCE_NODE_ID" "$RESOURCE_NODE_VALUE"
+
+custom_fields="[
+    {
+        \"name\": \"Iteration\",
+        \"type\": \"iteration\",
+        \"value\": \"@next\"
+    }
+]"
+RESOURCE_NODE_VALUE=$custom_fields
+$ENTRYPOINT_SCRIPT "$ENTRYPOINT_MODE" "$ENTRYPOINT_TYPE" "$ORG_OR_USER_NAME" "$PROJECT_ID" "$RESOURCE_NODE_ID" "$RESOURCE_NODE_VALUE"
+
+custom_fields="[
+    {
+        \"name\": \"Iteration\",
+        \"type\": \"iteration\",
+        \"value\": \"@current\"
+    }
+]"
+RESOURCE_NODE_VALUE=$custom_fields
+$ENTRYPOINT_SCRIPT "$ENTRYPOINT_MODE" "$ENTRYPOINT_TYPE" "$ORG_OR_USER_NAME" "$PROJECT_ID" "$RESOURCE_NODE_ID" "$RESOURCE_NODE_VALUE"

test_user.sh

@@ -52,3 +52,24 @@ custom_fields="[
 ENTRYPOINT_TYPE=custom_field
 RESOURCE_NODE_VALUE=$custom_fields
 $ENTRYPOINT_SCRIPT "$ENTRYPOINT_MODE" "$ENTRYPOINT_TYPE" "$ORG_OR_USER_NAME" "$PROJECT_ID" "$RESOURCE_NODE_ID" "$RESOURCE_NODE_VALUE"
+
+
+custom_fields="[
+    {
+        \"name\": \"Iteration\",
+        \"type\": \"iteration\",
+        \"value\": \"@next\"
+    }
+]"
+RESOURCE_NODE_VALUE=$custom_fields
+$ENTRYPOINT_SCRIPT "$ENTRYPOINT_MODE" "$ENTRYPOINT_TYPE" "$ORG_OR_USER_NAME" "$PROJECT_ID" "$RESOURCE_NODE_ID" "$RESOURCE_NODE_VALUE"
+
+custom_fields="[
+    {
+        \"name\": \"Iteration\",
+        \"type\": \"iteration\",
+        \"value\": \"@current\"
+    }
+]"
+RESOURCE_NODE_VALUE=$custom_fields
+$ENTRYPOINT_SCRIPT "$ENTRYPOINT_MODE" "$ENTRYPOINT_TYPE" "$ORG_OR_USER_NAME" "$PROJECT_ID" "$RESOURCE_NODE_ID" "$RESOURCE_NODE_VALUE"