Create an Integration

Owned by Peter Atthem
Last updated: 2023-08-28 by Rickard Atthem
6 min read

Creating integration flows in Jira have never been easier!

Extend, automate and integrate Jira with other systems or use it to automate JIRA tasks via the REST API.

Find the App!

Goto “Apps” → “Integrations Hub” → “Integrations”

 

View your integrations / create new integration

Click “Integrations” from the menu.

Click the integration name to edit, click the “Create integration” button to create a new integration flow.

Setting Up an Integration Process (Flow)

Think of integrations as a series of steps, which we call 'flows'. Each flow consists of one or more actions. An action is a specific task that accomplishes something. For instance, one action might retrieve data from a system, while the next one updates a Jira issue using that data. Actions are executed in sequence, with each one waiting for the previous one to complete.

Details

Set a name and a description (optional) for your integration flow

Trigger

A trigger is what starts or executes an integration flow. There are three main types of triggers:

  1. Jira Issue Events: These are specific events that occur within Atlassian Jira, like when an issue is created or updated.

  2. Incoming Webhooks: These allow other systems to initiate the integration flow by sending an HTTP post request.

  3. Scheduled Jobs: These are set to run at specific times based on Unix cron settings.

In essence, triggers act as the catalyst to activate and run your integration processes."

Issue event triggers

Select one or more Jira Issue events (e.g., issue creation, updates, status transitions) to trigger this flow. Remember to add a JQL filter.

Important: A JQL filter is mandatory. Without it, the integration flow won't activate, as per Atlassian's strict requirement.

Incoming Webhooks

Webhooks allow external systems to initiate the integration flow by sending an HTTP POST request.

  1. Select "Incoming Webhook" if you want other applications to trigger this integration flow.

  2. Click "save" to obtain your unique trigger URL.

  3. To activate the flow, post data to the provided URL. Any data within the POST body or query parameters will be processed by the flow.

  4. The service will respond with "HTTP 200 OK" once the data is successfully received."

Scheduled Triggers

These are triggers that automatically run at preset times, similar to how alarms are set. They use Unix cron settings to determine when to activate."

Actions in Integration Flow

Definition: Actions are "integration steps." A flow can contain numerous actions. They run sequentially, with each action only starting after the preceding ones (including children) have finished. Parent actions always execute before their child actions.

Adding a New Action:

  1. Click the “+ Add new action” button.

  2. Select the type of action:

    • Top-level action: Executes when an event or webhook is triggered.

    • Child action: Executes after its parent completes. Can process data from its parent, like an API call response.

    • Web Action: A generic action for any API endpoint.

    • Jira Template Action: Options include creating, updating, or commenting on a Jira issue.

Action Settings

Your action settings comprise four main tabs:

  1. Connection: Configure how the action interfaces with other platforms or services.

  2. Condition: Define the scenarios in which you want the action to run. Conditions can be mixed using "AND" (all conditions must be met) or "OR" (meeting any condition is sufficient).

  3. Variables: Assign names to specific data bits to reuse in different parts of your setup.

  4. Advanced: Define specific functionalities for each action, such as pagination or iteration.

 

Connection Tab Details:

  • API Endpoint:

    • Choose the request method.

    • Enter the API's URL. You can include variables from Jira events or webhook data using handlebars/mustache templates.

      • Example: {{baseUrl}}/rest/api/3/issue/{{issue.key}}/comment

  • Authorization: Select the authentication method required with the API. This is setup on the credentials page. For Jira, choose the implicit “Jira authorization token”

  • HTTP Headers: Define headers required by the API. Some default headers are pre-filled, adjust as needed.

  • Jira Utilities: Use this tool to find the handlebars/mustache template for accessing Jira fields.

  • Body: Define the JSON payload sent to the API. Variables within can be replaced dynamically using mustache/handlebars expressions.

Condition Tab Details:

Specify when the action should run based on the outcomes of previous steps or specific scenarios.

  • Data condition: Depends on the data received from the previous action or the trigger.

  • HTTP status condition: Depends on the HTTP status of the previous action. Note, only applicable to actions that have a parent.

 

Variables Tab Details:

  • JSON Path Variables: Create variables to extract specific data from JSON payloads of incoming webhooks or data from parent actions. Normally, all payload data can be accessed using mustache dot notation.

You can access these variables by using handlebars (mustache) expressions {{ user.name }} or {{ user.address.street }}

Example: For the payload { "user": { "name": "Big Helmet", "address": { "street": "Outer space" }}}, use {{ user.name }} or {{ user.address.street }}.

  • Javascript Variables: Define custom JS variables for sophisticated data extraction. Scripts can access the current scope and must return a value.

 

Advanced Tab Details:

  • Pagination: Ensures comprehensive data retrieval. The system will continue to fetch data until:

    • No new data is received.

    • Data duplicates appear.

    • The system receives an "not modified" notification. (304 Not Modified)

    • A predefined stopping point is reached. (Json path)

  • Iterator: Works like a highlighter, focusing on a list in the retrieved payload data. Provide the JSON path to your desired list, and the action processes each item sequentially.

Enabling the Flow

Activate the flow using the 'Enable' toggle, found at the top right of the flow page or directly from the integrations list page.

Testing the Flow

  1. Click the play icon to initiate a test run of the flow.

  2. Simulate a real trigger by inputting data as you'd expect the flow to receive during regular operations.

  3. Monitor the flow's performance in the “Execution Log” section where results will be displayed."

Previewing the Action request using a Jira Issue

To see how the action request will look loke with a Jira Issue, click the "eye" icon beside the "hamburger" menu. Then, input a Jira issue for the preview.

Variables in the Integration Scope

When working with integrations, the scope contains data originating from two primary sources:

  1. Triggering Request: Data that is part of the initial request that triggered the integration.

  2. Parent Actions: Data inherited from preceding actions in the integration flow.

These data are automatically added to the scope, making them readily accessible. You can retrieve these variables using the mustache syntax.

Special Note for Issue Events: When dealing with issue events, the issue data is always present in the scope. You can access it using {{ issue }}.

Default Variables in the Integration Scope

When building integrations, some variables are automatically available within the scope. You don't need to define these, as they are provided by default:

  • {{ baseUrl }}: Represents the URL of your instance.

  • {{ now }}: Indicates the current date and time, presented as string in format "YYYY-MM-DDTHH:mm:ss.sssZ".