Last updatedOct 22, 2019

Integrate Jira issues with your application

Many organizations around the world rely on Jira as a source of truth in their business processes. Jira Software has more than 37,000 customers and Jira Service Desk is used in over 20,000 organizations.

Atlassian offers Jira REST APIs that allow you to easily integrate with Jira Cloud, Server, and Data Center. In addition to integrating with our REST APIs, Jira also provides you with a framework that allows you to customize Jira's UI with an app. You can reach new prospects by listing your app in the Atlassian Marketplace .

Integrating on the Atlassian platform

The Atlassian platform provides different tools and solutions for integration and extension:

  • Product integration: Use the REST APIs and webhooks. Authenticate using OAuth1 or Basic Authentication.
  • Atlassian Connect: Use REST APIs and webhooks as well as surface information inside Jira using UI extension points. This framework uses JSON Web Token authentication and provides in-app discovery & installation.

Head over to Integrating with Jira Cloud to learn more about the frameworks, features, and services that you can use.

Integration categories

There are three categories of integration that you can develop:

  • Enhance your app with Jira REST APIs:
  • Create, update, or delete Jira issues from your application or service
  • Read data from Jira to display issues in your application
  • Enhance and extend Jira issues:
  • Show info from another application on the Jira Issue page
  • Automatically update or transition issues from your app
  • Add your content to Jira projects:
  • Add a page to the Jira project sidebar
  • Add custom reports to the Jira reports section

We're only going to look at examples from the first three points to gain more of an understanding what's involved with building each.

Enhance your application with Jira REST APIs

Create a Jira issue from your application or service

Integrating Jira into your service is a great way to make your service more robust.

Let's take a look at an example of this pattern we call a one-way integration currently in production. A one-way integration is the most basic form of integration and the most simple to implement.

Sauce Labs

SauceLabs creates a modal form right in their UI that allows users to capture bug information.

How to do it

The first thing you need to decide before writing a line of code is which authorization to Jira will you use. You have two choices:

  • OAuth Authentication (OAuth 1.0a)
  • Basic Authentication

We recommend that you use OAuth over basic authentication, unless you are building tools like personal scripts or bots. With basic authentication, the username and password are sent repeatedly with requests and cached on the web browser, which is much less secure than OAuth (even if credentials are sent via SSL/TLS for basic HTTP). OAuth requires more work to implement, but it uses a token-based workflow which is much more secure.

Resources

Jira REST APIs needed

Another way to enhance your application or service is to pull in relevant Jira issues into your user interface using Jira REST APIs. Use JQL to pull in all issues from a specific project or tag issues with Entity Properties and pull just those issues back. Use JQL to search for issues of a certain criteria and display those. The possibilities are endless.

Entity properties allow apps to add key/value stores to Jira entities, such as issues or projects. These values can be indexed by Jira and queried via the REST API or through JQL.

FrontApp

FrontApp uses the Jira REST API to display existing issues into its UI. Users can then select a relevant issue to attach FrontApp information to the Jira issue.

How to do it

Again you'll need to decide how you will authenticate with Jira, being basic or OAuth authentication.

Resources

Jira REST APIs needed

Enhance and extend Jira issues

Show info from another app on the Jira Issue page

Lastly, you can add value to your application or service by adding contextual information on a Jira page. With an Atlassian Connect app you can extend predefined UI locations to any issue.

An Atlassian Connect app is a web application that you host and that Jira admins can install into their instance of Jira Cloud. Once they install your app they will have access to your application or service right in Jira.

There are many ways to extend Jira's UI but here we will look specifically at enhancing a Jira issue with web panels.

Harvest

Harvest extends Jira by adding in a time tracking widget into a predetermined UI extension point.

Resources

Code examples

Next steps

Hopefully, you've gained an idea of what's possible. Integrating Jira issues with your application or your integration with Jira makes your application that much more important to the ecosystem.

Need more help? Head on over to the Atlassian Developer Community and start a conversation with other developers in the Atlassian Ecosystem.