Jira integration

Pulse integrates with Jira Cloud to receive data about:

• Issues - necessary to calculate Lead time and Cycle time.

• Incidents - necessary to calculate the following Accelerate metrics:

  • Time to recover

  • Change failure rate

Setting up the Jira integration

Note

• A Jira administrator must set up the integration, as Pulse will only have access to Jira resources that the user setting up the integration has access to.
• You can only integrate one Pulse organization with each Jira instance.
• If you want to report incidents using Jira, review the details of the incident detection strategy before you proceed with the integration setup.
• See below the permissions that Pulse requires from your Jira instance.

To set up the Jira integration:

1. On Pulse, expand Integrations and select Jira.

2. Click Install Jira App and follow the instructions on the Jira UI to install the app. You must be a Jira administrator to proceed with this step.

   

3. Confirm that Pulse successfully connected the integration to Jira. If there is an error please contact support.

   

4. Choose the strategy to detect incidents that best fits your workflows. See the section below for a detailed description of each option.

   

5. Click Complete setup.

Your Jira integration is now complete. Pulse will start loading your data for the last 90 days.

Automatic incident detection strategies

The Pulse Jira integration can detect incidents automatically using the issues assigned with the label Incident.

You can also choose not to detect incidents via Jira.

Use issues assigned with the label "Incident"

• Pulse considers an incident every completed Jira issue assigned with the label Incident (case-insensitive). An issue is completed when its status maps to the Done status category in Jira. See below how Pulse collects issue status data from Jira.

• Pulse associates an incident to one or more systems matching the values in the Component(s) field of the Jira issue (case-sensitive).

  • If the Jira issue is set with more than one component, Pulse creates an incident for each existing system that matches a component name, ignoring the remaining components that don't exist in Pulse as a system.

  • If the Component(s) field in the Jira issue is empty, or none of the components exist in Pulse as a system, Pulse creates an incident and associates it with the system _unknown_.

• The incident creation date is the timestamp when the Jira issue was created, while the incident resolution date is the timestamp when the Jira issue was last completed.

• Pulse creates new incidents when the following updates are performed in Jira:

  • An issue assigned with the label Incident is completed. Pulse creates one or more incidents, depending on the values in the Component(s) field.

  • A completed issue is assigned with the label Incident. Pulse creates one or more incidents, depending on the values in the Component(s) field.

  • A new component that matches an existing system is added to a completed issue assigned with the label Incident. Pulse creates a new incident associated with the matching system.

• Pulse deletes an existing incident when the following updates are performed in Jira:

  • The corresponding issue is re-opened.

  • The label Incident is removed from the corresponding issue.

  • A component that matches an existing system is removed from the corresponding issue. Pulse deletes the incident for that system.

  • The corresponding issue is deleted.

Important

After completing the Jira integration setup, Pulse starts loading your incident data for the last 90 days. Therefore, before you perform the integration setup, make sure the corresponding Jira issues follow the rules described above, so Pulse can load your historical data correctly. Pulse will only create incidents for the completed Jira issues that are assigned with the label Incident, and associates them with the systems matching the values in the Component(s) field as described above.

Don't detect incidents via Jira

• Pulse doesn't detect incidents automatically using Jira events.

  Choose this option if you want to send to Pulse the information about your incidents using another Pulse integration - GitHub one-click integration or Bitbucket one-click integration, PagerDuty one-click integration, Pulse CLI, or Ingestion API - or if you don't want Pulse to track incidents data.

Collected data

The table below lists the data that the Jira integration collects from your Jira instance and the metrics that Pulse displays on the dashboards, calculated using the collected data.

Data collected from Jira	Details	Used in
Issues	Issue data includes all issue status transitions. To detect the state of an issue, Pulse considers all the statuses under each Jira status category: An issue is not in progress when its status maps to the To-do status category, represented by the grey color in Jira. For example, BACKLOG, WAITING FOR APPROVAL, or any other custom value. An issue is in progress when its status maps to the In-progress status category, represented by the blue color in Jira. For example, IN PROGRESS, DEVELOPING, IN REVIEW, or any other custom value. An issue is completed when its status maps to the Done status category, represented by the grey color in Jira. For example, DONE, CLOSED, DECLINED, or any other custom value.	Lead time and Cycle time on the Lead & Cycle time dashboard
Projects	Project data includes the name of the Jira projects.	Filters on the Lead & Cycle time dashboard
Issue types	Pulse groups issue types per name since in Jira you can have the same issue type name in different projects. This means that, for example, the Pulse UI will group different issue types named Subtask and Sub-task under the name of the issue type that was processed first. For all effects, these issue types are the same for Pulse.	Filters on the Lead & Cycle time dashboard
Issues	Pulse detects incidents from issue data according to the defined strategy.	Time to recover and Change failure rate on the Accelerate Overview dashboard

Which permissions does Pulse need from Jira?

Pulse requests only the necessary permissions/scopes from your Atlassian account to collect issues data from your Jira instance and keeps your information secure. See below the detailed list of permissions.

Classic scope	Description
read:me	Pulse retrieves the email of the user installing the integration.
read:jira-work	Pulse requires this scope to perform the following actions: List all issue statuses associated with the active workflows to identify the transitions of the issue status, required to detect when an issue is closed or re-opened. Get the details of an issue for real-time processing. List projects to use on dashboard filters. List the closed issues of a project for historical data loading.
manage:jira-webhook	Pulse uses Jira webhooks to retrieve data in real time.

See also

• Lead and Cycle time metrics
• Time to recover
• Change failure rate