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.

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.

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/

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.

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.

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 and epic-level issue types for you. Sub-task level issues are not currently supported in Elements. We strongly suggest you link Epic level issues to Elements requirements, and story level issues to Elements stories.

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 issue type and start again.

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 and 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:

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:

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.

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.

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".

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.

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.