Automation basics
Understand the general concepts and best practices of automation in Atlassian cloud products.
Actions are the doers of your rule. They allow you to automate tasks and make changes within your site, and can perform many tasks, such as editing an issue, sending a notification, or creating sub-tasks.
See how to use all of these actions in our Jira automation template library.
Use smart values here: Yes
Required permissions: Assign issues, Assignable user
Assigns an issue to a user.
There are eight different options for assigning issues:
A user in a defined list: An issue that passes a restriction (specified in JQL) is assigned to a user from a specified list of users using the method of your choosing. This can be:
Balanced Workload: Ensures that each user in the list has the same number of issues assigned. The scope of these issues is defined by the JQL.
Random: Assigns randomly from the list of users.
Round-Robin: Assigns issues based on the sequence in the list of specified users.
Another field value or comment: Assign the issue based on user field values on the issue or in a comment. For example, assign the issue to a previous assignee based on the issue history, or assign the issue to its creator. If you specify users to exclude, or groups the user must be in, any user not matching this requirement will be skipped and the action will continue looking for matching users (such as going further back in the issue history of assignees).
Automatic: Assign the issue to the project's default assignee.
Copy from another issue: Copy the assignee from a related issue. You can also use JQL to find an issue to copy the assignee from.
Smart value: Assign the issue based on a smart value. For example, when an issue is commented on, you can assign it to the author of the comment. Learn more about user smart values.
Specify user: Assign to a selected user.
Unassigned: Remove existing user and set the issue as ‘Unassigned’.
User who triggered the event: Assign the issue to the user who triggered the event.
User in a role: Assign the issue to a specific role within a team.
User in a group: Assign the issue to a user under a selected group.
On-call responder: Assign the issue to who is on-call, based on a team's Opsgenie on-call schedule.
Attach one or more forms to an issue. You can also set the visibility of the forms. Learn more about how forms work in the issue view.
Use smart values here: Yes
Creates a duplicate of an issue within the same project or a project of your choosing.
This action can be used as part of a workaround for moving issues between projects.
This action will create a new issue and copy across all field data possible, including the ability to copy attachments by selecting the Attachment field from the list of supported issue fields and then choosing the source issue from which attachments need to be copied.
Its status is then set to the first step of the corresponding workflow, and any resolutions from the original issue will be cleared. As the issue is not a true clone, it won’t be linked to the original issue.
You can also set values to override any copied data in supported fields. For Jira Service Management, you set both Jira fields and Assets fields. Learn more about Assets in Jira Service Management.
Select More options to display additional fields for advanced field editing.
This action will not clone issue links or comments.
Use smart values here: Yes
Adds a comment to an issue.
You can use smart values to reference issue fields to personalize the comment. You can also set the comment visibility.
Copy one or more forms from one issue to the current issue.
Creates a branch in the tool of your choosing. There are currently three actions that do this:
Create branch in Bitbucket
Create branch in GitHub
Create branch in GitLab
This requires setting up a connection between your automation rule and the other tool. Learn more about connections in automation.
You can also use smart values to access information related to these branches - learn more about created branch smart values.
Branch names cannot:
Be HEAD, as this is a reserved word
Start or end with /
Start or end with .
End with .lock
Contain a space
Contain the following symbol sets: .., ~, ^, :, ?, *, [, /, \\, @{
Use smart values here: Yes
Creates a Confluence page (or blog) in an Atlassian Cloud site of your choosing. Note that this creates the Confluence page, but it doesn’t enter any content. This means while you can define the page title using smart values, the automation rule can’t define any of the page content.
Requires a connection between your Jira project and Confluence. Learn more about using Jira automation with Confluence.
Use smart values here: Yes
Required permissions: Browse projects, Create issues
Creates an issue of any type to a project. You can select fields to configure, and set their values. You can copy attachments by selecting the Attachment field from the list of supported issue fields and then choosing the source issue from which attachments need to be copied.
Select More options to display additional fields for advanced field editing.
For Jira Service Management, you can set both Jira fields and Assets fields. For Jira Service Management, if the rule is triggered by an object, you can select Insert object to automatically add the triggered object via AQL. Learn more about Assets in Jira Service Management.
Take care when using Project > Same project as trigger on global rules. As the project type is unknown until the rule runs, all issue types are available to configure. This means that you can select an issue type that will not exist in the project.
Create a table of key-to-value mappings and assign it to a smart value, which can be used in other actions and conditions in your rule. In the following example:
The smart value {{departments.get("HR")}} would return Human Resources.
Note that your key-to-value map can only be called within the same rule. If the action is used in a branch, the smart value can only be used within the same branch. Key/value mappings don’t carry across to other rules or branches.
Example use case
Let’s say you want to create an automation rule that assigns due dates on a bug based on priority; bugs that are high priority need to be completed within the week, while bugs that are lowest priority can be completed within the next 6 months.
You could create a key/value map with the following values:
And then, using the Edit issue action and the {{dueDates.get(issue.Priority.name)}} smart value, you can automatically assign due dates based on how urgent the bug is:
Note that when nesting smart values in this way, the value returned by the nested smart value must be a string. So in this example, if you instead used issue.Priority.id, it won’t work unless you add .format(“#”) to turn the output into a string (i.e. {{dueDates.get(issue.Priority.id.format("#"))}})
Use smart values here: Yes
Creates sub-tasks on an issue.
This action only supports setting the Summary of the sub-task.
Selecting Add fields will convert the Create sub-tasks action into a Create issue (issue type: sub-task) action, allowing you to set additional fields.
Use smart values here: Yes
Define your own smart value, which can be used in other actions and conditions in the same rule. The smart value you define can consist of other smart values, as well as math functions.
Note that this will always return a string. For example, if you created variable called Stakeholders with the smart value {{issue.watchers.distinct}}, your variable would return the list of watchers but the list would be rendered as a string.
Use smart values here: Yes
Can be used to delete a comment on an issue. There are two different ways to use this action:
Deleting a trigger comment: If the rule uses a trigger that involves adding a comment, such as Issue commented, Issue transitioned, or Issue updated, {{comment.id}} will delete that comment.
Deleting other comments: Delete a comment on an active issue by using a comment smart value, such as {{issue.comment.first.id}}.
Use smart values here: No
Deletes the current issue that is in context.
This action allows you to remove unwanted issues from your site, such as when automating moving issues between projects.
Deletes the current issue that is in context. This is a great way to remove unwanted issues from Jira, such as in automating moving issues between projects.
Use smart values here: No
This action allows you to remove any issue links currently on an issue. You can remove all issue links of a certain type (for example, remove all "blocked by" issues), or select specific issues to unlink.
Use smart here: Yes
This action allows you to edit a comment's visibility, or the contents of a comment. Available options are:
First comment: Edit the oldest comment on an issue.
Last comment: Edit the most recent comment on an issue.
Trigger comment: Edit the comment that triggered the rule. Used with triggers such as Issue commented or Issue comment edited. Learn more about automation triggers.
Smart value: Choose a comment to edit by providing a comment smart value.
Once you've selected an option, you can leave the next field blank to keep the comment unchanged; this is useful if you only want to edit the comment's visibility, and nothing else. Entering the smart value {{currentComment}} will return the current content of the comment; this is useful if you want to retain the current comment and add content before or after it.
Use smart values here: Yes
For Jira Service Management only. This action edits the attribute values of an Assets field. You can enter either a smart value, a string value, or the ID/Key of an Assets object. If the field is left empty here, the object's value will be cleared.
Assets attributes can have many different types of values (string, integer, user, date, reference object, etc.), so you have to get the input right here. This rule will result in an error if the value in this action doesn't match the attribute type.
Use smart values here: Yes
Edit the current issue by choosing the field to set and value to add. For Jira Service Management, you can edit both Jira fields and Assets fields. Learn more about Assets in Jira Service Management.
You can set some values to be dynamic. You can also copy attachments by selecting the Attachment field from the list of supported issue fields and then choosing the source issue from which attachments need to be copied. Select More options to display additional fields for advanced field editing.
Use smart values here: Yes
For Jira Service Management only.
Updates an object's attribute values. You can enter either a smart value, a string value, or the ID/Key of an Assets object. If the field is left empty here, the object's value will be cleared.
Assets attributes can have many different types of values (string, integer, user, date, reference object, etc.), so you have to get the input right here. This rule will result in an error if the value in this action doesn't match the attribute type. Learn more about Assets in Jira Service Management.
You can only use this action:
for global automation rules and only when an object is the focus of the rule. For example, if the rule begins with an Object trigger, the object that triggered the rule will be the object that is edited by this action.
when it's under a branch on an AQL branch. It won't work on its own and it won't work with the Lookup objects action.
Use smart values here: Yes
For Jira Service Management only.
Updates the request type for an issue. Note that request types are based on issue types; any number of request types can correspond to one issue type. However, this means that when your automation rule acts on an issue, the chosen request type must correspond to that issue type. If it doesn't, the action will result in an error on the audit log.
Use smart values here: No
Can only be used with vulnerability found trigger.
Links the trigger vulnerability to an issue.
To create and link a new issue for every trigger vulnerability:
Create an automation with the vulnerability found trigger and the create issue action.
In the drop-down menu in the link issue to vulnerability action, choose most recently created issue.
To link all trigger vulnerabilities to one issue:
Create an automation with the vulnerability found trigger.
In the drop-down menu in the link issue to vulnerability action, enter the issue key.
If you enter an issue key in this action, the automation will fail if the issue doesn’t exist when the rule is run.
Use smart values here: Yes
Links an issue to another by selecting the link type and the issue to link.
You can link to the issue that triggers the rule, the current issue on a related issues branch, a smart value or an issue key.
Use smart values here: Yes
You can use date and time smart values to dynamically set the date started, and text smart values to customize the description.
Use smart values here: Yes
Search for up to 100 issues using a JQL query. Include the results list in other actions by using the {{lookupIssues}} smart value. Learn more about using smart values with issue lists.
All fields and custom fields can be accessed from the lookupIssues list. For example, to print the issue key for each issue in bullet point form:
1
2
3
{{#lookupIssues}}
* {{key}}
{{/}}
And the following example sums all story points in the issue list:
1
There are {{lookupIssues.Story Points.sum}} story points remaining.
Use smart values here: Yes
For Jira Service Management only
Search for up to 100 objects using an Assets AQL query. Learn more about Assets in Jira Service Management.
Pass the resulting list of objects to other actions by using the {{lookupObjects}} smart value. This can be used to access and print the list of objects, but can't be used to trigger other rules. Learn more about smart values for JSM Assets.
Use smart values here: Yes
Add or remove watchers on an issue.
You can specify users to add or remove by using smart values directly in the fields.
Use smart values here: Yes
Transitions an issue from one status to another, through a workflow.
You can select field to update as part of this transition, for example:
Copy from issue: copies the status from a related issues or an issue on a branch rule.
Copy from parent: for use with sub-tasks; copies the status from a parent.
Copy from Epic: copies the status from the issue's associated Epic.
Copy from Trigger issue: copies the status from the issue that triggered the rule.
Same status (loop): for use when a transition exists from the current status back to itself; this can be used together with a screen to gather more data from users, e.g. an Escalate transition.
You can also copy attachments by selecting the Attachment field from the list of supported issue fields and then choosing the source issue from which attachments need to be copied. Select More options to display additional fields for advanced field editing.
For Jira Service Management, you can edit both Jira fields and Assets fields. Learn more about Assets in Jira Service Management.
Changes to "Reply to" addresses
From June 28, 2021, only the first email listed in the Reply to field will receive reply emails. This means:
For new automation rules that have the Send email action, we recommend putting only one address in the Reply to field.
For existing rules that use the Send email action, we recommend reconfiguring them so that only one address is used in the Reply to field.
Use smart values here: Yes
Sends an email. All the fields on this action support customization using smart values.
Selecting All customers involved from the To field will trigger the email to be sent to the reporter, request participants, customers whose organization has been added to the issue, and customers who have subscribed to issue notification. Learn more about customers and organizations in Jira Service Management.
Note that there are limits around how many emails this action can send - Learn more about Automation service limits.
This action will automatically provide the email's message ID in the audit log. If the email needs to be traced, use the information provided in this format: <message-id>@automation.atlassian.com.
Use smart values here: Yes
Sends a Microsoft Teams message to notify a team when a rule is run
You can personalize the message in this action. Learn more about using automation with Microsoft Teams.
Use smart values here: Yes
Sends a Slack message to notify a team or individual when a rule is run
You can personalize the message in this action. Learn more about using automation with Slack.
Use smart values here: Yes
Sends a notification using the Twilio service.
This action is useful for service teams that rely on SMS for on-call scenarios.
Use smart values here: Yes
Your network must allow requests from Atlassian in order for this to work. For outgoing connections, see IP addresses and domains for Atlassian cloud products.
Sends an outgoing web request to notify another system when a rule is run. You can set this action to return response data that can then be used in a subsequent action.
There are three different formats you can select from:
Issue data (Jira format) - The format used by throughout most of Jira Cloud, including Jira Cloud’s Legacy Automation feature. Learn more about the Jira format.
Issue data (Automation format) - The format used by Jira Cloud automation components. Learn more about the automation format.
Custom format - Select this option to enter your own data format.
Note that the only permitted ports for urls from the Send web request action are 80, 8080, 443, 6017, 8443, 8444, 7990, 8090, 8085, 8060, 8900, 9900.
You also have the option to hide each header by selecting the Hidden checkbox. This will ensure the value displays only as asterisks (*****); you won’t be able to view the value, or inspect any payload.
Once a value is hidden, this can’t be reversed (i.e. the Hidden checkbox can’t be unselected), though the value itself can still be changed when editing your rule.
Use smart values here: Yes
Adds new customers to your Jira Service Management project.
You can use smart values in all fields and add the customer to an existing organization.
Calling this action multiple times in quick succession will result in the first call succeeding and then subsequent calls failing due to the customer existing but not yet showing up in user search results. It can take up to 15 seconds for the new user to appear in searches and this to resolve itself.
The {{customer}} smart value will not return the existing user until they are available in the user search results and the action will result in an error.
If this issue is affecting your rule, you can introduce a delay into your rule by adding a number of Re-fetch issue data actions right before the Add Service Project customer action – note that this may not work in all cases.
Use smart values here: No
Approves or declines a request in Jira Service Management, regardless of how many approvers are needed to proceed in the workflow.
You can use this action on Jira Service Management issues that are pending approval on the current workflow status. Approvals are managed through the workflow. Learn more about approvals in Jira Service Management.
Use smart values here: Yes
Creates a new issue in a Jira Service Management project using the selected request type.
All request types you’ve added to the service project can be used with this action. Learn how to organize your request types into portal groups
Similar to the Create issue action, this action allows you to configure any field available using smart values.
Use smart values here: Yes
Required permissions: Browse projects, Create issues
When this action is executed, an incident of selected request type will be created in the selected service project on Jira Service Management. For example, you can use this action to create a new incident when an issue is created and meets certain criteria.
You'll also have the option to avoid creating a new incident if the action has already created an open incident of the same type in the project.
You need to have a service project and a request type for incidents to use this action.
Use smart values here: Yes
Creates a new version that you can assign issues.
If a version with the same name already exists, the version will not be created.
Use smart values here: Yes
Releases a version.
By default, this action will release the next unreleased version of a project with the existing release date. This is determined by the order the versions are set in Releases.
You can select a specific version to release, and use smart values to set dynamic names.
Use smart values here: Yes
Cleans up attachments using regular expression matches, based on the attachment filename.
Use smart values here: Yes
Logs a value to the audit log.
This action is useful when testing smart values, and debugging rules.
Use smart values here: No
Refreshes smart values with the latest field values.
By default, the {{issue}} reference is not updated during rule execution, and contains the same values as when the rule originally triggered.
Use smart values here: Yes
Sets entity properties on issues, projects and users related to the trigger issue of the rule execution.
These hidden properties can be used by apps for certain functions. Entity properties allow plugins to add key/value stores to issues and projects. These values can be indexed and queried via REST API or JQL.
Use smart values here: Yes
Unrelease a released version for a chosen project. By default, this will be the rule's project, but you can select More options to choose a different project.
Use smart values here: Yes
When this action is executed, a JSON message is sent to the selected Amazon Simple Notification Service topic. You can add up to 10 key-value pairs to an action. If you’d like to add more, contact support.
Smart values can be used with all value types (String, List, Number, Boolean, and Custom). However, Custom only supports smart values.
Make sure that your Amazon SNS topic allows Atlassian Automation to publish messages. Learn more about configuring Amazon SNS.
Use smart values here: Yes
When this action is executed, the selected AWS Systems Manager document will be run. You can add values to the pre-configured parameters of the document.
Make sure that the IAM role has a Permission Policy allowing Atlassian Automation to access and run SSM documents. Learn more about configuring AWS IAM.
Use smart values here: No
When this action is executed, the selected Virtual Machine in Microsoft Azure will be restarted by Atlassian Automation.
Make sure you’ve added Email in your Microsoft Azure profile information for authentication of the rule’s connection. Learn how to add or change profile information in Microsoft Azure
Was this helpful?