One of Craft.io’s core functionalities is native integration with development tools, enabling two-way synchronization of items between the two platforms.
The integration supports key components such as hierarchical links, Sprints allocation, and status updates.
In addition to that, custom fields and key attributes can be mapped, in order to provide the clearest picture of the item’s fundamental characteristics.
1. Connecting your Jira account to Craft.io
How to reach the integrations screen
The first step of the integration is to connect Craft.io to Jira. Click Integrations from the Workspace Settings menu on the lower left of the navigation bar and choose 'Connect to Jira'.
You will be prompted to enter your Jira credentials.
This includes the Jira URL, Email/Username, API token/password and connection name.
When filling in the required information please make sure to remove any trailing white spaces from the end of the Jira URL. Also, use a unique naming convention for ‘Connection name’
Please note, for both Jira Cloud and On-Premise an Administrator's permission is required to perform the connection.
Integrating Jira Cloud
To integrate with a Cloud Jira server, after specifying the URL, insert the email address that is used to log into Jira.
Then, an API token is required to authenticate Craft.io access to Jira on an ongoing basis.
Click here to learn how to create a Jira API token.
Integrating with Jira On-Prem
To integrate with an On-Premise Jira server, you may be required to whitelist Craft.io's Server IP addresses in your firewall. By doing so, Craft.io can connect to your JIRA server to create issues.
Craft.io IP address for whitelisting: 188.8.131.52 port 443
In addition to that, integrating with an On-premise Jira account requires you to insert the Password you use to log in to Jira instead of an API token.
2. Add project integration to your workspace
After clicking ‘Next’ on the connection screen, you will have the ability to add a project to the integration.
Project Integration screen
Once the connection is in place, you will be directed to the Project Integration screen.
On this screen, you will later see all active integrations.
Click to add a new Project Integration.
Project Integration specification
Select the first Jira Project to sync with. You will be able to add additional projects to the connection later on.
Specifying the Jira Board will later support synchronizing Sprints with Craft.io.
Lastly in this step, make sure to give a unique name to the integration.
Click 'Next' to continue.
Field & Type mapping screen
In the ‘Field&Type Mapping’ screen you’re invited to map Craft.io item types (left column) with the corresponding Jira item types, and map fields you’ve set up in Craft.io as metadata with corresponding fields on Jira.
Primary Types mapping
Align your item types and hierarchy in Jira to Craft.io.
On the left, you will see a reflection of your data model and item hierarchy in Craft.io. Here you define which item types will map with these fields and update when synchronizing.
In case there are primary item types you do not wish to synchronize with Jira you can set those to ‘Ignore’.
If you have additional item types in Jira, these can be mapped by clicking on adding secondary types fields. Bear in mind that for these item types the sync goes in one direction, Jira=> Craft.io.
In the following sections of the screen, you are able to map between fields in Craft.io and their corresponding fields in Jira.
Primary fields- this section is dedicated to mapping primary fields between Craft.io and Jira. For example- Jira Components, Story points, Releases/quarters, and Jira teams.
*These fields are not all configured by default, if you wish to map them please contact firstname.lastname@example.org
Default fields- we support the ability to map Craft.io default fields with Jira, such as Objective, Key result, Value, and Effort.
Custom fields - You can choose to map any custom field you create in Craft.io to Jira and vice versa.
Please note that the field types (text, single select, numeric, etc.) must be identical in both tools in order to map.
Through the Integrations screen, it is possible to perform a sync of your items ad-hoc, either from Craft.io => Jira or Jira=>Craft.io.
When choosing this direction, decide whether you want to sync all open issues from Jira, or alternatively, sync issues matching a JQL query.
Craft.io => Jira
If you manage your backlog in Craft.io and you are now at the point where you’re ready to push items to development, you can perform a sync of the entire workspace or specific sprints/releases
Learn more on how to sync items in this article.
3. Adding Integration projects
At this point, you can integrate additional Jira Projects. Click ‘+Add another Jira Project’ and repeat the above steps for each of the Jira projects you would like to integrate with.
Additional authentication will not be required should you wish to integrate with Projects that sit under the same Jira instance.
4. Setting up a Webhook
At the bottom of the connection area, you can find instructions on how to sync Jira back to Craft.io. This can be done by setting up a webhook on Jira’s side, to get updates automatically.
Click to expand for the detailed steps to set up a webhook.
The detailed instructions include a unique URL that contains your workspace ID.
Copy the URL to your clipboard and continue to the webhook configuration in Jira.
In Jira, go to Jira Settings > System, scroll down to the Advanced section and select Webhooks.
Click the + Create a Webhook button, and enter the required information:
Name - Enter a unique name for the Webhook listener.
Status - Select 'Enabled'.
In the "Events" section check all the boxes under Comment, Issue link, Issue, Version, Worklog, and Sprint (For example: under 'Issue' check the boxes for "created", "updated", "deleted").
Click 'Create'. Your two-way Craft.io-Jira integration is now enabled, and items will automatically sync via webhook from Jira to Craft.io.
The webhook needs to be set up only once per workspace, assuming that all Jira projects that you integrated into the workspace are from the same Jira instance. In case you integrate multiple Jira instances, the webhook will require configuration per Jira instance.
How can you tell if the webhook is connected or not?
On the Integrations screen, next to the connection name, you will find the webhook icon.the webhook icon will be lit in blue, to indicate when a webhook is connected and at least one event has been fired from Jira’s side.
5. Integration settings
For active integrations, the properties of the connection can be modified if and when needed.
Having the need to update integration settings is a common scenario, whether due to a need to change the API token or password for security reasons or because the person whose user’s credentials were used to create the connection is no longer in the company. For this reason, you have the ability to update the connection details, without having the need to disconnect.
Whether the company branding language changes or there has been a restructure that requires changing the name of the connection, this can be easily done with just a few clicks.
Performing this action will end the connection between Craft.io and the integrated Jira instance, along with all connected projects.
Note- Should the connection be recreated with the same project(s), the Craft.io item associated with the corresponding item in Jira will not be restored.