Jira workflow post function (preview)

The jira:workflowPostFunction module creates a workflow post function that can be configured on workflow transitions in company-managed projects ( see: Advanced workflow configuration).

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

A function must be declared in the manifest and configured for a given post function module. It is then invoked after every transition to which the post function has been added, with the post function event as an argument. If multiple post functions are added to a transition, the execution order is not guaranteed.

Lambda function

Whenever an issue is transitioned and an app-registered Forge workflow post function is assigned to the transition, the function declared in the manifest is executed.

A function must be declared in the manifest and configured for a given post function. It is then invoked after every transition to which the post function has been added. When the function is invoked, an argument is passed to it with the following information about the transition.

Retries for post functions work in the same way as product event retries. You can request a retry for a function invocation by returning an InvocationError object, defined in the @forge/events package.

Payload

The payload is the same payload included in post function event. Due to the data sent to the function from Jira, it is necessary to include OAuth scopes in the app manifest: read:jira-work and manage:jira-configuration.

Fetching additional data

You can fetch additional data not included in the argument passed to the lambda function using the Product Fetch API from the @forge/api package.

Sample resources:

• Get comments by ID to get the details of a comment if it’s been added on transition.
• Get changelogs by ID to get a list of field value changes that occurred on transition.

Adding post function configuration with custom UI

Workflow post function behavior often requires some configuration. For 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 properties in the manifest allow you to declare custom UI resources that will show:

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

The create and edit pages should present a form with configuration items relevant to the post function. In order to persist this information in Jira, the page needs to use the workflowRules API.

Note: the maximum size of post function configuration is 100 kB.

The config context variable is stored under the extension.postFunctionConfig key in the context object returned from the getContext API in the custom UI bridge.

Post function configuration is also included in the post function event.

Example

To create a post function that displays a custom UI, declare it in the manifest as follows:

1
2
jira:workflowPostFunction:
  - key: my-forge-workflow-post-function
    name: Jira workflow post function example
    description: This post function will be executed after issue transition.
    function: my-postfunction
    edit:
      resource: edit-resource
    create:
      resource: create-resource
    view:
      resource: view-resource
resources:
  - key: create-resource
    path: static/create/build
  - key: edit-resource
    path: static/edit/build
  - key: view-resource
    path: static/view/build
function:
  - key: my-postfunction
    handler: index.postfunction
permissions:
  scopes:
    - manage:jira-configuration
    - read:jira-work

To get product context in the create, edit, and view resources defined in the manifest, use the view.getContext function.

1
2
import { view } from '@forge/bridge';

function App() {
    const [context, setContext] = useState();
    const [config, setConfig] = useState();

    useEffect(() => {
        view.getContext().then(ctx => {
            setContext(ctx);
            setConfig(ctx.extension.postFunctionConfig)
        });
    }, []);
}

To save user input to the config context variable, pass the callback function returning stringified JSON to the workflowRules.onConfigure function.

1
2
import { workflowRules } from '@forge/jira-bridge';

const onConfigureFn = async () => {
    var config = {
        'key': 'value'
    };

    return JSON.stringify(config);
};

// calling onConfigure from an async function
try {
    await workflowRules.onConfigure(onConfigureFn);
} catch (e) {
    // Handle the error.
}

// calling onConfigure from a non-async function
workflowRules
    .onConfigure(onConfigureFn)
    .catch(e => {
        // Handle the error.
    });

To implement the actual post function logic in the src/index.js file, declare the function that will be invoked:

1
2
import api, { route } from '@forge/api';

export const postfunction = async event => {
    console.log(`Running post function for issue ${event.issue.key}`);

    if (event.comment) {
        const response = await api
            .asApp()
            .requestJira(route`/rest/api/latest/issue/${event.issue.id}/comment/${event.comment.id}`);
        const commentData = await response.json();
        console.log('Comment data', commentData);
    } else {
        console.log('Comment absent');
    }

    if (event.changelog) {
        const response = await api
            .asApp()
            .requestJira(
                route`/rest/api/latest/issue/${event.issue.id}/changelog/list`,
                {
                    method: 'POST',
                    body: JSON.stringify({'changelogIds': [parseInt(event.changelog.id)]})
                }
            );
        const changelogData = await response.json();
        console.log('Changelog data', changelogData);
    } else {
        console.log('Changelog absent');
    }
}

Properties

Known issues

• FRGE-709: if the comment has been added on the transition with restricted visibility, the post function won't be able to fetch it using the Product Fetch API.