This is the JSU for Jira Cloud documentation. If you are using JSU on Jira Server or on Jira Data Center, see our JSU Server/Data Center documentation.
On this page: |
Description
The ‘Linked Transition’ post function triggers a transition on a related issue. It can be very powerful, especially when used with the Create a Linked Issue post function to connect the workflows of two issues. You can also specify any number of fields to be copied to the related issue.
Want to try a new way of creating this post function?
We’re working to make it even easier for you to build workflow rules with JSU. A simplied version of this post function is now available in our Universal Rule Builder – a new editor experience currently in beta.
Configuration
You must specify the workflow and transition that you want to apply to the related issue.
Precondition
Issue relation
Choose the type of issue that you want to transition to the new status.
Related issues are identified by one of the following Jira concepts:
Issue link: You can define the link type to define which issues will be modified by the operation. If the post function includes the link type is ANY option, the operation will be performed on any linked issues.
Parent / Sub-Task: The related issue is either a parent or a subtask of the issue.
Epic / Issue in Epic: The other issue is either an epic related by an epic link, or it is part of an epic. This is only applicable if you have Jira Software installed.
JQL: A JQL query will be executed to retrieve the issues that the post function will modify. You can use some placeholders in the JQL query, which will be replaced with the current field values of the issue in transition. For tips on writing the JQL query, see JQL Reference or our JQL Use Cases for some examples.
Transition
When the post function is performed, it will trigger the transition with that particular ID on the linked issues. When the post function is executed, it will appear as if the transition ID is available on the target issue, no matter what workflow and transition name you picked in the configuration screen (that is only to make it easier to find a particular transition ID during configuration).
If the transition with that ID is not available on the linked issue (probably because it is in a different status) nothing will happen. Also, no comments or fields are copied, and no resolution is set.
It is important to keep this in mind and design your workflows accordingly to prevent them from becoming 'out of sync'. You might also use several 'Linked Transition' post functions in the same transition, each calling a different target transition to match different possible statuses of the linked issue.
Be aware that there might be some workflow conditions or validators, which could prevent a transition from being performed.
The transition on the linked issue will be performed as the user defined by the Peform As User option.
Conditional statuses
Use this option if you want the issue to be transitioned only when ALL of the sibling issues are in a specified status. Only 'the last' issue will trigger a linked transition.
Consider a test case issue that has several linked bugs. The bugs are linked as 'from test' to the test case. Only when the last bug is fixed, the test case should be set to the Status 'Ready for Re-Test'.
This prevents this transition from being executed when the first bug is fixed.
Optional Settings
Resolution
To set the resolution, you need a resolution field on the transition screen. For more information, see Atlassian’s Mapping a Screen to a Workflow Transition page.
If any transition screen contains the resolution field, that field becomes mandatory. Here you have a chance to set a value for the resolution to be able to perform that transition.
Resolution in the post function configuration | Resolution on the issues at the start when the transition is performed | What happens? |
|---|---|---|
Empty | (does not matter) | The resolution on the issue will not change. |
Any value | Any other value | The resolution will be set to the defined value. |
Perform As User
When choosing a user account to run a post function, the specified user account must have the appropriate permissions to perform the actions, such as creating an issue or adding a comment.
If JSU determines that the specified user has insufficient permissions, it executes the rule using the JSU Add-on user. This is displayed in the Execution Log as a success and includes a warning.
JSU can’t determine if the specified user is missing necessary Jira global permissions. In this case, the rule runs using the specified user. If the run encounters a Jira error, it will fail. This is displayed in the Execution Log with a permission error.
JSU Add-On User (default)
The JSU Add-On User account is automatically added to an instance when JSU is installed and already has the required permissions to perform all actions across JSU post functions. If the permissions haven’t been manually removed from the JSU Add-On User, it should not impact its success as the Perform as User instead of another account.
If you don't specify a different option, the transition on the related issue is performed as the JSU Add-On User with its associated permissions. This option is useful for testing, and you can confirm the action in your issue activity.
When the JSU Add-On User makes changes to issues, you can see the changes in the Activity section of the issue:
Initiating User
The transition on the related issue is performed with the same user who triggered this post function on the origin issue. That user must have the necessary permissions on the related issue. In some restrictive setups, a user might not be allowed to perform the action or might not have permission to view the relevant project.
Choose user
Use this option to specify a different user account that has been granted the necessary permissions. Usually, this user account is assumed to be only technical (impersonation), with broad permissions, and not used by individuals to log into Jira.
In combination with the Permission condition in native Jira, or the User Is In Any Users condition from JSU, you can hide a transition from all users that do not have permission to execute it.
Initiating/Specified User
If you configure your post function for either the initiating user or a selected user, the relevant issue fields must be included in the associated issue screen.
For example, if you create a rule that updates a field in a related issue, the field must be included in the target issue Edit screen. Similarly, if you define a rule that creates a new issue, or copies a field to a new issue, the field must be included in the Create screen.
Copy fields
These fields will be copied to the linked issue after the transition occurs. The conditions and validators of your linked transition will still use the old field values.
In some post functions, you can copy the value of a source field to a destination field. You can configure these fields in the Copy Value From Other Field post function and with the optional operations of the Create a Linked Issue and the Linked Transition post functions.
Although the source and destination fields can be different data type, not all conversions from source to destination field are supported nor feasible.
Overwrite / append / prepend
For text fields and other fields that can accept multiple values (like checkboxes), you can overwrite, append, or prepend the new value to any existing value. For a text field, you can also choose a separator between the values.
Create version if necessary
Imagine your origin issue has a version that you want to copy to the linked issue. If the destination field is Fix Version/s, Affects Version/s, or some custom field of type version picker, you can define that a new version will be created in the target project if it does not yet exist. If you don't choose this option and that version does not exist, the user receives an error message and the transition completes.
A user needs the Administer Projects permission to be able to create a new version.
Create component if necessary
Imagine your origin issue has a component that you want to copy to the linked issue. If the destination field is Components, you define that a new component is created in the target project, if it does not yet exist. If you don't choose this option and that component does not yet exist, the user receives an error message and the transition completes.
A user needs the Administer Projects permission to create a new component.
Special sources
In addition to fields, you can select from the following special sources to copy to a destination issue. For example, you can copy the value of the previous user to the Assignee field of a new issue.
*** empty ***: The destination field will be cleared.*** last comment ***: The last comment from the source issue will be copied. In some cases that might be the comment from the transition screen, which the user just entered while performing the current transition.*** transition comment ***: The comment that the user entered on the transition screen will be copied to the destination field.*** current user ***: The user who triggered the post function will be copied to the destination field.*** previous user ***: The field is updated with the previous user assigned to the destination field. This is valid for single-user picker fields.*** current datetime ***: The current date and time will be copied to the destination field.
Special destinations
*** new comment ***: A new comment will be created with the copied value. When you choose to overwrite to new comment, a new comment is created, enabling you to add multiple comments in one post function.
Examples:Copy Description to New Comment, overwrite→ creates a new comment with the description.Copy Summary to New Comment, append with separator ", "→ appends the summary to the previously created comment, so the comment will look like <Description>, <Summary>.Copy Assignee to New Comment, overwrite→ creates a new comment.
This configuration will result in two comments being created: one with the description and summary, and one with the assignee.
Supported field types
JSU supports many different field types; system fields, as well as custom fields.
You should be aware, however, that not all field types or all combinations are supported. We have tried to cover the most important field types but we are continuously adding more and improving how different field types are supported. We recommend you test JSU with fields to see if it is compatible with your system. Our evaluation license provides you with a 30-day free trial.
Troubleshooting
If a linked transition does not get triggered or even blocks your origin transition, these are a few things to check:
Did you check the log files? There are cases when the linked transition is not performed silently. But you will find a message in the log files on the server. You might increase to logging level (as described in Linked Transition).
What happens when you manually click the linked transition? Does it work, or might there be a problem?
Does this problem only happen to another user? Check that the user performing the origin transition has enough permissions for the linked transition.
Is there a transition screen for the linked transition? Is there a condition, validator, or post function on the linked transition? Could these prevent the transition from being performed in an automatized way (with the 'Linked Transition' post function)?
In the order of all post functions of the origin transition, the 'Linked Transition' post function must be the last one.
Did you try to set a particular Resolution in the linked transition? Or with 'Resolution=empty' - does it then work?
Infinite Loop Detection
An infinite loop can occur when executing the Linked Transition post function. An infinite loop occurs when an automation rule results in an endless cycle of issue creation and follow-up transitions following the triggering of the origin issue. To help prevent this, consider the outcome of the rule and the user permissions of your project teams. When a loop is detected JSU will stop the execution and log an execution failure. Learn more about how JSU identifies an infinite loop in Infinite Loop Detection.