Setting up two-way synchronization with Jira.
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.
- Authentication: Setting up the connection between your Craft.io Workspace and your Jira account.
- Mapping: Syncing between Craft.io and Jira
- Adding additional Jira projects
- Setting up the webhooks: Pushing items that you've created or updated in Craft.io to Jira
- Before setting up the connection, please verify that you have administrative privileges for 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.
Authentication: Connecting Craft.io & Jira
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.
Mapping: Syncing 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 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 Section, 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 Page designs 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.
- See our recommended field mapping between Craft.io and Jira below. You can always customize the mapping based on your specific Jira configuration:
- Title, Description 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.
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.
Adding additional Jira projects
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.
Setting up webhooks
To get automatic updates on Craft.io from Jira, you will need to set up a webhook. Each project will need its own individual webhook set up.
- 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 the name of the Webhook listener.
- Status - Select whether the Webhook status will be enabled or disabled.
- URL - Enter the URL copied from the 'Sync Jira back to Craft.io' information in Craft.io.
- Issue Related Events - Enter the name of your project in the format of project = <your project>.
- Issue - Check created, updated, and deleted.
- Issue link - Check created and 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:
- Remember to duplicate the webhook creation process for each individual Jira project.
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:
126.96.36.199 port 443