Jira
IT Service Management- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The Jira Server connector integrates with on-premise Jira Server (Data Center) instances over the Jira REST API v2 to synchronize project, issue, issue type, issue status, and issue field data into the Brinqa platform. Issues are the primary synchronized object and support dynamic schema discovery, with custom fields and issue link types resolved at runtime from the Jira create-meta endpoint. In addition to read synchronization, the connector supports bidirectional operations on issues — creating, updating, deleting, and transitioning issues, and (when enabled) synchronizing issue links.
Data retrieved from Jira
| 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 |
Model relationships
For detailed steps on how to view the data retrieved from Jira in the Brinqa Platform, see How to view your data.
When update sends its regular PUT request — on Server, only when no transition matches — 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.
The assignee, reporter and creator values the sync reads back are the user's name, or — when name is absent — their displayName, emailAddress or key, in that order.
Connection settings
When setting up a data integration, select Jira from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| Server URL | Yes | Default - (user input, Required) | Jira server URL |
| Access token | Yes | Default - (user input, Required) | Personal access 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 a comma separated list. |
| Default issue type | No | Bug | Default issue type when creating new issues. |
| Page size | No | 100 | Maximum number of records to get per API request |
| Parallel requests | No | Number of available processors (capped at 4) | Maximum number of parallel API requests |
| Issue linking | No | false | Supports issue linking |
| Render fields | No | true | Convert field values from html to wiki markup |
| Custom Headers | No | Default - (user input) | Custom HTTP headers to include with every request (format: HeaderName=HeaderValue) |
| SSL / TLS | No | false | Skip certificate verification |
Authentication
Method
Bearer Token (Personal Access Token)
Endpoint
| Method | URL |
|---|---|
| All requests | https://{your-jira-host}/rest/api/2/* |
Request Headers
| Header | Value |
|---|---|
Authorization | Bearer <personal-access-token> |
Accept | application/json |
Usage
All API requests include the personal access token as a Bearer token in the Authorization header:
Authorization: Bearer <personal-access-token>
Accept: application/json
Custom HTTP headers can also be injected via the customHeaders configuration property using the format HeaderName=HeaderValue, separated by semicolons.
Required Permissions
The setup instructions (SETUP-jira-server.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 Project, Issue and Issue Status reads |
Create Issues | Project | Always — the connection test, schema resolution for the Issue and Issue Field models (see note), the Issue Type read, and issue creation |
Edit Issues | Project | Issue update |
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
sincevalue is present, the JQL search is constrained withupdated > "<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 — Full sync on every run. These metadata models are re-enumerated per project (and per issue type where applicable); the
sincetoken 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 credentials
Create a personal access token
The Jira Server connector authenticates with a personal access token. Personal access tokens are available in Jira 8.14 and later. Jira does not allow retrieval of an existing token, therefore, you must generate a new one instead. To do so, follow these steps:
-
Log in to Jira as the user the connector should act as. The permissions this user needs are listed in the permissions section below.
-
Click your profile photo, click Profile, and then click Personal access tokens.
-
Click Create token.
-
Enter a name that describes what the token is for, optionally set the number of days until the token expires, and then click Create.
-
Copy the token and save it to a secure location. You cannot view the token again after this.
When you configure the connector, enter the token in Access token.
Note: If you do not see Personal access tokens in your profile, or cannot create a token, contact your Jira administrator. Administrators can disable personal access tokens or limit how many tokens each user can create and how long they can last. If the token expires, the connector can no longer authenticate, so create a new token before the expiration date and update the connector configuration. For additional information, see the Atlassian documentation.
Grant the required permissions
The connector authenticates with a personal access token, which has the same permissions as the Jira user who created it. That user must be a licensed Jira user. Project permissions are granted through each project's permission scheme, so the user needs them in every project the connector syncs.
Required for every integration:
- Browse Projects
- Create Issues. This is required even if Brinqa only reads from Jira, and the connection test fails without it.
Required only if Brinqa writes back to Jira:
- Edit Issues
- Transition Issues
- Delete Issues
- Link Issues
Note: Beyond the connection test, a missing permission does not make the sync fail. Instead, the affected data is missing: projects without Browse Projects are skipped, and projects without Create Issues sync their issues without custom fields. If a sync returns fewer records or fields than expected, check these permissions first.
customHeaders entries are applied after these two headers, and replace them when they use the same header name.
Create Issues is required even for a read-only integration, and the connection test fails without it. Both the test and the Issue / Issue Field schema resolution call GET /rest/api/2/issue/createmeta/{projectKey}/issuetypes/{issueTypeId}, which Jira gates behind the Create Issues project permission. Where the permission is missing for only some of the configured projects, the sync itself does not fail: the Issue schema falls back to the connector's built-in default attributes for those projects, with every custom field missing.
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.
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 |
Project.description | DESCRIPTION |
Project.id | UID |
Project.key | PROJECT_KEY |
Project.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.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 |
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.
Issue Type
| Source Field Name | SDM Attribute |
|---|---|
Instant.now() | LAST_CAPTURED |
IssueTypeResource.description | DESCRIPTION |
IssueTypeResource.id | ISSUE_TYPE_ID |
IssueTypeResource.name | NAME |
IssueTypeResource.subtask | SUBTASK |
Project.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 |
IssueTypeResource.name | ISSUE_TYPE |
Project.key | PROJECT_KEY |
ServerIssueFieldResource.allowedValues[].name | ALLOWED_VALUES |
ServerIssueFieldResource.fieldId | FIELD_ID |
ServerIssueFieldResource.hasDefaultValue | HAS_DEFAULT_VALUE |
ServerIssueFieldResource.name | NAME |
ServerIssueFieldResource.operations | OPERATIONS |
ServerIssueFieldResource.required | REQUIRED |
ServerIssueFieldResource.schema.type | FIELD_TYPE |
{projectKey}-{issueType.name}-{field.name} | UID |
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
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. |
project | String | The projectKey configuration property | Comma-separated project keys or IDs to search, overriding projectKey for this operation. The value is inserted into the search unquoted, as project in (<value>). A value of *, or a blank value, removes the project filter entirely and searches every project the account can browse. |
*(any other key)* | String | — | Any option that is not a framework option or project is applied as an equals filter and AND-ed into the JQL as key="value". |
Delta sync
Supported. The connector performs an incremental (delta) sync via the since sync token, filtering on updated.
API
- Type: REST
query and project are honored only by the Issue model — the other models ignore them. 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.
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
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
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
Changelog
The Jira connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.2.5 | Improvements - Locally cached project and issue-field data is now kept separately per Jira site, so multiple Jira Server integrations running on the same agent are isolated from one another regardless of how their syncs are scheduled. | N/A |
| 3.2.4 | Improvements - Custom Issue and Issue Field attributes now inherit the connector's standard consolidation mappings, so their values consolidate consistently with the rest of the schema. Bug Fixes - The Issue Field Allowed values attribute is now emitted as a single comma-separated string that matches its declared single-valued schema; previously it emitted a set of values that disagreed with the declared type. | N/A |
| 3.2.3 | No changes in this release. | N/A |
| 3.2.2 | No changes in this release. | N/A |
| 3.2.1 | Improvements - Added LAST_CAPTURED mandatory attribute to all five Jira Server models: Project, Issue, Issue Type, Issue Status, and Issue Field. Each model now records the sync capture timestamp on every synchronized record, ensuring consistency with the Brinqa 3.x schema compliance standard. | N/A |
| 3.2.0 | No changes in this release. | N/A |
| 3.1.26 | Bug Fixes - Fixed Jira Server issue update operations failing with HTTP 405 (Method Not Allowed). Field edits on existing issues are now correctly PUT to /rest/api/2/issue/{id} instead of /rest/api/2/issue/{id}/transitions. | N/A |
| 3.1.25 | New Features - Added support for custom HTTP headers on the Jira Server connector, allowing additional headers to be included with every API request (format: HeaderName=HeaderValue, separated by semicolons). | N/A |
| 3.1.24 | New Features - Added handling for Jira rate limiting (HTTP 429). When the server 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 | New Features - Added new models that are synchronized alongside issues: Project, Issue, Issue Type, Issue Status, and Issue Field. These provide richer context about the Jira instance being synced. | N/A |
| 3.1.22 | No changes in this release. | N/A |
| 3.1.21 | No changes in this release. | N/A |
| 3.1.20 | No changes in this release. | 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 | New Features - Added support for Personal Access Token (PAT) authentication. The connector now authenticates with a single Personal Access Token instead of a username and password. | • Connection configuration: The username and password fields have been replaced by a Personal Access Token field. Update each Jira Server connection to supply a Personal Access Token before the next sync. Action: reconfigure. |
| 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 an available project to retrieve issue field metadata, so field discovery works without requiring a project to be specified. | N/A |
| 3.1.9 | No changes in this release. | 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 | Improvements - Improved Jira Server authentication by sending credentials preemptively and preserving the session cookie across requests, reducing authentication round-trips. | 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 Server connector integrates with Atlassian Jira Server (and Data Center) to synchronize issues, including their fields, statuses, comments, and links. Category: IT Service Management Models | N/A |