Extending the Jira Cloud user interface with Connect

The most common (and most powerful) way for apps to extend Jira Cloud is by adding content directly to the Jira user interface.

Jira Cloud provides a number of Connect modules to provide different types of content. All Jira Cloud UI modules use iframes to sandbox content. There are three types of modules for apps to provide UI elements:

Location-based modules

These modules provide content in a specific location in the Jira Cloud UI, as defined in your app descriptor. Within the Atlassian developer community, these module types are commonly referred to as web fragments. They include:

• Web item: displays a link or button. These can be used to target (open) other modules like pages or dialogs
• Web section: provides a location to group several web items together
• Web panel: display content in a specific context with Jira Cloud (like in a panel on the issue view page)

Available locations for location-based modules

Locations for web items, web sections, and web panels are available across Jira Cloud. Consult the linked pages below for a comprehensive list of locations available on each page in Jira Cloud. There may be more valid locations that aren't documented below, but we don't guarantee that we support them.

• Issue view
• Project sidebar
• Jira administration (global settings)
• User profile menu
• [Jira home container (global navigation)]
• Jira project settings
• Jira Software boards

New Jira issue view modules

We're currently rolling out a new issue view for Jira Cloud, with three new extension patterns: quick-add buttons, to add content to help describe issues, Issue context panels, which provide users a quick way to get information related to the issue from your app, and glances, which let users include and show contextual information from your app on issues. You can read more about these patterns on our new issue view UI locations page, and take a look at the design guidelines to see how you can increase your user base and provide a great user experience.

Pages and dialogs

Jira Cloud provides support for pages, which display content on a full screen page. There are several types of page modules. General pages are added to the Jira global sidebar, but there are other types that are available in specific locations. Review the documentation to see the various types and their uses.

Jira also provides a dialog module type that can be opened either by a user clicking a button you provide or inside your app's iframe via the Dialog JavaScript API module.

Advanced UI modules

Jira Cloud also provides specific module types for certain types of UI content that extend specific Jira features. These include:

• Issue tab panel: provides a location in the tabbed content section of the issue view (where comments on an issue are located)
• Dashboard items: allows apps to provide a gadget to display on Jira Cloud dashboards
• Project admin tab panels: provides a new page in the project settings area of Jira
• Report: provides a page type that will be rendered in Jira Cloud's project reports page
• Search request view: renders a custom view of a search result that's accessible from the Jira issue navigator
• Workflow post-functions: this module contains both a webhook for apps to be notified when an issue transition occurs, and a location to provide a configuration screen for the user

Jira Software- and Jira Service Desk-specific locations

Jira Software also provides locations for web items and web panels on boards, and Jira Service Desk provides several dedicated module types for integrating with the agent and customer views on tickets. You can learn more about these special module types in the Jira Software Cloud and Jira Service Desk Cloud modules pages.

Non-UI modules

There are also a number of Jira Cloud modules that extend other concepts in Jira, where Jira will handle the rendering of your data. The most common of these are Issue Fields, which allow your app to provide fields that will be treated as native Jira Cloud custom fields, and Webhooks, which allow your app to be notified when events take place in Jira Cloud. There are also modules related to permissions, time tracking, and keyboard shortcuts. See the full Jira Cloud modules reference to learn more

Conditions

Most often, you won't want to load all of your modules on every page, for every user, every time. You can specify conditions in your app descriptor to determine which of your app's UI modules Jira cloud should display at which times. For example, you may want to display a certain panel if the current user is an administrator, or if a certain property on an issue has been configured.

To learn more, read conditions.

Atlassian Connect JavaScript API

The Atlassian Connect framework provides a JavaScript API to allow your app iframe to interact with the content around it on the page in Jira cloud. To use the JavaScript API, simply include the all.js file in the scripts in each of your pages. The JavaScript API includes methods for:

• messaging between multiple iframes
• automatic resizing for your content
• advanced Jira UI actions like opening date pickers and the create issue dialog
• making XHR requests to Jira REST resources without requiring CORS
• and much more!

To learn more, read the JavaScript API documentation.

Context parameters

Frequently, the content you show in a panel will vary depending on the context around it (like the current issue, board, user, or project). When Jira cloud makes a request to your app to load an iframe, it can send additional context parameters to tell your app how to respond to the request and which content to display. There are some standard context parameters (like user language and timezone) as well as Jira cloud-specific parameters.

To learn more, read context parameters.