One of Craft.io’s core functionalities is native integration with development tools, enabling two-way synchronization of items between the two platforms.
The main benefit of integrating Craft.io with your Jira instance is that it enables the product management org to manage all none-dev resources such as UX, Content, and Research, while easily tracking the progress of the dev work and allowing smooth communication.
The integration supports key components such as hierarchical links, Sprint allocation, and status updates. 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 top right 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’
Notes:
Craft.io supports the Basic authentication method (User email + API token/ password ) - see further details below.
Creating the integration with Jira requires Project Admin permission for the specific Jira projects you'd like to connect with Craft (relevant for both Jira Cloud and On-Premise).
We recommend creating a generic service account solely for the purpose of the integration, granting it with Project Admin permission, and using its credentials when connecting Craft.io to Jira. This will prevent the need to update credentials etc. in case of an actual user who leaves the company or switches roles.
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: 35.232.112.68 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.
Field mapping
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 support@craft.io
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.
One-time sync
Through the Integrations screen, it is possible to perform a sync of your items ad-hoc, from Jira to Craft.io.
You may sync all open issues from Jira, or choose to sync issues matching a JQL query.
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.
Creating the webhook requires Global Admin permission for Jira, however, installing the webhook is a one-time action that can be performed by the Jira admin or another relevant person in your IT team, and will not require sharing their credentials with Craft.
Click on "How to sync Jira back to Craft.io" to expand on 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", and "deleted").
Click 'Create'. Your two-way Craft.io and 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.
Update connection
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.
Rename connection
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.
Disconnect connection
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.