Last updatedApr 1, 2019

Integrating with Jira Server

Welcome to Jira Server development! This overview will cover everything you need to know to integrate with Jira Server. This includes the P2 framework for building plugins, as well as Jira features and services that you can use when integrating with Jira.

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 Server plugin.

We recommend that you read this entire page if you are new to Jira Server development, but if you want to skip to a specific section, use the links below:

  • Developing with Plugins2: The framework for building plugins for Jira Server
  • Modules: Integration points for interacting with Jira, including the Jira UI
  • Entity properties: Key-values stores in Jira
  • Jira APIs: This includes REST APIs for the Jira platform and the Jira products
  • Webhooks: User-defined callbacks over HTTP
  • Security: Authentication and authorization
  • Jira Data Center: Tools for working with the Jira UI, like the Atlassian Connect JS API, conditions, and context parameters.

Building a plugin

If you want to build a plugin for Jira Server, then you will be using the Atlassian development platform via the Atlassian SDK. The platform consists of the Plugins2 framework (also known as the P2 framework) and a set of components that provide useful tools to developers, as shown below. 

For more information on the components in this platform, see Atlassian Platform Common Components.

A Jira Plugins2 is a bundle of code, resources and configuration files that can be installed in Jira. Fundamentally, s can do following:

  • Add content or features, like pages, panels, reports, JQL functions, gadgets, in certain defined places in the Jira UI via modules.
  • Make secure requests to Jira's APIs.
  • Listen and respond to webhooks fired by the Atlassian application.

For more information, see Jira Plugins2 overview

 Developing with Plugins2

If you are building a plugin with Plugins2, you'll also need to understand a number of key development processes:

  • Implementing security: Implementing security is a crucial part of integrating with Jira. Robust authentication and authorization help prevent malicious access to customer data. To learn more about authentication and authorization for Jira Server, see the Security overview.
  • Listing your plugin on the Atlassian Marketplace and implementing licensing: Listing your plugin on the Atlassian Marketplaces and licensing it are necessary, if you want to make your plugin available to the public. See the Marketplace documentation for more instructions.
  • Designing your plugin: Since Plugins2 plugins can insert content directly into the Atlassian host application, it is critical that plugins are visually compatible with the Atlassian application's design. Our designers and developers have created a number of resources to help you with this:

Modules

Modules are the most important component of your Jira plugin or integration. Simply put, these are the integration points that your plugin uses to provide rich interactions with Jira. There are two types of modules: basic iframes that allow you to display content in different places in Jira, and more advanced modules that let you provide advanced Jira-specific functionality. Jira Service Desk and Jira Software also have their own application-specific modules (UI-related only).

For more information, see About Jira modules.

Entity properties

Entity properties are key-value stores attached to Jira objects, that can be created, updated, and deleted via the Jira REST APIs. This is a powerful system for storing data on the Jira host; it easily support imports, exports, and migrations between instances because the data is stored locally with the Jira instance. Here's how entity properties can help you with your Jira Server integration:

  • Simplify your plugin 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, see entity properties

Jira APIs

Use the Jira APIs to interact with Jira from your integration. You should also read the Security overview to learn how to secure any interactions with the Jira APIs.

REST APIs

You should use the REST APIs for most integrations. Each of the Jira Server applications have a REST API that allows you to interact with the objects in that application (e.g. sprints for Jira Software). The Jira Server platform REST API is common to all Jira products.

To learn more, see About the Jira Server REST APIs. See the Webhooks section below as well.

Java APIs

The Java APIs are primarily used when building a P2 plugin. Similar to the REST APIs, each of the Jira Server applications have a Java API.

Webhooks

Webhooks are outgoing messages from Jira that allow your plugin 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 Software and Jira Service Desk.

To learn more about webhooks, see Webhooks

Jira Data Center

Jira Data Center is the enterprise implementation of Jira, providing high availability and performance at scale. If you are developing for Jira Data Center, you need to be aware of the guidelines for building plugins for high availability and clustered environments.

To learn more, see About Jira Data Center.

Get started

Time to get hands-on with Jira Server development! Read our Getting started guide to learn how to set up a development environment and build a Jira Server plugin.