Configuring Jira for RealTheory Ticketing Integration

Before RealTheory can create Jira issues for Recommendations within a specified Jira project, Jira must be set up correctly. This article explains exactly what must be configured on the Jira side to support the integration.

Supported Jira Versions and Authentication Methods

RealTheory supports both Jira Cloud and Jira Data Center. The authentication methods differ depending on the deployment type.

Jira Data Center

Jira Data Center requires one of the following:

A Jira service account (highly recommended)
A Jira user account (not recommended)

RealTheory supports two authentication models for Jira Data Center:

Basic Authentication
- Username + Secret
- Where Username is the Jira username, and Secret is the password associated with the account.
Personal Access Token (PAT)
- Available for Jira Data Center 8.14+
- Created through the user's Manage Account page

Jira Cloud

Jira Cloud requires:

A Jira service account (highly recommended)
A Jira user account (not recommended)

RealTheory supports one authentication model for Jira Cloud:

An API Token generated by the account
Created from:
https://id.atlassian.com/manage-profile/security/api-tokens

RealTheory supports a Username + Secret authentication model for Jira Cloud, where Username is the account email address and Secret is the API token associated with the account.

Jira Integration Account

RealTheory connects to Jira using a single Jira account, referred to in this article as the integration account. Whether you use a dedicated service account (highly recommended) or a human user account (not recommended), the integration account must:

Have an active Jira license
Have access to the project(s) RealTheory will interact with
Use one of the supported authentication methods above

Jira records the integration account as the Reporter of every issue RealTheory creates, so choose a clear, recognizable name. For example, realtheory.integration.

No administrative or global permissions are required.

Project-Level Permissions

RealTheory creates Jira issues and can delete the issues it created. Actions such as assigning an issue, adding sub-tasks, or making status transitions must be managed in Jira.

The integration account must have the following permissions in the Jira project(s) you intend to integrate with RealTheory through Integration Profiles:

Browse Projects - Allows RealTheory to see the project and its metadata.
Create Issues - Required for creating Jira issues.
Delete Issues - Required to delete issues from Jira using the RealTheory Console.

Many Jira environments restrict the Delete Issues permission. Without it, RealTheory still creates issues successfully, but deleting an issue from the RealTheory Console fails with a "Failed to delete" message.

Issue Types

RealTheory creates issues using the Default Issue Type specified in the Integration Profile. Users can override the Default Issue Type during ticket creation, so Jira must allow the integration account to create whichever Issue Type the user selects.

To ensure this:

The Issue Type must exist in the project's Issue Type Scheme
Example: Task, Bug, Story, Incident, etc.
Any required fields must be optional or have defaults
RealTheory does not supply values for custom fields or special workflow fields. If your Issue Type has required fields such as:
- Component
- Custom fields
- Priority
- Environment
- Team
- Epic Link (if required)
  Note: Epic Link is a common mandatory field when the issue type is Story.
…then each field must either:
- Be configured as optional, or
- Have a default value in the project configuration
If a required field has no value, Jira rejects the create request.
Workflow validators must not block creation
If the project's workflow includes validators on the Create transition, they must not require fields that RealTheory does not provide. Common blocking validators include:
- "Field X must not be empty"
- "Component is required"
- Mandatory custom fields via scripting add-ons
Remove or relax these validators, or add default values in Jira.
Note: If your Jira implementation uses ScriptRunner or other add-ons for mandatory fields, RealTheory cannot bypass these.

Multiple Issue Types and Projects

Your organization might want RealTheory to support different workflows, such as:

Bugs for QA
Stories for Development
Tasks for Operations
Incidents for SREs
Multiple Jira projects across teams

Create one Integration Profile for each workflow. For example, one profile per provider (Jira Cloud or Jira Data Center), per project, or per Default Issue Type. Each Jira instance needs its own integration account, configured as described in this article, and each profile's Default Issue Type must exist in its project's Issue Type Scheme.

URLs and Connection Details RealTheory Needs From Jira

Your Jira administrator must provide the following information to your RealTheory administrator. These values are entered into a RealTheory Integration Profile, and all of them are required.

API URL - Enter it without a trailing slash.
- Jira Cloud: the root URL of your site. For example, https://<your-domain>.atlassian.net
- Jira Data Center: your Jira base URL, including the context path if Jira uses one. For example, https://jira.<your-company>.internal
Console URL - Used to generate direct links to issues in Jira. Typically, the same as the API URL.
Project Key - For example, ENG, OPS, QA, PLAT
Default Issue Type - For example, Story, Task, Bug, Incident
Authentication values - The integration account's Username and Secret, or a PAT for Jira Data Center. See Supported Jira Versions and Authentication Methods.