Configuring Jira integration

Use this topic to connect Evidence Hub to a Jira instance so that evidence requests and workflow updates are synchronized as Jira tickets. Configuration is performed on the Connections page in Settings.

Before you start

Confirm these prerequisites before you create a connection.

Requirement Details
Evidence Admin role Only Evidence Admins can access the Connections page and manage Jira integrations.
Jira API token Generate an API token from the Jira service account that will own the integration. The token authenticates all requests between Evidence Hub and Jira.
Jira site URL The base URL of the Jira instance (for example, https://your-company.atlassian.net).
Service email The Jira service account email that owns the API token.
Jira API scopes The Jira service account must have the required classic and granular API scopes enabled. See Required Jira API scopes.

Setting up the Jira service account and project

Before you create a connection, set up a Jira service account and a project for the integration. For full UI steps, follow the linked Atlassian documentation.

Service account and API token

  1. Create a service account and enter a name and description. See Understand and manage service accounts.

  2. Assign app access: the user role for Jira and the App admin role for Jira Administration.

  3. Add the service account to the default jira-admins-<site-name> then jira-users-<site-name> groups.

  4. Finish creating the account.

  5. Generate an API token for the service account with the API scopes required by the integration. See Manage API tokens for service accounts.

Project

  • Create a company-managed project from your preferred template (for example, Scrum or Kanban) and set yourself as the project administrator. See Create a new project.

Permissions

  • In Project settings > People, add the service account with the required project role. See How to use space roles.

Required Jira API scopes

The following API scopes must be enabled on the Jira service account used for the integration. Both classic and granular scopes are required:

Classic scopes Granular scopes
read:jira-work read:workflow:jira
write:jira-work write:workflow:jira
read:jira-user write:workflow-scheme:jira
manage:jira-configuration read:project:jira
manage:jira-project read:board-scope:jira-software
- read:board-scope.admin:jira-software

Creating a new Jira connection

Create a connection to authorize communication between Evidence Hub and a Jira instance.

  1. Open Settings and select Connections.

  2. In the Jira section, select + New connection.

  3. Enter a Connection name to identify this integration.

  4. Enter the Site URL of the Jira instance.

  5. Enter the Service email associated with the API token.

  6. Enter the Jira API Token.

  7. Select Test connection & Save.

The system validates connectivity and authentication before saving. If validation fails, correct the credentials and try again.

Managing existing connections

After a connection is saved, it appears as a card under the Jira section on the Connections page. Use the context menu on each connection card to manage it.

Action Effect
Edit connection Opens the connection details so you can update the name, URL, email, or API token. Select Test connection & Save to apply changes.
Disable Suspends the connection. Existing Jira tickets are retained, but no new tickets are created and no further comments are synchronized until the connection is re-enabled.
Enable Resumes a disabled connection and re-enables Jira synchronization.
Delete Permanently removes the connection configuration. Existing Jira tickets in the Jira instance are not affected.

Adding a Jira space and mapping statuses

After you save a connection, add one or more Jira spaces (projects) and map Evidence Hub statuses to the corresponding Jira statuses in each space.

  1. Open the saved connection to view its details.

  2. Select Add new Space.

  3. In Select space, choose a Jira space from the dropdown.

  4. Configure status mapping. The Use default mapping toggle is on by default. Turn it off to customize the mapping for each status.

  5. Select Save.

Status mapping reference

Each Evidence Hub status maps to a Jira status in the selected space. When Use default mapping is on, the system applies the standard mapping shown below and the Jira statuses cannot be edited. Turn it off to select a custom Jira status for each Evidence Hub status.

Evidence Hub status (Default Jira status) Description
Draft The record is in progress and has not been sent.
Awaiting response The request has been sent and is waiting for the respondent.
Awaiting review The response has been submitted and is pending review.
Accepted The evidence has been accepted.
Invalid The evidence has been rejected or marked as invalid.

Warning

The system prevents saving duplicate or invalid mappings. Mapped Jira statuses must exist within the selected space's workflow.

How Jira ticket synchronization works

When an Evidence Admin configures a Jira connection and adds spaces, record owners can enable Jira integration for individual records. When an owner enables a Jira space for a record, notifications for that record switch from standard email communication to Jira comments.

Ticket creation

With a Jira space enabled, Evidence Hub creates a Jira ticket in the mapped space when a record owner sends an evidence request or provide evidence as a self-respondent. The ticket includes the following Evidence Record details:

  • Name, description, and scope dates (start and end)

  • Due date and expiry date

  • Labels

  • Assigned participants: owner, respondent, alternate respondent, reviewer, requester, and notifier

  • Evidence Record ID

  • Deep link to the Evidence Record in Evidence Hub

  • AI validation, discoverable and downloadable settings, and delegation scope

  • Assigned Jira space

Assignee and watcher mapping

The Jira Assignee field follows the record status:

Evidence Hub status Jira Assignee
Draft -
Awaiting response Respondent
Awaiting review or Accepted Owner

The respondent, alternate respondent, and reviewer are recorded in their respective fields on the Jira ticket. Viewers are added as Jira Watchers.

Note

Jira does not support adding a user group directly as a watcher. When a group is assigned as a Viewer, Evidence Hub adds the group's individual members as watchers instead.

Note

If the respondent does not exist in Jira, Evidence Hub sends an email notification to the respondent instead and records the notification details as a comment on the Jira ticket.

Comment synchronization

The following workflow actions on an Evidence Record are captured as comments on the linked Jira ticket. Each comment includes notification details, assignee information, the Evidence Record ID, and the current status:

  • A requester assigns an Evidence Record to a respondent.

  • A respondent delegates to an alternate respondent.

  • A respondent or alternate respondent submits evidence.

  • A requester revokes access from a respondent, which also revokes the alternate respondent.

  • A respondent removes access from the alternate respondent.

  • A user requests access from the owner.

  • The owner approves or denies an access request.

  • The owner revokes access previously granted through an access request.

  • The owner assigns or revokes a reviewer.

  • A reviewer accepts or rejects submitted evidence.

  • The owner assigns or revokes the viewer role for a user or group.

  • A participant's role is changed on the Collaborators tab.

  • The owner changes a user role from previous to a new role.

Changing the Jira space on a record

Changing the Jira space on an existing record will be available in a future release.

Setting up Jira notifications for record roles

When a participant on a record exists as a Jira user, Evidence Hub does not send its own email notifications to that participant. Instead, Jira emails them about activity on the linked ticket. For these participants to receive email, a Jira administrator must configure a Jira notification scheme that notifies the relevant recipients, including the user custom fields the connector records on the ticket (respondent, alternate respondent, and reviewer) and associate that scheme with the mapped Jira space.

Note

This configuration is performed in Jira, not in Evidence Hub. Participants who do not exist in Jira continue to receive email directly from Evidence Hub.

Complete the following in Jira. For detailed steps, see the Atlassian documentation on Configure notification schemes.

  1. Create a notification scheme from Settings > Work Items > Notification Schemes, then give it a name and description.

  2. For each notification type, add the recipients your workflow requires (for example, Current Assignee, Reporter, All Watchers, and Current User).

  3. To notify the evidence roles the connector records on the ticket, add each as a User Custom Field Value recipient—respondent, alternate respondent, and reviewer.

  4. Go to the mapped Jira space's notification settings: open Space settings, select the space, select the more options menu (three dots), select Space settings, then select Notifications > Settings. The currently selected notification scheme is displayed.

  5. To apply the scheme you created, select Actions > Use a different scheme, select the scheme from the dropdown, then select Associate.

For record-level workflow details, see Creating and sending an evidence request. For admin governance and settings, see Administering Evidence Hub.