| Table of Contents | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Workflow functions
- CLI action (validator) - check information from a CLI action before allowing a transition
- CLI action (post-function) - run a CLI action after the transition has completed
Related documentation
Refer to the ACLI or product specific Documentation and Examples for how to use CLI actions.
Usage
Administrator authority is required to add or update workflow actions. This is required to use JCLIP.
- Create a draft workflow
- Edit the workflow
- Find the workflow step
- Select Validators or Post Functions tab
- Select Add
- Find and select CLI action
Parameter input dialog
CLI action validators and post functions share the same parameters.
- Product - select the product (JIRA, Confluence, Bamboo, Crucible, FishEye) to be accessed
- Action - provide an action string valid for the product selected - same as what you would do from a command line
- Data - some CLI actions can input data from standard input or using the file parameter and this allows the input data to be provided directly
- When using the file parameter, specify to use standard input: file -
- Find pattern1 - A regex pattern that is used to find data on the result produced by running the CLI action
- For a validator, if the pattern is not found, the validator will fail
- Regex find groups are available as substitution variables using syntax like %pattern1_1%, %pattern1_2%, etc ...
- Find pattern2 - a second find pattern
- Regex find groups are available as substitution variables using syntax like %pattern2_1%, %pattern2_2%, etc ...
- Message - Validator error message and workflow property value
- If validator fails (action fails or one of the find patterns do not match), this error message will be shown as a transition error
- Use text and substitution variables to construct a reasonable message
- For both validators and post functions, this message is passed as a workflow property for access in subsequent CLI actions
- Notes - This provides administrators an opportunity to better document this workflow function
Variable substitution
A variety of substitution variables are available to use in text parameters.
| Category | Variables | Where Used | Discussion |
|---|---|---|---|
| Issue special values | %issue_key% %issue_summary% %issue_description% %issue_affected_versions% %issue_fixed_versions% %project% | Action, Data, Message | |
| Parent issue special values | %parent_key% %parent_summary% %parent_description% %parent_affected_versions% %parent_fixed_versions% | Action, Data, Message | Only available if issue is a subtask |
| Issue field values | %fieldname% | Action, Data, Message | Any JIRA defined field name. Like summary, description, environment, issueType, priority, resolution, versions, fixVersions, components, duedate, reporter, assignee, timetracking, id |
| Issue custom field values | %customfieldname% | Action, Data, Message | Issue specific custom field name |
| CLI values | %base_url% %validator_message% %function_message% | Action, Data, Message | URL of this JIRA instance - useful for local JIRA actions Message field from last run CLI action validator Message field from last run CLI post function |
| Action result | %cli_message% | Message | Result message from running the CLI action |
| Pattern replacements | %pattern1_n% %pattern2_n% | Message | Regex group value from evaluating find pattern1 or pattern2. n represents the regex group number (1, 2, ...) - equivalent of $n substitution in other regex based usage. |
There are 2 primary ways to use this add-on.
- Workflow post function to run CLI actions on a transition - see CLI Post Function and CLI Validator
- Administrator UI for running CLI actions directly - see Administrator UI to Run CLI Actions
Related documentation
- Action Reference - find product specific actions that you can run as part of the transition
Logging
Setting up advanced logging is highly recommended.
See How to add advanced logging.
Security
CLI actions require user credentials to access Atlassian servers. Those credentials must be provided on the action, there isn't currently any way to avoid that even with Application links. Consider setting up an automation account for CLI automation use.
Limitations
Actions like updateIssue
and setFieldValue
should not be used if they reference the issue being transitioned. Instead, use post functions that are available for those specific functions directly. See JCLIP-19 for more information.