Event-based Actions

An Event-based Action is a series of one or more JMWE post-functions that run when a change is made to an issue, such as when fields are modified, an issue is transitioned, or a comment is added.

Some examples of what can be achieved through Event-based Actions are:

• Synchronizing changes to a field with related issues such as sub-tasks, linked issues, epics, etc.

• Calculating the value of a field based on the values of another field. See this post for a demonstration.

• Copying a comment added by a customer on a Service Management request to linked Jira Software issues.

• Validating data when a user edits an issue field on the issue view screen (as opposed to validating field values during a transition, for which you should use a Validator). See this video for a demonstration.

Administration

To access Event-based Actions:

1. Log into your Jira instance as an administrator.

2. Click the Settings icon in the upper right corner and select Apps.

3. Under JIRA MISC WORKFLOW EXTENSIONS in the left-hand panel, click Event-based Actions.

The Event-based Actions page (Figure 1, right) lists all Event-based Actions that have been created, as well as the following:

• Search - Filter the list of Event-based actions by action ID.

• Create new action - Click to create a new Event-based Action.

• Shared action list - A list of all Event-based Actions for the instance. The list includes the following information:

  • Enabled - Status of an Event-based Action. By default, a newly created Event-based Action is enabled.

  • Action Name - The name of the Event-based Action.

  • Event(s) - The event or events that will trigger the action.

  • Projects - The number of projects to which the Event-based Action has been applied.
    Hover over the badge to see a list of projects in which the Event-based Action is used.

  • Post-functions - The number of post-functions included in the Event-based Action.
    Hover over the badge to see a list of the post-functions included in the Event-based Action.

  • Action menu - Click to open a menu with specific actions for the Event-based Action:

    • Edit - Open the Event-based Action Editor to update the action.

    • Duplicate - Create a copy of the Event-based Action. The new action will have the same name as the original, with “- copy” appended.

    • View Summary - Open the Summary window (Figure 2, right), listing the triggering event for the action, the projects and issues included in the action, and the Post-functions that will run in the Event-based Action.

    • ID - The Jira ID of the Event-based Action. Click the menu option to copy the ID value to your clipboard. This value can be used in the JMWE Logs page to filter the logs by Action ID.

    • Delete - Permanently delete the Event-based Action.

Filter and Sort

Configure an Event-based Action

When you create or edit an Event-based Action, the Event-based Action Editor will open (Figure 3, right). The Event-based Action Editor uses the JMWE Automation Rule Builder, consisting of two side-by-side panels; the left panel has buttons for selecting each configuration category (e.g. When for the event that triggers the action), and the right panel includes specific configuration options for the selected category.

To configure an Event-based Action set the following configurations:

1. Action name (Point 1, Figure 3, right) - Required. Click the name to edit. Enter a meaningful name and hit Enter, or click the check button, to save.

2. Description (Point 1, Figure 3, right) - Click Add a description to edit the Scheduled Action description. Enter a detailed explanation of the action and click the check button to save.

3. When/Event (Point 2, Figure 3, right) - Click the When header or the Event button. In the right panel, select the event that will trigger the action. See Events, below for more information.

   1. Ignore events caused by JMWE post-functions and actions - Check this box to prevent the Event-based action from triggering when another JMWE post-function or action runs.

   2. Ignore events caused by Jira Automation and other apps - Check this box to prevent the Event-based action from triggering when the event is caused by a native Jira Automation or other app.

4. If Scope/Projects (Point 3, Figure 3, right) - Click the If Scope header or the Projects button to configure which projects will trigger the Event-based Action; only events on issues within the selected projects will trigger the action. See Projects and Issue Types, below, for more information.
   If you do not select a specific project(s), issues from all projects will trigger the action.

5. Issue Types (Point 4, Figure 3, right) - Click the Issue Types button to configure which issue types will trigger the Event-based Action. See Projects and Issue Types, below, for more information.
   If you do not select specific issue type(s), all issue types will trigger the action.

   1. Only apply to issues that match a JQL filter - Check this box to use a JQL query to filter the issues that should trigger the action.

   2. Only apply to issues that match a Nunjucks condition - Check this box to use a Nunjucks condition to filter the issues that should trigger the action.

6. Then/Post-functions (Point 5, Figure 3, right) - Click the Then header or the Post-functions button. In the right panel, select a post-function from the list to add the first post-function, or click Add post-function to add additional post-functions. See Post-functions, below for more information.

   1. Skip subsequent post-functions if a post-function encounters and error - Check this box to stop the execution of the Event-based Action if any of it’s post-functions encounter an error.

Events

Nearly any issue event can trigger an Event-based Action; the Event configurations determine which specific event will trigger the action.

The following events are able to trigger an Event-based Action:

• Issue Created (default option) - Triggered when a new issue is created, including when an issue is cloned.

• Issue Updated - Triggered when an issue is modified, such as being edited or transitioned.

• Issue Deleted - Triggered when an issue is deleted.

• Issue Commented - Triggered when a comment is added to an issue.

• Comment Updated - Triggered when a comment is updated on the issue.

• Comment Deleted - Triggered when a comment is deleted from the issue.

• Issue Transitioned - Triggered when a transition is performed on an issue. You can optionally filter the source and/or destination statuses of the transition.

• Issue Field Value Change - Triggered when one of the fields you have selected is modified on an issue.

• Attachment Created - Triggered when an attachment is added to an issue.

• Attachment Deleted - Triggered when an attachment is deleted from the issue.

• Issue Link Added - Triggered when an issue link is added to an issue.

• Issue Link Deleted - Triggered when an issue link is deleted from an issue.

• Work Log Created - Triggered when a worklog entry is added to the issue.

• Work Log Updated - Triggered when a worklog entry is updated on the issue.

• Work Log Deleted - Triggered whenever a worklog entry is deleted from the issue.

• Work Started on Issue - Triggered when the ‘Work started on issue’ system event fires during a transition.

• Work Stopped on Issue - Triggered when the ‘Work stopped on issue’ system event fires during a transition.

• Issue Assigned - Triggered when an issue is assigned. This can be triggered in two ways:

  • The ‘Issue assigned’ system event fires during a transition.

  • An issue is assigned or reassigned. Note: this event will not trigger if an issue is unassigned (i.e. the Assignment field is empty).

• Issue Resolved - Triggered when an issue is marked as Resolved.

• Issue Closed - Triggered when an issue is marked as Closed.

• Issue Reopened - Triggered when an issue is reopened.

• Issue Moved - Triggered when an issue is moved from one project to another.

Projects and Issue Types

Configuring which projects and issues types will trigger your Event-based Action both work the same way. You can use the pull-down menu at the top of their list to browse the list, or start typing to search for specific projects and issue types. Check the box next to the project or issue type to add it; click the X next to its name in the list to remove it.

Alternately, you can click Select Projects/Select Issue Types to open a window listing all of your Jira projects or issue types (Figure 4, right). Select or deselect the projects or issue types and click Add.

You can further filter the issue types that will trigger your action by using the JQL and Nunjucks filters. When either of these boxes are checked, a new field will appear - JQL or Nunjucks. Click these fields to open the JQL Filter/Nunjucks expression window, where you can enter the query or template and preview its results. Click Save to save the query or template and apply it to the action.

For more information on using JQL queries, see Using Jira Expressions.

For more information on using Nunjucks, see Using Nunjucks Templates.

Post-functions

For each issue included in the Event-based Action (see Projects and Issues, above), the configured post-functions will run in the order in which they are listed.

Add a post-function

1. In the right panel, click Add post function at the top of the panel.

2. Select a post-function from the list and click Add. You can search for the post-function by name using the Search field at the top of the list.

3. The post-function configuration window will open. Configure the selected post-function as needed, then click Save. See Post-functions for more details on all of the available post-functions.

Modify a post-function

You can reorder post-functions using the Up ( ) and Down ( ) buttons to the left of the tile. You can edit, delete, or duplicate any post-function by expanding the tile using the arrow ( ) to the right (Figure 5, right).

The expanded tile includes:

• the post-function name

• the post-function ID (this can be used in the JMWE Logs Administration page to filter the logs for the post-function)

• a brief description of the configuration.

The bottom of the expanded tile includes actions buttons:

1. To enable or disable a post-function, use the Enabled/Disabled toggle.

2. To edit the selected post-function, click Edit ( ).

3. To remove the post-function, click Delete ( ).

4. To copy the post-function, click Duplicate ( ).

Pass variables within a sequence

It is possible to pass data from one post-function to all subsequent post-functions within a Scheduled Action by using the {% setContextVar %} Nunjucks tag. When using a Build-your-own (scripted) post-function, the variable can be set anywhere within your script; when using other post-functions, the most common place to set a variable is in the Conditional Execution configuration.

• context: Holds all the context variables added in the current post-function. For example, if you create a context variable myVar in the first post-function of the sequence:

  {% setContextVar myVar = "a value" %}

  This variable will then be available to all its subsequent post-functions as:

  {{ context.myVar }}

   

Variables specific to the Create Issue post-function

• newIssueKey: Stores the issue key of the last issue created by a Create Issue(s) post-function in the action. You can access it as:

  {{ context.newIssueKey }}

   

• newIssueKeys: Stores an array of the keys of all the issues created by any Create Issue(s) post-function in the action. You can access the created issues from

  {{ context.newIssueKeys }}

  For example: to add a comment on the current issue with the keys of the issue created

  Issues created are: {{ context.newIssueKeys | join(",") }}

You can access the information of a specific issue using the issue filter. For example: To get the assignee of the issue created by the Create Issue(s) post-function

Pass context variables to an Event-based action

Variables specific to the current transition

If a post-function for the acton is run during a transition, information about the transition is accessible.

Access these variables using the prefix context.. For example:

This returns ID of a transition. The following information is available:

• transition.transitionId: Stores the ID of the transition.

• transition.transitionName: Stores the name of the transition.

• transition.from_status: The status from which the current transition starts.

• transition.to_status: The status to which the current transition leads.

• transition.workflowName: The name of the workflow to which the transition belongs.

• transition.workflowID: The ID of the workflow to which the transition belongs.

Variables specific to Comments

If the post-function is run during a transition, any comment that was entered on the transition screen is available. 

The newly created comment is available if the post-function is run during an action triggered by an Issue Commented event.

• context.comment.body: The body of the comment, as text with wiki markup.

• context.comment.created: The date/time the comment was created.

• context.comment.author.accountID: The account ID of the author of the comment.

• context.comment.author.displayName: The display name of the author of the comment.

• context.comment.jsdPublic: Determines if the comment is shared with Customers (for Jira Service Management projects).

Variables specific to Attachments

If the post-function runs as part of an Event-based Action listening to the attachment_created or attachment_deleted event, the attachment added or deleted is available through the context.attachment variable.

Access these variables using the prefix context.. For example:

This returns ID of an attachment. The following information is available:

• attachment.filename: Stores the filename of the attachment.

• attachment.id: Stores ID of the attachment.

• attachment.created: The date/time the attachment was created.

• attachment.size: The size of the attachment.

• attachment.mimeType: The mime-type of the attachment.

• attachment.author.accountId: The account ID of the user adding the attachment.

• attachment.author.displayName: The display name of the user adding the attachment.

Variables specific to Issue Links

If the post-function runs as part of an Event-based Action listening to the issue_link_created or issue_link_deleted event, the issue link added or deleted is available through the context.issueLink variable.

Access these variables using the prefix context.. For example:

This returns the issue link type of the link being added. The following information is available:

• issueLink.sourceIssueId: The issue ID of the source issue of the issue link being added or deleted.

• issueLink.destinationIssueId: The issue ID of the destination issue of the issue link being added or deleted.

• issueLink.issueLinkType.name: The issue link type of the issue link being added or deleted.

Variables specific to Work Log Links

If the post-function runs as part of an Event-based action listening to the worklog_created, worklog_updated, or worklog_deleted event, the worklog data is available through the context.worklog variable.

Access these variables using the prefix context.. For example:

This returns the date and time of when the worklog was created. The following information is available:

• worklog.timeSpent: Work Log string added/updated/deleted.

• worklog.timeSpentSeconds: Work Log in seconds added/updated/deleted

• worklog.comment: Comment added/updated with the Work Log.

• worklog.created: The date/time the worklog was created.

• worklog.updated: The date/time the worklog was updated.

• worklog.started: The date/time the worklog was started.

• worklog.author.accountId: The accountID of the user adding the worklog.

• worklog.author.displayName: The display name of the user adding the worklog.