This article is specifically for users who are using a Jira Cloud instance. If you are using Jira Server the setup is similar, but please use this article for guidance.

Note: Jira Server will be deprecated in 2024.

Article outline

Prerequisites

Video overview

Watch this quick video to see how you can connect Elements to Jira Cloud: company managed project. Alternatively, you can keep reading for a step-by-step guide.


Creating a new Jira connection

To set up a connection, go to "Space Settings" and select "Connections" in the left-hand menu.

Choose the "Jira" tab at the top and click "New connection" to create a new development project for Jira.

Once you click to create a new connection you will see the following window open.

Specify the JIRA type as Jira Cloud. You will need to input your JIRA cloud URL, username (usually your email), and JIRA API token. You will also need to provide a name for the connection. Adding a description is optional but can be useful if you are connecting lots of projects.

Your Jira Cloud URL should follow the format https://[yourJiraDomain].atlassian.net/

Configuring your Jira connection

Once the Jira connection has been established, you need to configure how Jira and Elements will work together. This requires picking the Jira project and configuring user story mapping for fields and statuses.

Load Jira project

Select one of the Jira projects to load the data from.

Once you have chosen a project and loaded it you cannot change it. If you've made a mistake you can delete this connection project and create a new one. You can create and connect multiple Jira projects in your Space, but you cannot connect the same project more than once.

Selecting an issue type

Once you've loaded your chosen project you can choose an issue type to link.

From the stories settings panel, navigate to the list of issue types and select which one you want to link:

We will load all story-level issue types for you, but you can only choose one type. Epics and sub-task level issues are not currently supported in Elements.

Note: Once you have chosen your issue type you cannot change this. You will see a warning window to confirm your choice:

If you do make a mistake you will have to delete the connection and start again.


Mapping Elements stories to Jira stories

Once the Jira project data is loaded, you can set up Elements to Jira mapping between statuses and fields. You will see the list of Elements story statuses for which you can select the target Jira story statuses.

If you move an Elements story to a given status it will push the story on the Jira side to the mapped status and vice-versa.

Scroll down to set up your standard and custom field mapping with Jira.

The summary, release & description fields are automatically mapped and fixed. If you want to, you can map the acceptance criteria field or any custom field that you have. You can choose whether the updates should be flowing from Elements to Jira or if you'd like the connection to work both ways for these fields.

You can also choose whether or not to send tags to Jira.

A couple of things to remember:

  1. You must ensure the field you map is available on the relevant issue screen in Jira, otherwise you will see an error message when making changes to the linked story.

  2. You should ensure the fields you map are of the same type. For example, only map date fields to date fields, list to list, text to text, etc...

  3. If you are trying to map a "User picker" field in Jira you will only be able to send changes one way (from Jira to Elements). Link it to a text field in Elements and we can populate it with the User name value, but we can't make changes from Elements into Jira for this field type.

Registering the Webhook

If the Jira user credentials used to set up the development project belongs to the Jira administrator then after selecting the Jira project you can click "Register webhook" to set it up automatically in Jira. You will see a green notification message informing you that the webhook was successfully registered, and it will continue to show it as long as the webhook is successfully enabled. If already registered you will not need to re-register.

If the Jira user credentials used to set up the development project DO NOT belong to the Jira administrator then after selecting the JIRA project you won't be able to register the webhook. You will need to send the webhook URL to your Jira administrator.

The webhook should be enabled for the following events:

  • issue: created, updated, deleted

  • comments: created, updated, deleted

  • project: deleted, soft deleted

Once the webhook is manually registered in Jira the connection will work; but because user credentials do not belong to the Jira administrator, you will not be able to see the webhook status in real-time. Instead, you will see the webhook status based on the last successful action.

OPTIONAL: Creating the Elements Reference field on JIRA side

This step is now optional.


If you currently have the Reference field present you do not need to make any changes. Our integration will work exactly the same with or without it.

You may choose to create the "Elements Reference" custom field in JIRA for the selected JIRA project. This field will store a reference to Elements user story (that is connected either through import from JIRA or sending stories to JIRA from Elements). This then allows us to keep stories in both systems in-sync. If you do so, you must ensure this field is added to all story screens in that project.

There is a different workflow for setting this field for Team Managed and Company Managed projects.

For Team Managed projects:

Team Managed projects have simple and self-contained configuration.

Go to project settings in the left menu.

Select issue types from the loaded sub-menu.

Then, add a new field of type "Short text" and call it "Elements Reference".

For Company Managed projects:

Company Managed projects offer much more functionality, but they are more difficult to configure.

Click on the 'Gear' icon in the top icon menu. Select 'Issues' from the dropdown.

Then, create a new custom field of type URL called "Elements Reference".

Then, you need to associate the new field with ALL screens for user stories in your target JIRA project.


Enabling the project

Once the setup is complete, all you need to do is enable the project. You can enable/disable the project at any time you want.



Warning: Disabling the project removes JIRA records from all stories that were already sent to JIRA.

It will not delete any stories or data, just remove the connection between them.

You might be also interested in:

Did this answer your question?