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-]+$
Description

A key to identify this module.

This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

Keys must only contain alphanumeric characters and dashes.

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key. For example, an add-on which looks like:

1
2
3
4
5
6
7
8
{
    "key": "my-addon",
    "modules": {
        "configurePage": {
            "key": "configure-me",
        }
    }
}

Will have a configuration page module with a URL of /plugins/servlet/ac/my-addon/configure-me.

name

Type
i18n Property
Required
Yes
Description

A human readable name.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
{
  "value": "My text"
}

Properties

value
Type
string
Required
Yes
Description

The human-readable default value. This will be used if no translation exists.

i18n
Type
string
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

triggered

Type
URL
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"
    }
}

Properties

url
Type
string
Required
Yes

create

Type
URL
Description

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

Properties

url
Type
string
Required
Yes

description

Type
i18n Property
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.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
{
  "value": "My text"
}

Properties

value
Type
string
Required
Yes
Description

The human-readable default value. This will be used if no translation exists.

i18n
Type
string
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

edit

Type
URL
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

Properties

url
Type
string
Required
Yes

view

Type
URL
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

Properties

url
Type
string
Required
Yes