Jira Server and Jira Data Center data integration

CloudBees Engineering Efficiency stores Jira Server and Jira Data Center information in the System of Record for each instance that has installed the plugin. This page explains how the service works, API REST calls used with the servers, and details the data sent from the Jira Server plugin.

Jira Data Center and Jira Server use the same integration. While the content below mentions Jira Server, this information applies to Jira Data Center as well.

What data is stored

CloudBees Engineering Efficiency stores the following Jira Server and Jira Data Center information in the System of Record for each instance that has installed the plugin:

  • Account - The CloudBees user profile or organization profile linked with this Jira Server

  • Refresh Token - A security token obtained from the Jira Server App in CloudBees Engineering Efficiency.

  • Client key or Server ID - The unique identifier for the Jira Server

  • Server version - The version of the Jira Server

  • Plugin version - The installed version of the plugin

  • Base URL - The URL for the Jira Server

  • Installed - The flag denoting if the plugin is currently installed on a Jira Server

How the service works

The customer installs a Jira Server plugin developed by CloudBees into their on-premise Jira Server instance. Once installed, this plugin runs a sync operation to send CloudBees Engineering Efficiency data from the Jira Server instance, then sends webhooks as data is created, updated, and deleted. The sync operation also repeats periodically and resends all data created or updated since the last sync.

The data the plugin sends are comprised of:

  • Issues

  • Issue comments

  • Sprints

  • Boards

  • Issue changelogs

  • Projects

User information is removed from issues and issue comments on ingestion and stored separately in the System of Record, in accordance with Atlassian’s recommendations in the User privacy guide for GDPR compliance.

The data is sent to the CloudBees Engineering Efficiency backend service via the REST API. This service handles authentication and is responsible for handshaking and validating the plugin on the initial installation. The backend receives and stores your data where it can be retrieved and used by the System of Record GraphQL for your applications. This is the same methodology that is used with Jira Cloud.

Data syncs between Jira Server and System of Record

After the CloudBees Software Delivery Management plugin is installed for Jira Server and a new Jira Server integration is created, several installation scans are started simultaneously. This begins fetching data entities from the Jira Server, including all of the data for Projects, Sprints, Boards, Issues, Issue Changelog History, Comments, and the Users associated with those entities.

There’s no rate limiting for Jira Server instances. These scans retrieve and publish the data to the CloudBees Engineering Efficiency service as quickly as possibles until all the data has been retrieved and published. For large organizations, this can take a few hours.

Hourly, scans are run to retrieve all of the Project, Sprint and Board data. Also, once an hour, all of the Issues that were created or updated within the last hour are retrieved and sent to the CloudBees Engineering Efficiency service. This also includes extracting the Projects, Comments, Changelog history, and Users associated with these Issues.

Once an integration has been set up, the CloudBees Software Delivery Management plugin begins triggering webhook events to CloudBees Engineering Efficiency any time an Issue, Field, Comment, Project, Sprint, or Board is created, updated, or deleted. These webhook events are processed directly and do not result in subsequent API calls back to Jira Server from CloudBees Engineering Efficiency.

Optional proxy server

Customers have the option to install an NGINX proxy server in their environment. This allows the plugin to run on an on-premise Jira instance in a customer’s environment. The customer may not want multiple services calling out to CloudBees Engineering Efficiency injectors.

Currently, this proxy can be configured to receive data from multiple sources such as Jira Server, GitHub Enterprise, and Jenkins and pass it to CloudBees Engineering Efficiency. You only need to authorize outbound traffic from the proxy. To accommodate this, all data is pushed from the plugin to the CloudBees Engineering Efficiency service.

The CloudBees Engineering Efficiency service does not send requests back to the plugin for data; communication is one-way.

Connecting Jira Server to CloudBees Engineering Efficiency

Integration with Jira Server is provided through the CloudBees Engineering Efficiency plugin. After installing the plugin on your Jira Server, it will establish a push-based connection that sends the latest Jira changes to CloudBees Engineering Efficiency after an initial push of existing data.

If you are using a proxy server to allow your Jira server to access CloudBees Engineering Efficiency, the Jira plugin can be configured to use the web address of your gateway server instead of directly connecting to https://app.cloudbees.com

The NGINX proxy server configuration can be used to set up the proxy server. The Jira plugin also needs to be configured to enable the connection.

Jira Server App REST APIs

The Jira plugin publishes data to app.cloudbees.com using a REST API. Invocations of the REST API are executed over HTTPS and authenticated using a shared secret that is associated with the Jira Server during setup.

EndpointMethodParams / Request BodyDescription

/api/v1/ingest/jira-server/app/{serverId}/server-issue-{issueEventType}

POST

issueEventType (path parameter) - The type of Issue Event. One of created, updated, or deleted.

Jira Issue Event, see the Jira docs for the JSON format.

Endpoint for receiving Jira Issues from the Jira Server plugin.

/api/v1/ingest/jira-server/app/{serverId}/server-comment-{commentEventType}

POST

commentEventType (path parameter) - the type of Comment Event; created, updated, or deleted.

Jira Comments Event, see the Jira docs for the JSON format.

Endpoint for receiving Jira Comments from the Jira Server plugin.

/api/v1/ingest/jira-server/app/{serverId}/server-sprint-{sprintEventType}

POST

sprintEventType (path parameter) - The type of Sprint Event; created, updated, or deleted.

Jira Sprint Event, refer to the Jira docs for the JSON format.

Endpoint for receiving Jira Software Sprint events from the Jira Server plugin.

/api/v1/ingest/jira-server/app/{serverId}/server-board-{boardEventType}

POST

boardEventType (path parameter) - The type of Board Event; created, updated, or deleted.

Jira Board Event, see the Jira docs for the JSON format.

Endpoint for receiving Jira Software Board events from the Jira Server plugin.

/api/v1/ingest/jira-server/app/{serverId}/server-fields

POST

Jira Issue Field Metadata (see the Jira docs for the JSON format).

Endpoint for receiving Jira Field metadata from the Jira Server plugin.

/api/v1/ingest/jira-server/app/{serverId}/server-plugin

POST

Jira Server Plugin Info (includes the clientKey, serverId, serverVersion, pluginVersion, installationSecret, baseUrl, and sharedSecret).

Endpoint for initial plugin installation.

/api/v1/ingest/jira-server/app/{serverId}/server-plugin

PUT

Jira Server Plugin Info (includes the clientKey, serverId, serverVersion, pluginVersion, installationSecret, baseUrl and sharedSecret).

Endpoint for plugin reinstall or updates. Updates the state of the plugin info stored in the System of Record for the given clientKey. Requires a properly signed JWT since there has already been communication between this Jira Server instance and the Jira Server App.

All Issues, Comments, Sprints, Boards, and Projects on the Jira Server are sent to CloudBees Engineering Efficiency upon plugin install. Whenever one of those types are created, updated, or deleted, a webhook event is generated by the plugin and sent to CloudBees Engineering Efficiency to update or remove the data for that entity in the System of Record. In an effort to ensure data consistency between the Jira Server and CloudBees Engineering Efficiency, sync events containing Issues, Comments, Sprints, and Boards are sent to CloudBees Engineering Efficiency hourly. These events contain all of the entities (of the aforementioned types) that were created or updated since the last sync event was sent, and these are sent to the respective endpoints documented above, based on the event type.

Data sent from the Jira Server plugin

The following data is synchronized to the CloudBees Engineering Efficiency SaaS on an on-going basis and stored in the CloudBees Engineering Efficiency data store, the System of Record.

Jira Server

Account

The CloudBees user profile or organization profile linked with this Jira Server

Client key or Server ID

The unique identifier for the Jira Server

Shared secret

The secret used to sign the JWT used to authenticate and authorize the Jira Server plugin to the CloudBees backend server

Server version

The version of the Jira Server

Plugin version

The installed version of the plugin

Base URL

The URL for the Jira Server

Installation secret

The secret generated by the plugin and used by the Jira Server Injector to validate the association request upon plugin install on Jira Server

Installed

The flag denoting if the plugin is currently installed on a Jira Server

Jira Server Users

Display name

The user’s public display name

Email Address

The user’s email address

Self

The URL of the user

Key

The Jira handle (i.e., username)

Account ID

The unique identifier for the user, provided by Jira

URL

The URL for the user profile

Avatar

The URLs for the user’s avatars

Time zone

The user’s time zone

Active

The active/closed status for the user

Jira Server Issue Comments

Jira Issue Id

The ID of the issue to which this comment belongs (e.g., 10001)

Jira Issue Key

The key of the issue (e.g., PROJECT-123)

Self

The URL of the comment

Body

The text representation of the comment body

Rendered Body

The sanitized, HTML representation of the comment body

Author Key

The author’s Jira handle

Update Author Key

The update author’s Jira handle

Created

The comment created timestamp

Updated

The comment updated timestamp

Jira Server Issues

Jira Issue Id

The ID of the issue (e.g., 10001)

Jira Issue Key

The key of the issue (e.g., PROJECT-123)

Self

The URL of the issue

Features

Any features this issue is associated with

Assignee Key

The assignee’s Jira handle

Creator Key

The creator’s Jira handle

Reporter Key

The reporter’s Jira handle

Epic Link

A link to the issue’s epic

Sprint

A link to any current sprint the issue belongs to

Jira Sprint IDs

A collection of the sprint IDs for all the sprints that included this Issue

Description

The sanitized, HTML representation of the issue’s description

Issue Fields include:

  • Issue Type

  • Project

  • Summary

  • Status

  • Status Change Date

  • Description

  • Created

  • Updated

  • Last Viewed

  • Priority

  • Rank

  • Votes

  • Issue Links (to other related Issues)

  • Resolution

  • Resolution Date

  • Labels

  • Time Spent

  • Aggregate Time Spent

  • Time Estimate

  • Time Original Estimate

  • Aggregate Time Estimate

  • Work Ratio

  • Story Points

  • Progress

  • Aggregate Progress

  • Versions

  • Fix Versions

  • Attachments

  • Subtasks

Jira Server Sprints

Jira Sprint ID

The ID of the sprint

State

One of active, closed, or future

Name

The name of the sprint

Start date

The date the sprint started

End date

That date the sprint ended

Origin Board ID

The ID of the board from which the sprint was created

Origin Jira Board

The board from which the sprint was created

Goal

The sprint’s goal

Self

The URL of the sprint

Jira Server Issue IDs

A collection of IDs of the Jira Server issues that belong to this sprint

Jira Server Issues

A collection of Jira Server issues that belong to this sprint

Jira Server Boards

Jira Board Id

ID of the board

Name

The board’s name

Self

The URL of the board

Type

One of scrum, kanban, or simple

Location:

  • Project ID

  • Display Name

  • Project Name

  • Project Key

  • Project Type Key (one of software, business or service_desk)

  • Avatar URI

    Jira Sprints

    A collection of sprints that are associated with this board

    Jira Sprint Ids

    A collection of the sprint IDs for all the sprints that are associated with this board

Jira Server Projects

Jira Project ID

The ID of the project (e.g., 10001)

Jira Project Key

The key of the project (e.g., PROJ)

Name

The name of the project

Self

The URL of the project

Avatar URLs

The URLs for the project’s avatars

Project Type Key

The type of project (software, service_desk or business)

Simplified

Whether the project uses the simplified workflow

Jira Server Issues

A collection of Jira Server issues that belong to this project