You can connect your Elements Catalyst 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.
*We do not support connections with JIRA next gen projects yet
- Required permissions
- 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
- Chrome extension for JIRA
- Sending stories to JIRA
- Deleting the JIRA connection
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" (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.
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.
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 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.
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.
Any update to an Elements story will automatically be pushed to JIRA and vice-versa. Depending on your field mapping fields will be updated instantly.
Sending story documentation to JIRA
Install our chrome extension to be able to access any documentation, salesforce metadata or diagrams that you linked to a story during your analysis.
Once you install the extension and log in (using the same credentials you use for the application) choose the right JIRA project connection details to enable the right panel for stories from that project.
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.