Manual Step
- Karl Henselin
- Chandresh Patel
- Blake Westmoreland
The Manual step creates a task for the assigned role group members and blocks the stage execution until the task is either approved or rejected (either through the release dashboard, tasks page, or via the REST API, or via Emails (pipeline roles and users can complete the task)). This is useful when there are manual steps that must be performed in between automated steps executing within a stage.
Field | Description |
|---|---|
Name | The name of the step. |
Description | An optional description for the step. |
Approval Role | The pipeline role which is assigned to this manual step. Optionally, use a Groovy expression to make this field dynamic based on some contextual value (e.g. a property defined on the pipeline, and specified on the release). When using a role script you can dynamically return a key/value pair. For example |
Input Fields | User defined inputs that are used to control behavior within your Pipeline during each execution. Input Fields are assigned values during the execution of this step. These can be accessed in groovy via the ‘Code’ field, but are read-only and cannot be modified. |
Precondition | An optional Groovy script which determines whether the gate or step is applicable during execution. The script has access to variables and methods listed in Pipeline Groovy Variables and Methods. You can find these variables and methods while using the Groovy Editor. The script must return true if the step is applicable, or false otherwise. If no script is provided, the default is to return true (applicable). |
Input Fields
Input Fields are user defined inputs that control behavior within your Pipeline during each execution. Input Fields are assigned values during the execution of this step. This can be done from the Release Dashboard, Tasks screen, or through Email reply. These can be accessed in groovy via the ‘Code’ field, but are read-only and cannot be modified. Trying to modify an input field variable within a script will result in an error during execution. Similar to other property definition screens like Workflow Properties or Pipeline Properties, Input Fields are highly customizable. However, they are not encrypted and the default value is defined as a script, which will be evaluated at the initialization of this step during execution. The pipeline script variables are accessible in the default value, validation, and list data scripts for each input field.
To create a new Input Field, click the Create button. To edit or delete an existing Input Field, use the options from the Actions menu. The Edit Property wizard provides multiple options for customizing the overall behavior of the property.
Field | Description |
|---|---|
Code | A code for the input field, as appropriate for variables within Groovy or Shell scripts. (e.g. no spaces or special characters other than underscore.) |
Display Name | A meaningful name for the input field used for display. |
Description | A meaningful description for the input field. |
Required | Whether or not a value is required for this input field. |
Default Value Script | A groovy script that returns a value which will be assigned to the input field when the step is initiated. Groovy libraries are available to reference in this script. Other pipeline script variables can also be referenced but this only applies to Input Fields. |
Validation Script | Optional Groovy Script to validate provided value. The script should return true if the value is valid, and false otherwise. The user-specified value is available to the script in the Value variable. If not valid, the ValidationMessage is displayed to the user. Groovy libraries are available to reference in this script. Other pipeline script variables can also be referenced but this only applies to Input Fields. For example, if ("BAD".equals(Value))
{
ValidationMessage="Bad value!!";
return false;
}
else
{
return true;
} |
Field Data Type | The data type for this input field. |
List Data CSV | A comma separated list of valid values for the input field. Optional, and only applicable for Text Field and Text Area data type. To provide more detail, the following format can be used for labels or descriptions: |
Multiselect | Whether multiple values can be selected from the List Data. Only applicable when List Data CSV is provided. |
Max Length | The maximum allowed length of the property value. Optional, and only applicable for String data type. |
Min Value | The minimum allowed property value. Optional, and only applicable for Number and Decimal data types. |
Max Value | The maximum allowed property value. Optional, and only applicable for Number and Decimal data types. |
Click the Done button to save the changes to the property (be sure to also save the pipeline, or changes will be lost).
Using List Data
There are multiple ways to fill out the List Data CSV field when specifying an input field. There are a few terms to iron out before we dive in:
label - The label is what text will be shown on the select option.
value - The value is what value will be saved when selecting an option. This is not visible on the screen when selecting a value.
description - The description is simply a hint that will be shown below the option label.
Take for example the Field Data Type selection above:
In this case “Text Field” is our label, “Generic text field” is our description and our value (again hidden) would be some id that correlates to the Text Field type.
With that out of the way let's talk about the various ways we can define the list data.
Plain Text
Plain text is the default for list data. It is simpler than Groovy but does not support as many use cases. Below are the variations which can be used for Plain Text
Variation | Notes |
|---|---|
john, jack, jill | When specifying a CSV in this fashion, each entry will be used for BOTH label and value. This means the selection option will show “john” and when selected we will save a value of “john”. The description is omitted in this variation. |
John##john, Jack##jack, Jill##jill | You can optionally separate entries with |
John##john##QA Analyst, Jack##jack##Software Engineer | Lastly, you can add a third segment, also separated with Note that you can mix and match entries in the CSV. For example, if Jack did not have a role within the company you can omit the description: John##john##QA Analyst, Jack##jack |
Groovy
Using Groovy to define your list data has the added benefit of being able to make HTTP calls or any other means to dynamically set the list data. As such there are infinite examples of usages but a few are shown below.
Groovy libraries are available to reference in this script. Other pipeline script variables can also be referenced but this only applies to Input Fields.
Variation | Notes |
|---|---|
return 'john, jack, jill' | The simplest example is for all intents and purposes identical to the first example in the Plain Text examples. Any variation you can do in Plain Text can be done in Groovy by just returning it as a string. |
return ['john', 'Jack##jack', 'jill'] | Perhaps more conventional in terms of Groovy scripting, you can return a list of strings to represent the options as well. |
import flexagon.fd.model2.pojo.common.ListValueDataObject;
return [
new ListValueDataObject("value1"),
new ListValueDataObject("label2","value2"),
new ListValueDataObject("label3","value3","Description")
] | You can also use the |
import flexagon.ff.common.core.rest.FlexRESTClient;
import groovy.json.JsonSlurper;
def client = new FlexRESTClient("https://swapi.dev/api/people");
client.addHeader("accept", "application/json");
def response = client.get();
def jsonObject = new JsonSlurper().parseText(
response.getResponseString()
);
// json keys can be accessed via dot notation
// for example jsonObject.items or jsonObject.result.data
// the following returns a list of text names
return jsonObject.results.collect({item -> item.name}) | This final example is making a public API call to the Star Wars API and returning a list of Star Wars character names as list options. At the end of the day, this is boiled down to something like: return ['Luke Skywalker', 'Han Solo', 'Darth Vader'] |
Referencing Input Fields Across the Pipeline Version
Each input field code is unique to the pipeline version it is defined in, and cannot be an existing pipeline property or pipeline variable code. The same code cannot be redefined on other steps in the version. This is to ensure that the values are not overridden during execution. In cases where you might need to have the same inputs across multiple stages, it is recommended to prefix the stage name to the code. As an example using the screenshot above, we have a Manual Step with the purpose of testing changes that were deployed. Each stage will have a manual step to perform manual testing and decide if we need to deploy rollback packages in case any errors were found while testing. For our Development stage, we would specify the “Run Rollback” input field code as DEV_RUN_ROLLBACK. In the QA stage the code would be QA_RUN_ROLLBACK etc. There is also another input for the user to record the percentage of test cases that were successful. Lastly, we would reference the input field code in the preconditon of the deploy rollback packages step depending on what the user submitted during the manual testing. Similarly, we could include a custom gate at the next stage to evaluate the DEV_TEST_SUCCESS input field.
Complete or Stop Execution
Tasks can be completed from tasks page as well, but user members of Approval Role must complete the step on release dashboard as there will be no task for them when gate is executed. If user member of Approval Role completes the step, then task is created and approved for any one of approver user's group for reference.
Note that even when more than one Groups are member of Approval Role, only one approval is needed to complete this step.
When the step is completed, it will be marked as successful and the execution will continue.
When the “stop execution” action is taken on the manual step, then the execution is immediately aborted. However, the manual step can be replayed.
When using Task page, user can claim the task to work on, at which point other users will see that someone else is working on it and they will not be able to complete or stop execution also.
Administrator can complete or stop execution on the manual step.
For more information please view the Complete or Stop Execution for Manual Step page.
Email Notifications
When manual step is executed, email will be sent to members of Approval Role.
Individual email is sent for
Each group member of Approval Role. i.e. if there are two groups in Approval Role, two individual emails will be sent for each group’s users.
All user members of Approval Role
All email addresses member of Approval Role
For submitting the manual step through email reply, see Replying by Email.
Script Variables
Related content
- style