Description

Jira is a popular, highly customizable issue and project management tool.

Benefits

Better for You, Familiar for Them
By integrating Conveyor with Jira you can assign compliance work to your workforce in the tool they already use for their day-to-day duties. This saves you having to onboard users on to a new tool and enables your workforce to be productive with the tool they're already familiar with. Conveyor automatically creates tickets in Jira and syncs their status back when it's updated in Jira. This gives you the full picture of your compliance work in one place, no more digging through Jira when audit times comes.

Usage

After you've setup the integration (instructions below), you're ready to start assigning tickets in Jira through Conveyor.

First, create a Procedure. Proceed through the steps until you get to the status step. Here you're able to select your ticket's destination. The ticket can go to Conveyor or a Jira project you select from the dropdown. You can also edit a Procedure's destination after the fact.

Creating a new procedure connected to Jira.Creating a new procedure connected to Jira.

Creating a new procedure connected to Jira.

You can select any Person you track in Conveyor to be the assignee in Jira, whether they have a Conveyor user account or not. Conveyor will try to find this person by their name in Jira and assign them to the issue. If they are not found, the issue will not have an assignee. The created Jira issue will include the guidance, notes, and asset information from Conveyor. The issue is given two labels specifying it is from Conveyor and the Ticket Template which you can use to power Jira automations.

The reporter field can be set only if the last person who authorized the Jira integration in Aptible also has the MODIFY_REPORTER permission for the project in Jira. This permission is part of the default Administrator role in Jira projects. The reporter field will be set to the Person who created the ticket in Conveyor's corresponding Jira user. If the ticket was not created by a Person (example: created by an integration), then if the ticket has a Person Asset, the Asset Owner in Conveyor's corresponding Jira user will be set as the reporter. If neither a Person creator nor a Person Asset Owner have corresponding Jira users, the reporter will default to the last authorizer of the integration.

Jira issue created by Conveyor, automatically assigned.Jira issue created by Conveyor, automatically assigned.

Jira issue created by Conveyor, automatically assigned.

Tickets that are synced to Jira are not editable in Conveyor. A link to the Jira issue for a ticket is provided for your convenience. Conveyor will listen to changes in the Jira card's status and mark the ticket Closed when it is marked Done in Jira, giving you a single source of truth for all your compliance work in Conveyor.

A ticket synced to Jira in Conveyor.A ticket synced to Jira in Conveyor.

A ticket synced to Jira in Conveyor.

Status Syncing

The Jira integration pushes tickets to Jira and then listens for changes to its status. Jira has 3 types of statuses:

  • To Do (gray)
  • In Progress (blue)
  • Done (green)

You may have many statuses in your Jira, but they all are one of these three types. When Conveyor detects a change to the issue's status it reacts in the following ways:

  • When the new status is To Do or In Progress, the ticket is marked Open.
  • When the new status is Done, the ticket is marked Closed.
  • When an issue is deleted, the ticket is marked Cancelled.

In order for tickets to be tracked as complete in Conveyor you must have at least one Done status. For Jira Classic projects, you can manage this in Project Settings > Workflows. For Jira Next Gen projects, you can edit the columns on the Board page (the far right column is automatically your Done status).

Setup

📘

Which account should I use?

The Jira account integration can be set up as a human user or a service account. The benefit of the human user is you can sock puppet and have the tickets write as the security officer or a more senior team member to bring attention to the tickets. The drawback of a human user is that the person who set up the integration may not really be a logical reporter for some types of tickets. A service account will save one person from being inundated with updates for all tickets created by the integration. if you use a service account we suggest you manage the credentials similar to as you would a human user in a password wallet or similar, as the integration does request admin access. If you change you mind later, there should be no impact on already created tickets if you swap it out the account that has connected the integration.

  1. Login in to a Jira account with admin level permissions.
  2. Create an Application Link. Go to Jira Settings > Products > Application Links, enter https://app.conveyorhq.com/ into the text box, and click Create New Link. Jira may ask you about redirects or validating the domain, if so follow the on screen instructions to move past the validation.
  3. Fill in Conveyor as the application name in the following form and click Save. You do not need to fill out the rest of the form.
  4. You should now see a Conveyor item in the list. Click the pencil icon to edit it. Under the "Incoming Authentication" tab fill in the following values and click save:

Consumer Key: jira-oauth-production
Consumer Name: conveyor
Public Key:

-----BEGIN PUBLIC KEY-----
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDln4UuUZF3pHTLjlKqj95oPxXA
jxgSnUBPUyb226QXGxO04WCr8L9IghqBkHwPCIxQPyWfpFQEqkBEittgSXUg+Psn
w9pmqv3C2GKeV9tKcjhwOdunYnDgycTADw8zfmU2mrxmaRiUQb3vRGUcbDbWeCzR
eHlwk5GAyVSxxcqzfQIDAQAB
-----END PUBLIC KEY-----
  1. While logged in as an account owner, navigate to "Preferences" in the top right dropdown. Then, go to the "Organization Preferences" tab. Click "Add Integration" and select the Jira integration, and authorize Conveyor to connect Jira.

Troubleshooting

The most common problems when setting up the integration are:

  • Not creating an Application Link in Jira as described in the instructions.
  • Not using a Jira admin account.

If you receive an error message when trying to sync create your integrated tickets, please check the above items and contact [email protected] if the problem persists.


Did this page help you?