How do I set up my Jira integration

The Jira integration enables Adoptech to create, update and track issues in your Jira projects directly from the compliance platform.

This integration helps organisations:

• Manage compliance remediation tasks within existing Jira workflows

• Track the progress of risk treatments and audit findings

• Ensure compliance actions are assigned, visible and actioned

• Reduce duplication between compliance and engineering or operations workflows

Prerequisites

Before configuring the integration, ensure you have:

1. An active Jira Cloud or Jira Server instance

   1. A Jira user account with permission to create and manage issues in the target project.
      We recommend connecting the integration using a dedicated Jira service account rather than a personal account. This limits the integration to only the permissions it needs (principle of least privilege) and keeps the audit trail clean — every Adoptech-created issue is attributed to the service account, making it easy to distinguish automated activity from manual changes. See Atlassian's guide on creating and managing API tokens for instructions on setting up a service account with an API token. 

2. A Jira API token for that user account

3. Your Jira domain (e.g. yourcompany.atlassian.net)

What Data We Collect

To configure the integration, Adoptech retrieves the following from Jira:

• Project names and IDs (to let you select a target project during setup)

• Issue types available in the selected project

• Issue status and available transitions (to keep issue state in sync)

Adoptech keeps the following fields in sync between Portal actions and Jira issues:

• Name (Portal) ↔ Summary (Jira)
• Description (Portal) ↔ Description (Jira)
• Due date (Portal) ↔ Due date (Jira)
• Status (Portal) ↔ Status (Jira)

Status mapping: an Open Portal action maps to the To Do status category in Jira; a Completed action maps to Done. When a Jira issue transitions to a Done status, the corresponding Portal action is automatically marked as complete.

What We Use the Data For

The connection is used to:

1. Create Jira issues from compliance actions, risk treatments and audit findings

2. Update issue status as tasks progress

3. Close issues when compliance actions are resolved

Before you get started you will need:

The following configuration items are required to integrate Jira with Adoptech:

- Jira domain
- Jira user email address (preferably a Jira service account)
- Jira API token

You will also be prompted to select a target project and issue type during setup.

How do I configure Jira?

Creating the API Key

1. Go to Account settings
   
2. Select the Security tab
   
3. Scroll down to API Tokens and click on Create and manage API tokens
4. Select the Create API token button
5. Fill in the Name and expiry - Note: Jira limits the token to a max life of 1 year
   
   
6. Once created you can then copy the API token. Note: you will need to save the token somewhere safe as it cannot be viewed again once you click Done 

Setting up WebHooks

WebHooks are required to enable the two way communication between Adoptech and Jira. If you create a ticket in Adoptech and send it to Jira, any updates (to supported fields) will also be updated in Adoptech. This allows the ticket to remain in sync between systems.

You will need Admin permissions in Jira to set up WebHooks.

1. Go to Jira admin settings/System
   
   

2. Scroll down to Advanced/WebHooks
   

3. Select Create a WebHook
   

   1. Give the WebHook a name

   2. Enter the following url (your VENDOR_ID can be found on the Company Profile page in Adoptech. If you cannot find this please ask Adoptech Support).

      https://portal.adoptech.co.uk/webhooks/jira_issue/VENDOR_ID
   3. Under Issue related events
      1. Enter the following syntax (select your Project )
         Project = "project_name" AND labels in (Adoptech)
         
      2. Select Issue types:       
          
   4. Please leave the "Exclude body" box unchecked. It can be found at the bottom of the page

How do I configure Adoptech?

Once you have generated the API token in Jira you can create the integration in Adoptech.

1. Select Apps and Integrations page from the LHS menu
    
2. Find the Jira tile and click On Connect
   
3. The RHS menu
   1. Enter the API key generated above into the API Key field
   2. The domain can be found from your Jira url - vendor-jira.atlassian.net 

1. 1. Enter the email address of the user who owns the API Key - Note: this user will default to be the 'Reporter' of the task in Jira for all tasks raised via Adoptech.
      
   2. Then click on the orange Connect button
   3. Select your Project ID and Issue type and click Done.

Once your integration is configured you can start to create Tasks in Adoptech that will flow through to Jira. This help article explains more about how to do this.

If you wish to update your Project ID and Issue Type, you can go to the Connected Integrations Page and click on the cog icon.

Troubleshooting

1. You Jira board must have the “Labels” field enabled for the issue type you're using, otherwise the issue sync fails. The fields are configured in Jira Space Settings (the settings may be under Issue Types, Request Types or Work Types, depending on your Jira space type).