You can connect your Elements Space with multiple JIRA projects in multiple domains and send stories for development. You can also mass-import your JIRA stories for validation and refinement in Elements.
While our integration was primarily built with JIRA Cloud in mind you can also integrate with JIRA server.
We do not support connections with JIRA next gen projects
- Required permissions
- Setting up the connection
- Connecting with JIRA cloud
- Connecting with JIRA server
- Choosing JIRA project to connect to
- Mapping Elements story to JIRA story
- Registering the webhook
- Creating the Elements Reference URL field
- Enabling the project
Only users with Space Admin permissions can set up JIRA connections. Read this article to learn more about different permissions and how to set them up.
Setting up the connection
To set up a connection, go to "Space Management" and select "Connections" in the left-hand menu. Then choose the JIRA tab at the top and click "New project" to create a new development project for JIRA.
Connecting with JIRA cloud
You will need to specify your JIRA cloud server URL, username, and JIRA API token.
Connecting with JIRA server
You will need to provide your JIRA base server URL, username and password (you can type it in the "JIRA API token" field).
You also need to make sure your JIRA server is not restricted to internal network access only. If it is you will need to make sure your server is open to port 443 for following IP addresses (these are the 3 IP addresses for Q9Elements within AWS Dublin data centre):
Choosing JIRA project to connect to
After that you will be taken to the setup page.
Select one of the JIRA projects in your JIRA server to load the data from. Once you confirm the choice, you cannot change it later. If you wish to load a different JIRA project, create a new JIRA connection project instead.
Mapping Catalyst story to JIRA story
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 Elements story to a given status it will push the story on JIRA side to the mapped status and vice-versa.
Warning: make sure your workflow transitions in Elements & in JIRA are configured correctly to avoid any errors.
Scroll down to set up fields mapping with JIRA.
The summary, release & description fields are automatically mapped and fixed. If you want to, you can map acceptance criteria field or any custom field that you have. You can choose whether the updates should be flowing from Elements to JIRA or should the connection work both ways for these fields.
Registering a webhook
If the JIRA user credentials used to set up the development project belong to "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 succesfully enabled.
If the webhook is already registered in JIRA, you don't have to re-register it.
If the JIRA user credentials used to set up the development project DO NOT belong to "JIRA administrator" then after selecting the JIRA project you won't have an option to register the webhook. You will need to send the webhook URL to your JIRA administrator.
The webhook should be enabled for following events:
- issue: created, updated, deleted
- comments: created, updated, 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.
Creating the Elements Reference URL field
Before you enable the project, you must create the "Elements Reference" custom URL field in JIRA for the selected JIRA project & make sure this field is added to all story screens in that project.
However, if you are connecting Elements to multiple JIRA projects then with each subsequent connection you just need to make sure that the original field is available on story screens in all target projects.
Creating multiple "Elements Reference" custom URL fields for different projects may result in errors.
Enabling the project
Once the setup is complete just 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.