This article outlines the following steps to help you smoothly set up your Jira integration and connect and synch Craft.io to one or multiple Jira projects.
Before setting up the connection, please verify that you have admin access permissions to the Jira project and board you plan to integrate with.
Craft.io can create and update items in Jira but can not delete them.
Integrating with Jira can be a complex task so please reach out to our Customer Success team or chat with us directly via in-app support and we'll gladly support you throughout the setup.
1. Connecting your Craft.io Workspace and your Jira account.
The first step of the configuration will connect Craft.io to Jira. Click Integrations from the Workspace Settings menu on the lower left of the sidebar and choose to connect to Jira.
You will be prompted to enter your Jira credentials. This includes the Jira URL, username, and API token.
Please ensure to remove any trailing white spaces from the end of the Jira URL.
An API token is required only for Jira cloud. Click here to learn how to create your Jira API token.
For the Jira username field, please insert the email address you’re using to connect to Jira.
2. Mapping Item types and Fields between Craft.io and Jira
Select the first Jira project and board to sync with. You will be able to add additional integrations for additional projects later on. Make sure to give a unique name to your integration. Click 'Next' to continue.
Next, in the Type Mapping step, you can map Craft.io item types with the corresponding Jira Item types, and map fields you’ve set up in Craft.io as metadata with corresponding fields on Jira.
See our recommended type mapping between Craft.io and Jira below but please feel free to customize to your own specific needs.
If you've used custom terminology for Epic, Feature, and Sub-feature then you will see those terms as Craft.io types in the Type Mapping section.
Releases will be synchronized automatically. Please ensure that the names are identical in both Craft.io and Jira. If you do not wish to synchronize Releases then deselect that mapping within the Field Mapping step.
By default, Craft.io attachments and visual specs are sent to Jira as attachments. You cannot configure the mapping for these types.
Each type in Craft.io and Jira has a set of default fields. When Field Mapping, we map these fields so that your items transfer seamlessly.
Title, Description, Sprint and Importance are sent by default to Jira. You cannot configure this mapping.
If you've used custom terminology for Release, Objective and Key result then you will see your terms here as field mapping options.
Any Craft.io custom fields that you have created will appear here as an optional field that you can map to Jira fields.
If you make a change to your Jira fields during the configuration process then click the refresh icon at the top of the screen and field updates will be loaded.
After you finish mapping all relevant fields, scroll all the way down and click on "Save".
Congratulations! You are ready for your first sync! Select ‘Continue to pull’ if you want to pull all the data from the selected Jira project to Craft.io right now, or ‘Finish and Exit’ if you want to add another Jira Project or to pull the data later (you can always come back to it).
3. Connecting more than one Jira project to your Craft.io workspace
At this point, you can add additional Jira Projects from multiple Jira accounts. Click on the ‘+Add another Jira Project’ and repeat the above steps (Authentication and Mapping) for each of the Jira projects you would like to integrate to.
4. Setting up the webhooks to automatically sync back items from Jira to Craft.io
To get automatic updates on Craft.io from Jira, you will need to set up a webhook.
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 (so if you integrated a few Jira projects from your Jira instance to the same workspace, the webhook will apply to all of them).
On the Integrations screen, an icon will indicate if a webhook has been connected. Below that icon, you will see instructions with information on how to create a webhook in Jira, as well as the webhook listener URL to use in the webhook configuration.
This is 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.
Once a webhook is successfully connected, you’ll see an icon indicating the connection is successful.
The webhook creation process needs to be performed only once per each individual Jira account/instance you integrated into the Craft workspace. Only if you integrate a few Jira projects from different Jira accounts you will need to repeat the webhook creation process per account.
Jira On-Premise Integration
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: 220.127.116.11 port 443
Please note that when syncing with an On-premise Jira account, you will need to insert the Password you use to login to Jira instead of an API token when inserting your credentials - see screenshot:
Both the Jira username (email address) and Password needs to have Admin access permission to your Jira account.
5. Syncing Items between Craft.io and Jira
When syncing your items from Craft.io to Jira, you can select to sync either:
The entire workspace
A specific Sprint/Release
An individual item (Epic/Feature)
We've created a short video to show all the different options of syncing items from Craft.io to Jira: