Jira Cloud

IT Service Management

Overview

The Jira Cloud connector integrates with Atlassian Jira Cloud to synchronize project, issue, issue type, issue status, issue field, and user data into the Brinqa platform. It supports bidirectional operations including creating, updating, deleting, and transitioning Jira issues, as well as issue linking. The connector uses the Jira Cloud REST API v3 with cursor-based pagination for issue search.

---

Data retrieved from Jira Cloud

Connector Object	Required	Maps to Data Model
Project	Yes	Project
Issue	Yes	Issue
Issue Type	Yes	Issue Type
Issue Status	Yes	Issue Status
Issue Field	Yes	Issue Field
User	Yes	Person

Model relationships

note

For detailed steps on how to view the data retrieved from Jira Cloud in the Brinqa Platform, see How to view your data.

note

When update sends its regular PUT request — which on Cloud is always, transition or not — the request always includes issuetype, falling back to the defaultIssueType configuration property when no issue type is supplied. A blank assignee value is skipped rather than sent, so the connector cannot un-assign an issue.

info

Do not send displayName, emailAddress, or name as the assignee value. Jira Cloud requires the accountId, which is available as the UID attribute of the synced User object type.

info

The assignee, reporter and creator values the sync reads back are never accountIds. Each one is the user's name, or — when name is absent, which it is on Jira Cloud — their displayName, emailAddress or key, in that order. As a result, a synced assignee value cannot be written back as-is, and it does not match the UID of the User model. Resolve the account ID through the User model before writing.

note

If comment posting fails during creation, the error is logged but the issue is still created successfully. Comment failures do not roll back the issue creation.

Setup

Connection settings

When setting up a data integration, select Jira Cloud from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Service URL	Yes	Default - (user input, Required)	JIRA rest interface URL
Email	Yes	Default - (user input, Required)	User with proper access to query, create, and delete issues.
API token	Yes	Default - (user input, Required)	User API token.
Project key	No	Default - (user input)	Project key for the project usually a three letter abbreviation of the project name. Multiple project keys can specified as comma separated list.
Default issue type	No	Bug	Default issue type when creating new issues.
Page size	No	100 (unused)	Maximum number of records to get per API request
Parallel requests	No	4, or the number of CPU cores if lower	Maximum number of parallel API requests
Maximum retries	No	5	The maximum number of retry attempts before giving up a request
Request timeout (secs)	No	120	The maximum seconds allotted before a request will time out. Enter zero (0) to disable timeouts (not recommended).
Issue linking	No	false	Supports issue linking
Render fields	No	true	Convert field values from html to wiki markup
Schema refresh interval (mins)	No	30	How long a resolved Issue schema is reused before it is read from Jira again. Resolving the schema reads every configured project and issue type, so lowering this increases API calls. Enter zero (0) to always read the schema from Jira.

Authentication

Method

Basic Authentication (Email + API Token)

Endpoint

Method	URL
All requests	https://{your-domain}.atlassian.net/rest/api/3/*

Request Headers

Header	Value
Authorization	Basic base64({email}:{api-token})
Accept	application/json

Usage

All API requests include Base64-encoded credentials in the Authorization header:

Authorization: Basic base64({email}:{api-token})
Accept: application/json

How to Generate an API Token

1. Log in to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Provide a label and click Create
4. Copy the token value

Required Permissions

The setup instructions (SETUP-jira-cloud.md) list which permissions to grant. The table below shows which connector operations use each one.

Permission	Scope	Required for
Browse Projects	Project	Always — the connection test, and the Project, Issue, Issue Type and Issue Status reads
Create Issues	Project	Always — schema resolution for the Issue and Issue Field models (see note), and issue creation
Browse users and groups	Global	The User model
Edit Issues	Project	Issue update, including comment writes
Transition Issues	Project	Issue transitions
Delete Issues	Project	Issue deletion
Link Issues	Project	Issue linking

---

Sync Behavior

The connector supports incremental synchronization through a sync token that carries the timestamp of the last successful sync as a since (Instant) value.

• Issue — Incremental. When a since value is present, the JQL search (GET /rest/api/3/search/jql, cursor-based pagination) is constrained with updated > "<timestamp>", so only issues modified since the previous sync are retrieved. Without a sync token, all issues matching the configured project(s) are fetched.
• Project, Issue Type, Issue Status, Issue Field, User — Full sync on every run. These metadata models are re-enumerated (per project, and per issue type where applicable); the since token is not used to filter them.

The since timestamp is formatted to the minute (yyyy-MM-dd HH:mm) in the Brinqa agent's time zone, while Jira interprets the value in the API user's time zone. When the two differ, the incremental window shifts by that offset.

How to obtain Jira Cloud credentials

Create an API token for your Atlassian account

The Jira Cloud connector authenticates with the email address of an Atlassian account and an API token for that account. Atlassian does not allow retrieval of an existing token, therefore, you must generate a new one instead. To do so, follow these steps:

1. Log in to API tokens in your Atlassian account.

2. Click Create API token.

   Do not use Create API token with scopes. Scoped tokens only work with requests sent through api.atlassian.com, and the connector sends requests to your Jira site URL.

3. Enter a name that describes what the token is for, choose an expiration date between 1 and 365 days, and then click Create.

4. Click Copy to clipboard and save the token to a secure location. You cannot view the token again after this.

When you configure the connector, enter the account's email address in Email and the token in API token.

Note: When the token expires, the connector can no longer authenticate. Create a new token before the expiration date and update the connector configuration. For additional information on API tokens, see the Atlassian documentation.

Grant the required permissions

The account whose API token the connector uses must be a licensed Jira user. Project permissions are granted through each project's permission scheme, so the account needs them in every project the connector syncs.

Required for every integration:

• Browse Projects (project permission)
• Create Issues (project permission). This is required even if Brinqa only reads from Jira.
• Browse users and groups (global permission). This is required to sync users.

Required only if Brinqa writes back to Jira:

• Edit Issues (project permission)
• Transition Issues (project permission)
• Delete Issues (project permission)
• Link Issues (project permission)

Note: A missing permission does not make the sync fail. Instead, the affected data is missing: projects without Browse Projects are skipped, and without Create Issues the issues sync without their custom fields. If a sync returns fewer records or fields than expected, check these permissions first.

info

Create Issues is required even for a read-only integration. The Issue and Issue Field schemas are resolved from GET /rest/api/3/issue/createmeta/{projectKey}/issuetypes/{issueTypeId}, which Jira gates behind the Create Issues project permission. A denied create-meta call is logged and skipped rather than failing the sync, so the symptom is silent: the Issue schema falls back to the connector's built-in default attributes with every custom field missing, and the Issue Field model returns nothing.

note

Jira omits rather than rejects what the account cannot see: projects without Browse Projects are silently excluded from the sync, as are issues hidden by an issue-level security scheme. A sync that returns fewer records than expected is more often a permission gap than a connector error.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Project

Source Field Name	SDM Attribute
Instant.now()	LAST_CAPTURED
ProjectResource.description	DESCRIPTION
ProjectResource.id	UID
ProjectResource.key	PROJECT_KEY
ProjectResource.name	NAME

Issue

Source Field Name	SDM Attribute
Instant.now()	LAST_CAPTURED
Issue.fields.comment	COMMENTS
Issue.fields.created	SOURCE_CREATED_DATE
Issue.fields.project.id	PROJECTID
Issue.fields.project.key	PROJECT
Issue.fields.project.name	PROJECTNAME
Issue.fields.resolution.name	RESOLUTION
Issue.fields.resolutiondate	RESOLUTIONDATE
Issue.fields.status.name	STATUS
Issue.fields.status.statusCategory.name	STATUS_CATEGORY
Issue.fields.timetracking.remainingEstimateSeconds	REMAINING_ESTIMATE_SECONDS
Issue.fields.timetracking.timeSpentSeconds	TIME_SPENT_SECONDS
Issue.fields.updated	SOURCE_LAST_MODIFIED
Issue.id	UID
Issue.id	ISSUE_ID
Issue.key	ISSUE_KEY

note

Additional custom fields and issue link types are dynamically discovered from the Jira API during schema resolution. The full attribute set varies per Jira project and issue type configuration. The Cloud connector also includes STATUS_CATEGORY which is not present in the Server connector.

Issue Type

Source Field Name	SDM Attribute
Instant.now()	LAST_CAPTURED
IssueTypeResource.description	DESCRIPTION
IssueTypeResource.hierarchyLevel	HIERARCHY_LEVEL
IssueTypeResource.id	ISSUE_TYPE_ID
IssueTypeResource.name	NAME
IssueTypeResource.subtask	SUBTASK
ProjectResource.key	PROJECT_KEY
{projectKey}-{issueType.name}	UID

Issue Status

Source Field Name	SDM Attribute
Instant.now()	LAST_CAPTURED
IssueTypeStatusesResource.name	ISSUE_TYPE
Project key	PROJECT_KEY
StatusResource.description	DESCRIPTION
StatusResource.id	STATUS_ID
StatusResource.name	STATUS_VALUE
{projectKey}-{issueType.name}-{status.name}	UID
{projectKey}-{issueType.name}-{status.name}	NAME

Issue Field

Source Field Name	SDM Attribute
Instant.now()	LAST_CAPTURED
IssueFieldResource.allowedValues[].value or name	ALLOWED_VALUES
IssueFieldResource.fieldId	FIELD_ID
IssueFieldResource.hasDefaultValue	HAS_DEFAULT_VALUE
IssueFieldResource.key	FIELD_KEY
IssueFieldResource.name	NAME
IssueFieldResource.operations	OPERATIONS
IssueFieldResource.required	REQUIRED
IssueFieldResource.schema.type	FIELD_TYPE
IssueTypeResource.name	ISSUE_TYPE
ProjectResource.key	PROJECT_KEY
{projectKey}-{issueType.name}-{field.key}	UID

User

Source Field Name	SDM Attribute
Instant.now()	LAST_CAPTURED
UserResource.accountId	UID
UserResource.accountType	ACCOUNT_TYPE
UserResource.active	IS_ACTIVE
UserResource.displayName	USERNAME
UserResource.emailAddress	EMAIL
UserResource.key	KEY
UserResource.name	NAME

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Project

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Project on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /rest/api/3/project/search

Issue

Operation options

Option	Type	Default	Description
query	String	—	A JQL fragment joined to the rest of the search with AND and no parentheses — for example status != Done AND labels = security. Wrap any OR in your own parentheses, otherwise it binds against the surrounding conditions rather than staying inside the fragment.
*(any other key)*	String	—	Any option that is not a framework option is applied as an equals filter and AND-ed into the JQL as key="value".
Option	Type	Default	Description
:------------	:---------	:---------------------------------------------------------	:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
project	String	The first key in the projectKey configuration property	Project key or ID the issue is written to. A project attribute on the record takes precedence over this option. Both operations fail when the resolved value is not a valid project key or ID.
issueType	String	The defaultIssueType configuration property (Bug)	Name of the issue type. An issuetype attribute on the record takes precedence over this option, and issuetype is accepted as an option key alongside issueType. Create fails when the resolved value is blank.

Delta sync

Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on updated.

API

• Type: REST · Endpoint: GET /rest/api/3/search/jql

note

query is honored only by the Issue model — the other models ignore it. The project option is not honored by this connector: the projects to sync come from the projectKey configuration property, or from project auto-discovery when that property is blank. Values supplied through the equals-filter fallback are always quoted, which JQL rejects for numeric fields such as id; express those conditions in query instead.

note

The project restriction above applies to sync. The create and update operations do honor the project option, along with issueType.

Issue Type

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Issue Type on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /rest/api/3/project/search (issue types returned via expand=description,issueTypes,lead,url)

Issue Status

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Issue Status on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /rest/api/3/project/{projectKey}/statuses

Issue Field

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of Issue Field on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /rest/api/3/issue/createmeta/{projectKey}/issuetypes/{issueTypeId}

User

Operation options

This object does not support any operation options.

Delta sync

Not supported. The connector performs a full sync of User on every run and applies no incremental date filter.

API

• Type: REST · Endpoint: GET /rest/api/3/users/search

Changelog

Changelog

The Jira Cloud connector has undergone the following changes:

Version	Description	Migration Steps
3.2.5	New Features - Added a Schema refresh interval (mins) setting that controls how long a resolved Issue schema is reused before it is read from Jira again. It defaults to 30 minutes; set it to 0 to read the schema from Jira on every request. Resolving the schema reads every configured project and issue type, so lowering it increases API calls against your Jira site. Bug Fixes - Each Jira Cloud integration now resolves the Issue schema from its own Jira site instead of reusing the first schema resolved on the agent. Previously all Jira Cloud integrations on a host shared one local metadata cache, so when several instances defined different fields on Issue, whichever integration was configured first determined the field list every other integration and mapping saw — leaving required fields missing or wrong and blocking pushes. Existing mappings that were built against another instance's fields should be reviewed after upgrading. - The Issue schema now reflects projects and issue types added in Jira, which previously stayed invisible until the cached copy expired. Changes appear on the next refresh, controlled by the new schema refresh interval. - Project and issue-field data cached locally is now kept separately per Jira site and account, so integrations pointed at different instances no longer read each other's cached data.	N/A
3.2.4	No changes in this release.	N/A
3.2.3	Improvements - Extracted redundant getProjectKey() / toMD5(projectKeys) logic into a reusable helper method to eliminate duplication across sync operations - Schema creation does not receive a transaction_id from operation options, so the directory structure for Project and Issue Field models is now determined based on whether a project key is present in the connector configuration	N/A
3.2.2	Improvements - Issue create and update operations now use the Jira Cloud REST API v3 issue endpoint, aligning issue writes with the v3 API used elsewhere in the connector.	N/A
3.2.1	Improvements - Refactored custom model attributes to use AttributeInfos.newAttribute() (for single-valued) or new AttributeInfoBuilder() with explicit COLLECTION_CRITERIA mappings (for multivalued attributes) to correctly inherit consolidation mappings; restricted custom attribute visibility to private - Consolidated all REST API endpoint paths into JiraCloudModel as public static final constants (e.g., PROJECT_SEARCH_ENDPOINT, ISSUE_SEARCH_ENDPOINT, USERS_SEARCH_ENDPOINT); removed hardcoded URL strings from Issue.java, IssueStatus.java, and JiraCloudConnector.java - Added addCommentsAfterCreate in Issue.java — with direct Java Map/List construction and ObjectMapper serialization, producing a minimal update.comment JSON payload - Alphabetically ordered model types in objectClassInfoTypes(), getModel(), and sync() switch cases in JiraCloudConnector.java for consistency - Added Javadoc with sample JSON response on UserResource and IssueTypeResource - Removed unused imports (SimpleKVStore, UserResource) from Issue.java - Moved ISSUE_API_PATH constant from JiraCloudConnector to JiraCloudModel for centralized access - Added mockwebserver test dependency (4.12.0) to pom.xml for MockWebServer-based integration tests - Created JiraCloudConnectorIntegrationTests with 9 integration tests covering connection, schema, and sync for all 6 Cloud models using canned JSON responses - Added 6 mock JSON response fixtures for project search, user search, issue search, issue type statuses, and issue createmeta endpoints - Modernized JiraCloudConnectorTests: corrected testConnection method name, added @After tearDown() lifecycle method, added testBadConnection test - Corrected JiraCloudConfiguration property order numbering - Updated jira-cloud.md documentation to reflect current model attributes and connector capabilities - Renamed License.txt to LICENSE.txt for conventional uppercase naming - Added LAST_CAPTURED mandatory attribute to all six Jira Cloud models: Project, Issue Type, Issue Status, Issue Field, User, and Issue - Added comment support during Jira Cloud ticket creation — comments can now be attached as part of the initial create operation - Added Postman collection (Jira_Cloud_Connector.postman_collection.json) and companion environment file for testing all Jira Cloud REST API endpoints	N/A
3.2.0	No changes in this release.	N/A
3.1.26	No changes in this release.	N/A
3.1.25	No changes in this release.	N/A
3.1.24	New Features - Added handling for Jira rate limiting (HTTP 429). When Jira Cloud responds with a rate-limit error, the connector now honors the Retry-After interval and automatically retries instead of failing the sync. Improvements - Authentication and permission failures now surface clearer messages (for example, "Bad credentials" on HTTP 401 and "Insufficient rights to the resource" on HTTP 403).	N/A
3.1.23	No changes in this release.	N/A
3.1.22	New Features - Added new models that are synchronized alongside issues: Project, Issue Type, Issue Status, Issue Field, and User. These provide richer context about the Jira Cloud instance being synced.	N/A
3.1.21	Bug Fixes - Fixed issue update operations that could fail by routing updates through the supported Jira Cloud issue endpoint.	N/A
3.1.20	Improvements - Jira Cloud issue retrieval and search now use the current Jira Cloud REST API, improving compatibility and reliability of issue synchronization.	N/A
3.1.19	Bug Fixes - Fixed parsing of custom fields returned in a nested object format. Affected custom field values are now read correctly instead of causing the issue to fail to sync.	N/A
3.1.18	No changes in this release.	N/A
3.1.17	New Features - Added a Status Category attribute on issues, exposing the broader category (such as To Do, In Progress, or Done) for each issue's status.	N/A
3.1.16	Bug Fixes - Corrected response log levels so that successful responses are logged at the debug level and only genuine error responses are logged as errors, reducing log noise.	N/A
3.1.15	Improvements - When no project is configured, field metadata is now derived from multiple projects (up to ten) instead of a single project, producing a more complete set of available issue fields.	N/A
3.1.14	No changes in this release.	N/A
3.1.13	No changes in this release.	N/A
3.1.12	No changes in this release.	N/A
3.1.11	New Features - Added support for setting an issue's parent, allowing issues to be linked to an epic (or other parent) when they are created or updated.	N/A
3.1.10	Improvements - When no project is configured, the connector now automatically detects available projects to retrieve issue field metadata, so field discovery works without requiring a project to be specified.	N/A
3.1.9	New Features - Added a Request Timeout setting to control how long the connector waits for a response from Jira Cloud. - Added a Max Retries setting to control how many times a failed request is retried.	N/A
3.1.8	No changes in this release.	N/A
3.1.7	Improvements - Improved error reporting for failed API responses, making connection and sync failures easier to diagnose.	N/A
3.1.6	Improvements - Improved handling of date and date-time issue fields when creating and updating issues, so date-only fields and timestamped fields are written in the correct format.	N/A
3.1.5	No changes in this release.	N/A
3.1.4	Improvements - Project settings now accept either a project ID or a project key, so connections can be configured using whichever identifier is available.	N/A
3.1.3	No changes in this release.	N/A
3.1.2	No changes in this release.	N/A
3.1.1	No changes in this release.	N/A
3.1.0	No changes in this release.	N/A
3.0.4	No changes in this release.	N/A
3.0.3	New Features - Added an Issue Key attribute so each issue's human-readable key is available in addition to its internal ID.	• Issue: Issues are now uniquely identified by their internal issue ID instead of their issue key. Action: re-sync issues so they are re-keyed under the new identifier.
3.0.2	No changes in this release.	N/A
3.0.1	Improvements - The unique identifier of each issue is now exposed as a readable attribute.	N/A
3.0.0	Overview The Jira Cloud connector integrates with Atlassian Jira Cloud to synchronize issues, including their fields, statuses, comments, and links. Category: IT Service Management Models	N/A