Connecting with JIRA

JIRA cloud; JIRA server; company managed projects; team managed projects

Ksawery Lisinski avatar
Written by Ksawery Lisinski
Updated over a week ago

You can connect your Elements Space with multiple JIRA projects in multiple domains and send and update stories for development. We support connecting with JIRA server and both Team Managed and Company Managed projects for JIRA cloud.

Prerequisites

  • Enterprise license (or have an active Trial)

  • Space admin permission to set up JIRA connection

  • Browse Projects permission for all projects that need to be connected

  • Create Issues permission for all projects that need to be connected

Being an administrator of a project does not automatically grant the Browse and Create permissions instead it is often inherited from another role. e.g. Users

TIP Some JIRA projects use different nomenclature for "Stories", and this is a crucial step to have an issue type "Story" in your project, to be able to integrate Elements with JIRA.

Video overview

Watch this quick video to see how you can connect Elements to JIRA Cloud: company managed project. Or 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.

Then choose the JIRA tab at the top and click "New connection" 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. You will also need to provide the name for the connection. Description is optional.

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). Note: ensure that you don't enter your server URL ending with "/".

If you are using Http protocol instead of Https you may have difficulties in connecting to Elements. This is for security reasons, please reach out to us if you have any issues.

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 the following IP addresses (these are the 3 IP addresses for Q9Elements within AWS Dublin data centre):

  • 52.50.27.226

  • 52.17.196.12

  • 52.48.228.227

If you want to use the browser extension with your Jira Server instance please reach out to us at support@elements.cloud, stating the URL for your instance, and we can activate this for you. This is because we do not automatically support showing the extension in Server instances due to security restrictions.


Configuring 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 confirm the choice, you cannot change it later. If you wish to load a different JIRA project, create a new JIRA connection project instead.

Selecting an issue type to link

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 an Elements 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 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 too.

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 successfully 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 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'. Give it a name '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, 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. You cannot restore these.

Did this answer your question?