Last updatedOct 22, 2019

Integrating with Jira Software Cloud

Jira cloud integration graphic

Welcome to Jira Software Cloud development! This overview will cover everything you need to know to integrate with Jira Software Cloud. This includes the Atlassian Connect framework, which is used to integrate with Atlassian Cloud applications, as well as Jira features and services that you can use when building an app.

Important! API changes to improve user privacy

On 24 May 2018 we announced upcoming API changes to Jira Cloud REST APIs, webhooks, and extension points to support user privacy. Before continuing, please ensure you have read the change notice.

Hello world

If you already know the theory and want to jump straight into development, read our Getting started guide to build your first Jira Cloud app.

Atlassian Connect

Atlassian Connect is a framework for building apps for Atlassian Cloud products, including Jira Cloud. Apps can extend the Jira Cloud user interface, access the APIs, and respond to events. We recommend using Atlassian Connect to build apps, but you can also integrate with Jira Cloud in other waysfor example, by using 3LO apps or calling the REST APIs using basic authentication.

Connect handles discovery, installation, authentication, and seamless integration into the Jira cloud UI. A Connect app could be an integration with an existing service, a new feature, or even a new product that runs within Jira cloud.

Connect apps are web applications that operate remotely over HTTP. To an end user, an app appears as a fully integrated part of Jira cloud. Once your app is installed, its features are delivered right from the Jira cloud UI. This deep integration is part of what makes Connect apps so powerful.

You can write a Connect app with any programming language and web framework, and deploy it in many different ways. From massive SaaS services to static apps served directly from a code repo, Connect is designed to let you connect anything to Atlassian products.

Jira cloud integration graphic

For example, the Who's looking app (source) is a Java application that runs on the Play framework and is hosted on Heroku. It uses the Jira REST API to retrieve the details of users viewing an issue, persists it locally (checking if users are still watching via an XHR heartbeat), and displays it in a web panel module on the Jira issue view screen.

Important things to know

As you prepare to build your first Connect app, here are a few things you should keep in mind.

Atlassian frameworks

We've written two different frameworks to help you get started. These frameworks are officially supported by Atlassian and help to generate some of the plumbing required for your Connect app:

For more information and additional frameworks and tools, see Frameworks and tools.

Security

Connect uses HTTPS and JWT authentication to secure communication between your app, Jira cloud, and the user.

Your app can only make requests based on permissions specified by the scopes in your app descriptor. When installing your app, the Atlassian administrator is presented with the choice to grant these permissions.

Read Security for Connect apps for more details.

Atlassian design guidelines

Since Connect apps can insert content directly into Jira cloud, it is critical that apps are visually compatible with Atlassian design. Our designers and developers have created resources to help you:

  • Atlassian Design Guidelines — Our design guidelines define core interactions with the Atlassian applications.
  • Atlaskit — Atlaskit is a library of reusable front-end UI components.

The Atlassian Marketplace

You can list your app publicly on the Atlassian Marketplace so other Jira cloud users can install it, or list it privately if you don't intend to sell or distribute your code. Private listings use secret tokens that you can generate yourself.

Atlassian Marketplace also lets you sell your app commercially. Read our licensing guide and selling on marketplace page for more details.

App descriptor

The basic building block of a Connect app is the app descriptor, a JSON file that provides basic information about the Connect app and how it works with Jira cloud. You use the app descriptor to specify:

  • Modules you use to extend the user interface
  • Endpoints that Jira cloud can call in response to certain events (webhooks)
  • Authentication and authorization information
  • Links and other information about your app and your company

For more information, read App descriptor.

Working with the UI

The main way your app integrates with the Jira cloud UI is with modules. A module is a UI element such as a tab or a menu that your app uses to interact with the Jira cloud UI. For example, your app can use a module to add a panel to the top of customer portals.

There are two types of modules: basic iframes that allow you to display content in different places in Jira cloud, and more advanced modules that let you provide additional functionality. Jira Service Desk and Jira Software also have their own specific UI modules.

For more information, read Extending the user interface.

Handling events with webhooks

Webhooks are outgoing messages from Jira cloud that allow your app or integration to react to events, like someone transitioning an issue or closing a sprint. Like the REST APIs, there is a set of platform-level webhooks and additional advanced webhooks for Jira cloud. You can also configure an automation rule to fire a custom webhook that notifies your app when something happens. For example, you might use a webhook to alert your remote application when an SLA is about to be breached.

To learn more about webhooks, read Webhooks.

Storing data with entity properties

You can store data in the form of entity properties: key-value stores, attached to Jira cloud objects, which can be created, updated, and deleted via the Jira cloud REST APIs. This is a powerful system for storing data on the Jira cloud host; it easily supports imports, exports, and migrations between instances because the data is stored locally with the Jira cloud tenant. Here's how entity properties can help you with your Jira cloud integration:

  • Simplify your app or integration by reducing how much data you store on your own server.
  • Improve performance by evaluating entity_property_equal_to conditions in-process.
  • Implement advanced features like JQL integration using search extractions.

To learn more about Jira entity properties, read entity properties.

REST APIs

The Jira REST APIs let your app get and modify data in Jira cloud. For example, with the Jira cloud REST API, you can retrieve a queue's requests to display in your app or create requests from phone calls.

Jira cloud REST API

The Jira platform REST API covers most of the primary operations with basic Jira objects such as issues, projects, users, dashboard, and more. This REST API is common to all Jira products.

Jira Software Cloud REST API

The Jira Software REST API covers Jira Software features such as boards, sprints, epics, and more.

Jira Service Desk Cloud REST API

The Jira Service Desk REST API covers Jira Service Desk features such as customer requests, queues, and SLAs.

Integrating with on-premises tools

Jira Software Cloud provides OAuth 2.0 credentials that you can use to integrate Jira Software Cloud with on-premises (self-hosted) tools. Currently, you can integrate with build and deployment tools, such as Jenkins. In future, this mechanism will also support development information from tools like repository managers. See Integrating Jira Software Cloud with on-premises tools for details.

Looking for inspiration?

If you are looking for ideas on building the next Jira Software Cloud integration, here are a few examples of what you can build on top of Jira Software Cloud:

  • Retrospective Tools for Jira -- This app provides a number of tools for reviewing your project history, and with the Jira Software API they're able to let you filter by board, or even overlay your swimlanes.
  • Epic Sum Up -- This app adds a panel to the issue view that allows you to review your epic progress or every issue within the epic.
  • Tempo Planner for Jira -- This app fetches information from boards, epics, and backlogs using the Jira Software API, and lets you plan your work by team member.

Next steps

Ready to get hands-on with Jira Cloud development? Read our Getting started guide to learn how to set up a development environment and build an app.

These resources will also help you start developing: