You can connect your Elements Catalyst PRO Space with multiple JIRA projects in multiple domains and send stories for development. While our integration was primarily built with JIRA Cloud in mind you can also integrate with JIRA server. At the moment our JIRA integration works one-way, i.e. you can send stories and updates from Catalyst to JIRA but you cannot import stories from JIRA or fetch updates on stories (other than status changes).
*We do not support connections with JIRA next gen projects yet
*You need to have Space Admin permission to connect to JIRA
- Setting up the connection
- Connecting with JIRA cloud
- Connecting with JIRA server
- Choosing JIRA project to connect to
- Mapping Catalyst story to JIRA story
- Registering the webhook
- Enabling the project
- Sending stories to JIRA
- Deleting the JIRA connection
Setting up the connection
To set up a connection, go to "Space Management" (click on "Manage space" button in the Space list or just click the name of your space at the top of the screen) 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 (we can also provide credentials of the JIRA administrator).
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 Catalyst to JIRA mapping between statuses and fields. You will see the list of Elements Catalyst story statuses for which you can select the target JIRA story statuses.
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.
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.
Enabling the project
Before you enable the project, you must also go to JIRA and create a "Elements Reference" custom URL field for the selected JIRA project & make sure this field is added to all story screens in that project.
Once the setup is complete just enable the project. You can enable/disable the project at any time you want.
Disabling the projects removes JIRA records from all stories that were already sent to JIRA.
Sending stories to JIRA
Go to the Change grid, switch to stories and either create a new story or edit the existing one.
Scroll right on the grid to the "JIRA dev project" column. Select one of the created and enabled development projects.
Once you've confirmed the story, click on the blue arrow in the right side of the screen to open a contextual right panel for the selected story. Click on the three dots next to the name of the story and choose "Send to JIRA".
A new story will be created in JIRA based on your Elements story. If you select an Elements release for a story it will be carried over to JIRA upon sending it. Either a new JIRA fixVersion will be created from that release or the Elements release will be linked to an existing fixVersion if it has the same name. The release data is sent to JIRA once and is not updated when story is updated.
If you edit any data on an Elements Catalyst story the JIRA story does not get automatically updated. You must sync data using the three dots menu as when you first sent story to JIRA.
Deleting the JIRA connection
At any time you can delete your development connection. Just click on the bin icon on the JIRA connections list:
Deleting a JIRA connection is irreversible. This action does not delete any stories in either Elements Catalyst or JIRA but it removes all connection records between the two. To confirm, you must type the name of the project you wish to delete.