In a prior blog post, we described how to authenticate an Amplify Integration Builder Jira Cloud Connector for creating flows that integrate with Jira. In that post, we enabled event webhooks but really didn’t describe how to take advantage of, and configure, event webhooks.

The reason we even want to enable and use event webhooks is so that we can trigger our Integration Builder flow when an event occurs in Jira (e.g. an Issue is created or modified).

Jira Cloud Connector event webhooks

In this blog post, we’ll take a look at Jira Cloud Connector event webhooks and how to (optionally) configure them in Jira.

Generate a Jira API Token

In order to authenticate our Integration Builder Jira Cloud connector we’ll use basic authentication, which requires a Jira API Token to use as the password.

* In your Jira instance, click on the gear icon and select Atlassian Account Settings and select the Security menu item:

* Click on Create API Token and give your token a name and then copy your token as you won’t have access to it again and you will need it to authenticate the Integration Builder Jira Cloud Connector:

Authenticate an Integration Builder Jira Cloud Connector with Event Webhooks

* In Integration Builder, click on Connectors, find the Jira Cloud Connector and click Authenticate

* Give your connector a name, make sure Authentication Type is set to Basic and enter your Jira username and use the Jira API Key created above as your password and provide the Jira server URL:

* Toggle on the Events Enabled switch and make sure that webhooks is selected for Event Type. Leave all the other fields blank:

Note that the user account used in the connector needs Jira Admin rights for Integration Builder to set up and enable event webhooks in Jira.

* Click on the Create Instance button to authenticate.

* Go to the API Docs for the connector and make sure you can exercise the APIs as described in the prior blog post.

* You can see the webhook setup in Jira by clicking on the Jira Gear icon and then select System. Then scroll down the menu to WebHooks and see the webhook you just created:

Test your Connector Webhook Events

In order to test our connector events, we’ll create a new Flow and enable a connector event trigger on the flow as follows:

* Create a new flow and click on Manage -> Manage Variables and add a connector instance variable for our connector. I called mine jira:

* Click on the Trigger step and add a new trigger of type Event Trigger and select the connector instance variable you created in the previous step and click on Save:

* Add a JS Script step to the trigger with the following contents in order to console log the trigger:

console.log(trigger);
done({});

* Click on the three dots and select Create Instance

* Enter the name and select the connector we authenticated above and click Create Instance

* Enable Debug Logging in your flow and go to your Jira instance and create an issue

* Review your flow executions and you should see an execution corresponding to the new Jira Issue

A portion of the trigger body is shown below for reference:

{
  "eventId": "AXvQSObPo4s6E-yPZhkH",
  "instanceId": 2730780,
  "formulaTriggerType": "event",
  "allowConcurrentExecutions": true,
  "body": {
    "message": {
      "eventId": "AXvQSObPo4s6E-yPZhkH",
      "instanceName": "JIRA LBG Event",
      "instanceTags": [
        "Jira LBG Event"
      ],
      "raw": {
        "issue": {
          "self": "https://lbrenman.atlassian.net/rest/api/2/10488",
          "id": "10488",
          "fields": {
            "statuscategorychangedate": "2021-09-10T11:17:23.269-0400",
            "fixVersions": [],
            "resolution": null,
            "lastViewed": "2021-09-10T11:17:23.286-0400",
            "priority": {
              "name": "Medium",
              "self": "https://lbrenman.atlassian.net/rest/api/2/priority/3",
              "iconUrl": "https://lbrenman.atlassian.net/images/icons/priorities/medium.svg",
              "id": "3"
            },
            .
            .
            .
            "customfield_10010": null,
            "customfield_10011": "Epic Test",
            "customfield_10012": {
              "self": "https://lbrenman.atlassian.net/rest/api/2/customFieldOption/10016",
              "id": "10016",
              "value": "To Do"
            },
            .
            .
            .
          "key": "ET-7"
        },
        "user_id": "admin",
        "issue_event_type_name": "issue_created",
        "changelog": {
          "items": [
            .
            .
            .
          ],
          "id": "11012"
        },
        "user_key": "admin",
        "webhookEvent": "jira:issue_created",
        "user": {
          "accountId": "5bb2679d672747437cf74547",
          .
          .
          .
          "displayName": "Leor Brenman",
          "accountType": "atlassian",
          "active": true,
          "self": "https://lbrenman.atlassian.net/rest/api/2/user?accountId=5bb2679d672747437cf74547",
          "timeZone": "America/New_York"
        },
        "timestamp": 1631287043029
      },
      "userId": 21107,
      "elementKey": "jira",
      "accountId": 18281,
      "companyId": 7861,
      "instanceId": 2730780,
      "instance_id": 2730780,
      "events": [
        {
          "date": "2021-09-10T15:17:22Z",
          "elementKey": "jira",
          "eventType": "CREATED",
          "hubKey": "helpdesk",
          "objectId": "10488",
          "objectType": "issue"
        }
      ]
    }
  },
  "type": "event",
  "event": {
    "date": "2021-09-10T15:17:22Z",
    "elementKey": "jira",
    "eventType": "CREATED",
    "hubKey": "helpdesk",
    "objectId": "10488",
    "objectType": "issue"
  }
}

An important part of the trigger is the “event” object:

{
  "date": "2021-09-10T15:17:22Z",
  "elementKey": "jira",
  "eventType": "CREATED",
  "hubKey": "helpdesk",
  "objectId": "10488",
  "objectType": "issue"
}

You can use this to determine if the event relates to an issue or project, etc… And what type of event it is (CREATED, UPDATED,…) as well as the Id of the object so you can retrieve it via a Connector API Request step later in your flow.

Filter Events

At this point, our Jira Connector will trigger the flow on ANY activity in Jira. However, your flow may only be relevant to newly created issues in a particular Jira software project. The first thing you should do is add steps to the beginning of your flow to inspect the trigger data and make sure that it is only processing events intended for the flow.

The next thing you can do is edit the Webhook settings in Jira to only generate events you care about.

Let’s tackle the first part and make sure our flow only processes events intended for it.

Filtering Events in the Flow

As an example, consider a flow that is intended to detect changes in an Epic (issue of type Epic) and capture metrics related to issues in the Epic. For example, total story points, total number of issues, … Furthermore, we only want to do this for certain Jira software projects.

The following flow fragment accomplishes this:

* The first thing the flow does is make sure we only process events of type Issue. This is achieved using the “isIssue” JS Filter Step with the following JavaScript:

done(trigger.event.objectType === 'issue');

* The next thing the flow does is make sure that the event pertains to a project we are monitoring. In this case, the flow has a flow instance variable called jiraProjectKeys which is an array of Jira project keys:

Note that in the Flow Instance example above, I am monitoring one project, ET

This is achieved using the “isWatchedProject” JS Filter Step with the following JavaScript:

let projectKey = trigger.body.message.raw.issue.key.split('-')[0];

done(config.jiraProjectKeys.includes(projectKey));

The code above extracts the project key from the issue key (issues.key). For example, issues in Jira software project ET have the form ET-xxx. Then it checks to see if that project key is in the project key array instance variable (config.jiraProjectKeys).

* Since an Epic is an issue, and its child issues are obviously issues, we need to make sure we are processing the Epic. That is handled in the last JS Script Step, processEpic with the following JavaScript:

let epicId;

if(trigger.body.message.raw.issue.fields.issuetype.name === 'Epic') {
  epicId = trigger.body.message.raw.issue.key;
} else {
  epicId = trigger.body.message.raw.issue.fields[config.globals.epicLinkCustomFieldName]
}

console.log('Process Epic: '+epicId);

done({});

The code above checks to see if the issue is an Epic. If it is, then the Epic Id is the issue Id/key. If not, then we need to find the issue’s parent link/Id. The parent Epic Id is in a custom field related to “Epic Link”. Since it’s a custom field we need to call the Jira connector’s GET /fields API to determine the custom field name. You can review the flow for more details.

Now your flow can proceed with the Epic Id.

At this point, your flow will only process desired events in desired projects. However, Jira will still trigger the webhook (which will trigger your flow) on ALL events. In the next section, we’ll look into how we can limit the events related to the Jira Webhook.

Filter Jira Webhook Events

In order to restrict the generated webhook events that Jira will generate, you can go to the Jira webhook page as described above by clicking on the Jira Gear icon and then select System. Then scroll down the menu to WebHooks and see the webhook that was created by the Integration Builder Jira Connector above.

We won’t cover everything that can be changed on this page but let’s describe a few.

Limit Webhook Events to Specific Jira Software Projects

In order to only have webhook events generated for specific projects, we will need to edit this page and modify the Issue related events field. This field uses JQL (Jira Query Language).

For example, to restrict webhook events to the Jira Software Project “Epic Test”, scroll down to the bottom of the webhook page and select Edit. Then enter project=”Epic Test”. Autocomplete will help you complete your JQL by providing the list of projects after you type project=.

Then scroll down and press Save.

Now, any modifications to issues in other projects will not generate webhook events.

Limit Webhook Events to Issues Only

By default, Jira will generate webhook events for Project, Issue and User modifications. If we want to limit to only Issues, then click Edit on the Jira Webhook page and clear all checkboxes for User related events and I as follows and press Save:

That’s it, we’re done. Our flow will only process Jira event webhooks it is designed for and Jira will only generate those event webhooks that we care about.

## Summary

In this blog post, we revisited how to authenticate an Integration Builder Jira Cloud Connector and enable webhook events. Furthermore, we described how a flow that is triggered by connector events may want to filter the events for the task at hand.

Then we looked at the Jira Webhook configuration screen to limit the generated webhook events to those that our flow is designed to process, thereby reducing the chance for flow errors during flow execution.