Manual Step
- Karl Henselin
- Blake Westmoreland
- Joel Wenzel
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.
Approve / Reject Action
Tasks can be approved from tasks page as well, but user members of Approval Role must approve step on release dashboard as there will be no task for them when gate is executed. If user member of Approval Role approves 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.
Administrator can approve or reject manual step.
Since FlexDeploy 8.0, manual step can be rejected, which would mean failure of manual activity and execution will stop.
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 approve or reject also.
Email Notification
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.
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 | @Since 8.0.0.4 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). |
On Error @Before 8.0.0.4 | |
Continue | If checked, any failure will be ignored, and the pipeline execution will continue. |
Notify Pipeline Role | Selects one or more roles from the pipeline definition to notify in case of error. Default role members are defined on the pipeline, and optionally overridden for each release. 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
@Since 8.0.0.4 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.
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.
On the Release Dashboard view, the user can assign values to the input fields and ultimately complete the step to progress through the pipeline, or stop the execution altogether.
Input fields will still be assigned values even if the user selects “Stop Execution”. When selected, all fields will be optional even if they were marked as required. However, custom validation and data validation will still apply. When the user submits the step (either completing or stopping the execution), their values will show up on the Execution Variables popup on the dashboard. Note that the values for input field variables will be null until the manual step it is assigned to has been initialized. When it gets initialized, the evaluated default script values will be assigned to their respective fields if present. Otherwise they will remain null until the user assigns values to them and submits the step.
Once the step has been submitted, the values submitted will be displayed on the dashboard.
Also, if the user stopped the execution by selecting “Stop Execution” when submitting the step, they will have the ability to replay the step/stage again. When this happens, the previous values assigned to input fields or the default value will be present, but the user can still modify them as needed.
On the Tasks screen, user has the ability to select the “Complete Step” or “Stop Execution” option which will launch a popup for them to enter values similar to the Release Dashboard view. Also, user has the option to assign the task to themselves so that only they can submit the manual step. However, FlexDeploy Administrators still have the ability to submit the task.
Replying by Email
When completing or stopping a manual step by email, the email will include the list of input fields and relevant information such as code, display name, description, data type, and if the input field is required. If the input field has list data associated with it, then the description will mention the first three items in the list with the following sentence: “Some possible values are: option 1, option 2, option 3”. There are also quick links to auto generate a reply with the proper format for the user to assign values to. Note that in the system Email Settings, “Enable Email Approval” has to be enabled with IMAP Settings configured for the server to process email replies.
When replying, make sure to use the words “Complete” or “Stop” along with a note on the same line. For assigning values to input fields, use the following syntax on a new line for each input field: CODE = VALUE. Similarly, using the links in the email will auto generate a reply and populate the necessary input fields in the correct format for the user to assign values to. Default values will initially be assigned to their respective codes. If the execution was replayed, then the previously submitted values will be displayed too, but the default values take priority. Using the screenshot above as an example, the reply email would look something like this. Keep in mind the last 3 lines were included when using one of the reply links.
Also, if an input field has a complex data type such as an environment id or date time, the user will have to include that in the proper format. If any error occurs when processing the reply, the server will send an email notifying the submitter of the issue. That email will have a subject starting with “Failed: Email response processing at Manual step…” and the body will look something like this:
In this case, there was validation on the field to accept numbers between 0 and 100. The submitted email included a value outside of that range which would have triggered this error. There will not be an email notifying the user if their email submission was processed successfully.
Script Variables
- style