Jira Server data integration

CloudBees SDM is a preview, with early access for select preview members. Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support. Learn more about the preview program.

CloudBees SDM stores the Jira Server 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.

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 SDM 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

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 SDM 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.

Optional proxy server

Customers have the option to install an Nginx proxy 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 SDM injectors.

The proxy server is optional. The plugin will function so long as it can connect to CloudBees SDM on port 443.

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 SDM. You only need to authorize outbound traffic from the proxy. To accommodate this, all data is pushed from the plugin to the CloudBees SDM service. The CloudBees SDM service does not send requests back to the plugin for data; communication is one-way.

Once the plugin is installed onto a server, the user can associate this server with their CloudBees user profile in CloudBees SDM using the Jira Server app.

Connecting Jira Server to CloudBees SDM

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

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

CloudBees is working on support for this setting in the Jira plugin and expects to deliver this capability soon.

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.

Endpoint Method Params / Request Body Description

/data/hooks/jira-server/v1/app/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.

/data/hooks/jira-server/v1/app/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.

/data/hooks/jira-server/v1/app/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.

/data/hooks/jira-server/v1/app/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.

/data/hooks/jira-server/v1/app/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.

/data/hooks/jira-server/v1/app/server-plugin

POST

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

Endpoint for initial plugin installation.

/data/hooks/jira-server/v1/app/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, and Boards on the Jira Server are sent to CloudBees SDM 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 SDM 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 SDM, sync events containing Issues, Comments, Sprints, and Boards are sent to CloudBees SDM 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 SDM SaaS on an on-going basis and stored in the CloudBees SDM 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