Writing post functions

How does it work?

A Universal Post Function runs some actions after a transition if the post function’s Jira Expression evaluates to true.

You can write post function actions using any sequence of the following three operations:

• Jira REST API calls

• Variable definitions (e.g. to pass information from one REST call to another)

• Writing to the application log with log(...);.

Each of these statements must end with a semicolon.

You can use variables from the post function event payload (e.g. issue ID, transition details, changes that occurred during the transition). These can be accessed either directly, e.g. issue.id, or within a string, e.g. "${issue.id}".

You can also add notes by writing a comment after the // symbol at the start of a line or after a statement.

1. Jira REST API Calls

You can trigger network calls to most Jira REST API endpoints. Define a REST API call with the following parts:

1. The HTTP method name, i.e. GET, POST, or PUT

2. The URL of the endpoint as a quoted string, possibly including replacement fields with ${...}

3. Optional: The request body JSON, if needed

Example

// Write a comment on the transitioned issue
POST "/rest/api/3/issue/${issue.id}/comment"
{
  "body": {
    "content": [
      {
        "content": [
          {
            "text": "My Comment Text",
            "type": "text"
          }
        ],
        "type": "paragraph"
      }
    ],
    "type": "doc",
    "version": 1
  }
};

Auto completion

You can use the auto-completion feature (ctrl + space) to help with the syntax, or to see which REST API calls are available.

For example, after typing POST, you will see a list of all POST endpoints which are available in your post functions. You can filter these results by typing which resource you would like to access, e.g. for issues:

For the selected endpoint, the helper link on the right shows the endpoint URI. Clicking the link will open the relevant documentation page in Atlassian’s Jira REST API documentation to show further information about the endpoint.

To select an endpoint from the auto-completion window, click on the entry, or select the entry with the arrow keys and press Enter.

2. Define Variables

You can define variables for use later in the post function. This is helpful, e.g. to capture the response of a REST API call. Variables can be used either directly, e.g. issue.id, or within a string, e.g. "${issue.id}".

Examples

Fetch the value of a custom field of the transitioned issue:

let customfield = GET "/rest/api/3/issue/${issue.id}?fields=customfield_10100";

Define a shorthand for some variable in the event payload:

let project_name = issue.fields.project.name;

Define a custom object

let myObject = { a: "some text", b: "some other text"};  // JavaScript-style object

3. Logging

You can write anything during the execution of the post function to the app logs. This can be useful for testing and monitoring.

Example

// Log the value of a custom field of the transitioned issue
let moved_issue = GET "/rest/api/3/issue/${issue.id}?fields=customfield_10100";

log("custom field value: ${moved_issue.fields.customfield_10100.value}");