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.
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 ways—for 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.
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.
As you prepare to build your first Connect app, here are a few things you should keep in mind.
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.
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.
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:
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.
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:
For more information, read App descriptor.
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.
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.
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:
To learn more about Jira entity properties, read entity properties.
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.
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.
The Jira Software REST API covers Jira Software features such as boards, sprints, epics, and more.
The Jira Service Desk REST API covers Jira Service Desk features such as customer requests, queues, and SLAs.
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.
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:
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: