Workflow Post Function

Post functions carry out any additional processing required after a Jira workflow transition is executed, such as:

  • updating an issue's fields
  • adding a comment to an issue

Your add-on needs to declare the URL that Jira will invoke with an HTTP POST after the transition is completed. Each POST will include the issue and transition details and the configuration of the workflow function. It will also include the authentication headers that allow the add-on to validate the authenticity of that request.

Often, the workflow post function will allow some degree of configuration of its behavior. As an example: You may want to react to a state transition only if the issue has a particular label, and you want the project administrator to configure that label. For this purpose, three additional URLs in the descriptor allow you to declare the pages that will show:

  • The form that is shown when a workflow post function is first created
  • The form that is shown when a workflow post function is edited
  • The read-only view or summary of the configuration

All URLs are relative to the base URL that is declared in the connect-container element of the descriptor.

Creating and editing a Post Function

The create and edit urls will need to present a form with relevant configuration for the post function. In order to persist this information with Jira, the page needs to include a snippet of Javascript to facilitate saving this data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
  AP.require(["jira"], function(jira) {
      // When the configuration is saved, this method is called. Return the values for your input elements.
      jira.WorkflowConfiguration.onSave(function() {
          var config = {
              "key": "val"
          };
          return JSON.stringify(config);
      });

      // Validate any appropriate input and return true/false
      jira.WorkflowConfiguration.onSaveValidation(function() {
          return true;
      });
  });

For more information, see the javascript API.

Example

For a full add-on example, see the workflow post function example add-on.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "modules": {
    "jiraWorkflowPostFunctions": [
      {
        "description": {
          "value": "My Description"
        },
        "view": {
          "url": "/view"
        },
        "edit": {
          "url": "/edit"
        },
        "create": {
          "url": "/create"
        },
        "triggered": {
          "url": "/triggered"
        },
        "name": {
          "value": "My Function"
        },
        "key": "workflow-example"
      }
    ]
  }
}

Properties

key

Type
string
Max length
100
Required
Yes
Pattern
^[a-zA-Z0-9-]+$

name

Type
object
Required
Yes

triggered

Type
object
Required
Yes
Description

The relative URL to the add-on resource that receives the HTTP POST after a workflow transition. It includes the authentication headers that enable the add-on to validate the authenticity of the request.

Your app must return a success status code in response to the HTTP POST request. If your app doesn't send a success status code the request will retry, as described in the webhook retry policy.

Contents of the HTTP POST

To understand the type of content that is sent to the add-on after a state transition, you can use the Connect inspector tool. The Connect inspector is a service that lets you generate a temporary Atlassian Connect add-on that you can install in your Cloud development environment to inspect the content of event messages.

Here is an example POST body. For brevity, some fields have been removed or truncated.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
{
    "configuration": {
        "value": "Configuration from the post function edit page"
    },
    "issue": {
        "fields": {
            "assignee": { },
            "attachment": [],
            "comment": { },
            "components": [],
            "created": "2013-11-18T17:56:23.864+1100",
            "description": null,
            "duedate": null,
            "environment": null,
            "fixVersions": [],
            "issuetype": { },
            "labels": [],
            "lastViewed": "2013-11-18T17:56:31.793+1100",
            "priority": { },
            "project": {
                "avatarUrls": { },
                "id": "10000",
                "key": "TEST",
                "name": "Test"
            },
            "reporter": { },
            "resolution": { },
            "resolutiondate": "2013-11-18T17:56:31.799+1100",
            "status": { },
            "summary": "The issue summary",
            "updated": "2013-11-18T17:56:23.864+1100",
            "versions": [],
            "votes": { },
            "watches": { },
            "workratio": -1
        },
        "id": "10000",
        "key": "TEST-1",
        "self": "http://issues.example.com/jira/issue/10000"
    },
    "transition": {
        "from_status": "Open",
        "to_status": "Resolved",
        "transitionId": 5,
        "transitionName": "Resolve Issue",
        "workflowId": 10000,
        "workflowName": "classic default workflow"
    }
}

create

Type
object
Description

The relative URL to the add-on page that allows to configure the workflow post function on creation.

description

Type
object
Description

The description of the workflow post function. This will be presented to the user when they add a new post function to a Jira workflow.

edit

Type
object
Description

The relative URL to the add-on page that allows to configure the workflow post function once it exists.

The edit URL can contain the following context parameters:

  • postFunction.id: The unique identifier of the post function
  • postFunction.config: The configuration value saved to Jira after calling WorkflowConfiguration.onSave

view

Type
object
Description

The relative URL to the add-on page that shows the read-only configuration or summary of the workflow post function.

The view URL can contain the following context parameters:

  • postFunction.id: The unique identifier of the post function
  • postFunction.config: The configuration value saved to Jira after calling WorkflowConfiguration.onSave