This is a complete guide on how to connect and sync your Elements and JIRA tickets. This guide covers permissions, installation, troubleshooting, and use-cases.
Why connect Elements with JIRA?
We often think of Elements.cloud as a one-stop solution for Org change management. For smaller teams, it can serve as a complete capture -> plan -> analyze -> execute suite.
However, when it comes to enterprise-level organizations, it is not going to replace dedicated project management tools .
What is the value of Elements for ticket management?
What is the value of Elements for ticket management?
Elements.cloud is a Change Intelligence Platform: Exceptional for analyzing stories and scoping changes.
Not built for Sprint Planning and Kanban Boards: Not designed to replace specialized project management tools.
Enterprise-level Organizations: Larger teams require more robust planning and execution tools.
Elements.cloud can act as the analytical engine that refines and scopes work items, making them ready for execution in other specialized platforms:
Creating Well-Analyzed Stories/Work Items: Use Elements.cloud to break down and analyze user stories or tasks.
Scoping the Full Impact of Changes: Understand the ripple effects of each change across the organization.
Full scope of work items in your ticketing tools: Thanks to Elements.cloud you can discover and document hidden to-dos. You can therefore ensure that there are no gaps in your scope of tickets and you understand fully the cost and scope of the project.
License prerequisites
You need to have JIRA connection license, which currently is part of our Unlimited license
Supported JIRA connections
We support connection with:
JIRA Cloud Team Managed Projects
JIRA Cloud Company Managed Projects
JIRA Server
Required permissions
Following permissions are required to successfully connect Elements to JIRA:
Elements:
Space administrator permission to set up JIRA connection
Requirement manager permission for account used for authentication to create and update change records in Elements based on JIRA integration
JIRA:
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 JIRA project does not automatically grant the Browse Projects and Create Issues permissions! Check your permissions before proceeding.
Supported issue types and fields
You can connect Elements change tickets to multiple issue types in JIRA
You can connect:
Elements business requirements to any 'parent' issue types (like epics)
Elements user stories to any standard issue types (stories, bugs, defects, etc.)
Sub-task issue type is not supported for mapping
You can map:
Standard JIRA fields (summary & description)
Custom fields (URL, text, rich text area, picklist, number)
Fix-version/release
You currently cannot map Elements fields to JIRA 'look-up' fields, like sprint, component, user, parent issue.
Integration use-cases
We recommend using Elements process maps to document how you work in the form of a UPN diagram.
Ask yourself why you want to use the integration, and what you need to get from it to benefit - what problems will it solve? Document your ideal process using the integration. Which teams are using it? Which issue types do you actually need in Elements, is it just the Epics and stories, or do you need other tasks and bugs too? Which projects do you need, if you use more than one?
Below are two main use-cases for integrating Elements and JIRA
Using Elements to create work items
Using Elements to create work items
At at Elements, we use our Jira integration to manage the development of our own product. The Product team uses Elements to carry out analysis and manage the business requirements/aims. We use:
Requirements and stories to break up work into the user “problems” we want to solve, with stories making up the smaller chunks of work that address the larger problem (requirement).
UPN diagramming capabilities to map out user journeys and experiences. This includes mapping out the current workflow for our target users’ Jobs to be done, as well as the to-be processes using Elements.
Architecture diagrams to map out the underlying product architecture, including ERDs of the different database collections or the different software systems we use. This helps inform our technical analysis when making changes to existing architecture or trying to understand how to add new features.
We link the requirements and stories to this documentation, as well as adding extra contextual information, including mockups, feature request record URLs, and other evidence and information to support the implementation of the business requirement.
Once we have validated the requirement, scoped it out, and documented it thoroughly, we then send the requirement and associated stories to Jira for our team. This is where sprints are planned, tracked, and kept up to date.
The development team has the benefit of our extension to see the added documentation, diagrams, etc., so they can understand the business context of the requirements. This helps them to see the work they’re doing not just as a set of features, but as a solution to a user problem as a whole.
Use the design template to map out your Elements-JIRA integration when change tickets originate in Elements:
Using JIRA to create work items, Elements to refine them
Using JIRA to create work items, Elements to refine them
Teams use Jira as the main source of their business requirements and user requests. Their workflow is:
Generate the tickets in JIRA from user requests and plan the sprint in Jira
JIRA tickets are then imported or automatically synced to Elements.
Stories in Elements are linked to affected Salesforce metadata for impact analysis (documenting affected metadata components and impacted metadata components)
Teams then plan to use the reporting aspects of Elements to generate a list of the changed metadata over a period of time. The metadata in this report is added to their “configuration log” spreadsheet, which the deployment teams use to know which metadata to release. Or Elements stories can be used directly to generate deployments in Copado or Salesforce DevOps Center.
This provides them with the organisational context to every change, as well as an auditable history of everything that was done and touched over time. The product owning team can leverage the benefits of Elements documentation without needin
Use the design template to map out your Elements-JIRA integration when change tickets originate in JIRA:
As part of this use-case, you need to enable auto-sync of any new tickets being created in JIRA to Elements. This ensures that the set of tickets between the 2 systems is the same.
Select your JIRA connection in Space management:
Ensure that the initial status for new stories in JIRA is mapped to the initial status for new stories in Elements. Then you can for each selected issue type turn on auto-sync.
Auto-sync from JIRA to Elements is tied to webhook event of issue being created. That is why the 'first' status of a JIRA issue and Elements story/ requirement need to be mapped for this to work.
Recommended setup
We strongly recommend that you make Elements the application where your work items (business requirements and user stories) originate. Consult this use-case.
Connect to JIRA
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.
Authenticate JIRA Cloud connection
Authenticate JIRA Cloud connection
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.
Authenticate JIRA Server connection
Authenticate JIRA Server connection
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.
Configure the integration
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.
Choose one of the projects to connect with.
You will be asked to confirm the choice and load project data. This step is required because each project can have a different configuration.
Then click 'Add issue type' and choose which issue type to integrate with either business requirements or user stories in Elements.
You can set up and integrate multiple issue types for both user stories and business requirements in Elements.
You will see a screen that will list Elements workflow statuses for either user story or business requirement and standard and custom fields. From the dropdown, choose JIRA statuses and JIRA fields you want to map to the Elements ones.
Key considerations during status and field mappings
Workflow:
You can only map statuses one to one, meaning a status in JIRA can only be mapped to one status in Elements.
When Elements status is unmapped, then when a ticket is moved to that status in Elements, user cannot send updates to JIRA
When JIRA status is unmapped to Elements, then when a ticket is moved to that status, changes will not be reflected in Elements
Fields:
If you are mapping picklist fields, ensure that the picklist values in both Elements and JIRA are spelled the same and are listed in the same order. Otherwise the integration will fail.
Optional: connect Elements releases to JIRA Fix Versions
Optional: connect Elements releases to JIRA Fix Versions
To set up the Release to FixVersion field mapping, go to the issue type(s) you have connected to Elements stories/requirements.
Under the "JIRA fields mapping" header, in the right hand column, find the "Release" field settings. From here, select "Fix versions" as the Jira field and select either one way or 2 way mapping, according to which way you want the integration to work. That's it, you're done!
How it works
The way this works is pretty simple. From Elements to Jira, when you send a new work item to Jira it will create a new FixVersion matching the Release name (if it does not already exist).
Equally, from Jira to Elements, when a story is assigned a new FixVersion, we create that Release in Elements using the same name. In Elements, the release will show all the other work items in Elements with the same Release/FixVersion assigned to it.
Register the webhook
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.
User has no 'Register webhook' permission
User has no 'Register webhook' permission
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:
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.
Enable 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.
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.
Import existing JIRA tickets
Go to list of business requirements and user stories in Elements main menu. Depending on your setup, go to either requirements or stories tab.
Click 'Import' button in the top right corner of the screen. Chose 'Import from JIRA' from the dropdown.
In the window choose from which JIRA development project you wish to import the user stories from (if you have more than one JIRA project connected).
Then from the 2nd dropdown list, select which of the connected issue types you want to import:
From the last dropdown, choose which of the mapped statuses you wish to include in the import request. Only issues in those statuses will be imported.
Depending on the number of user stories being imported, this operation may take some time. A few thousand JIRA issues would take a couple of minutes to sync.
Once the operation is complete, you will receive a notification.
If you receive a notification that some or all issues failed to import, click on the notification to download a detailed report that will list a reason for each failure.
Send Elements ticket to JIRA
In the main menu, select 'Changes'. Then open either the business requirements or stories tab.
First, ensure that your record is assigned to a JIRA dev project.
You assign user stories and business requirements to a JIRA project because you can have multiple JIRA projects connected to the same Elements space. That selection tells Elements which configuration to choose and where to send the ticket.
Select the record you wish to send to JIRA. In the details tab, find the 'JIRA integration' field and press 'Send to JIRA' button.
If you connected to multiple issue types, you will have a choice of which issue type to send the ticket as to JIRA.
Mass-send tickets to JIRA
Start by selecting the stories you want to send. You can do this by selecting the checkboxes on the left of the screen.
To send a story to Jira it must be associated with a connected Dev Project, and must not already have an existing story in Jira. Right click your selected stories to open the context panel and you will see the option to "Send all to Jira".
Once you select this option you will see a window summarising the stories you want to send.
In some circumstances you will be unable to send all your stories. For example, if this story is already connected and exists in Jira, or if you have not selected a Dev Project.
When you press confirm, all stories in the "Stories to send" tab will be sent to Jira, and those that cannot will be skipped.
You should see a notification when the operation is complete.
Limitation: you can bulk-send and bulk-update up to 50 tickets at once to JIRA
Delete JIRA connection
At any time, you can delete your development connection. Just click on the bin icon on the JIRA connections list in your Space's settings:
Deleting a JIRA connection is irreversible. This action does not delete any stories in either Elements 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.
Troubleshooting / FAQ
I can't see the JIRA project I want to connect to
I can't see the JIRA project I want to connect to
Most likely you do not have the “Browse projects” permission for the Jira project you wish to connect to.
When I send tickets to JIRA, I lose all the formatting
When I send tickets to JIRA, I lose all the formatting
If you find that the HTML formatting in your connection is being lost when sending tickets from Elements to Jira you may need to alter the field settings in Jira. It is the rich text fields that usually have this issue.
Go to Project settings → Issues → Fields → Actions/Edit fields → Field configurations
From here you’ll see a list of fields, on the right hand side it should show some options including “Renderers”. Click on this. For the Active Renderers option, instead of Rich Text Field you should select Wiki Style Renderer.
The data is not flowing correctly between fields
The data is not flowing correctly between fields
When field mappings are not working properly it is usually related to one of 3 things.
The field in Jira is not present in all the issue types screens
The field types do not match
The field type is not supported - e.g. lookup fields