Craft.io allows you to set up two-way synchronization with Jira. The following instructions will take you step by step through the setup.
Synchronize Craft.io to Jira
Before setting up the connection, please verify that you have administrative privileges with Jira project and board.
Connecting Craft.io to Jira
The first step of the configuration will connect Craft.io to Jira. Click Integrations from the user menu at the lower left and choose to connect to Jira.
You will be prompted for Jira credentials. This includes the Jira URL, username and API token.
Note: An API token is required only for Jira on-cloud. Click here to learn how to create your Jira API token. For Jira server on-premise, simply use your Jira login username and password. For more information about Jira on-premise integration see section 'Jira On-Premise Integration' below.
Click Next to connect and move to the next screen.
Select the Jira project and board to sync with.
Note: a product in Craft.io connects to a single project and board in Jira.
Click Next to continue.
Type Mapping Between Craft and Jira
In the Type Mapping step, you can map Craft.io types with the corresponding Jira types:
See below our recommended type mapping between Craft.io and Jira. You can always customize the mapping based on your specific Jira configuration:
You are also asked to select an override option in case of type differences between Craft.io and Jira.
Field Mapping Between Craft and Jira
In the Field Mapping step, you can map Craft.io fields with the corresponding Jira fields:
See below our recommended field mapping between Craft.io and Jira. You can always customize the mapping based on your specific Jira configuration:
Assignee Mapping Between Craft and Jira
In the Assignee Mapping step, you can choose whether or not to sync team workflow statuses between Craft.io and Jira (i.e ToDo,In Progress, Done). If you choose to sync workflow statuses, you can map assignees between a Craft.io selected team and Jira. To do so, switch on the Sync Workflow toggle.
Once the workflow sync is toggled, you are asked to select a team in Craft to sync Jira workflow statuses with. Upon first connection, Jira board columns will be synced into Craft.io’s workflow for the selected team. For more about the Workflow Kanban view, look Here
Congratulations! - you are now ready for your first sync!
At this point, you can choose to synchronize the systems for the first time or you can do it later. You can also choose to skip this step and sync selected stories instead. For more information about syncing a specific story, see ‘Sync a Single Story’ section below.
Note: you can always return to this step by clicking Push button:
First time sync between Craft.io and Jira
When running sync for the first time you have the option to import Jira project into your Craft.io Product, import Craft.io Product into your Jira project or import both directions as described below:
- Override Jira Items with Craft Items - Import Craft product into Jira project.
- Override Craft Items with Jira Items - Imports Jira project into Craft.io product and Craft product into Jira project. Note: import of Jira project to Craft.io is performed once. To enable automatic updates from Jira to Craft.io, you will need to set a Webhook in Jira. See “Synchronize Jira back to Craft.io” section below.
- Sync according to the last update - not applicable on first sync.
Select the parts of your product in Craft.io that you want to push to Jira.
The following options are available:
- All Product - Syncs the entire Craft.io product to Jira.
- Containers - Allows you to select one or more Craft.io releases to be pushed to Jira.
- Sprint Backlog - Allows you to select one or more Craft.io sprint backlogs to be pushed to Jira.
Once you have completed your selection, click Sync. Depending on the size of your product, the procedure could take several minutes to complete.
When the sync is completed, you will see messages showing what was synced and/or skipped.
You can also download a more detailed log.
Note: All Jira issues were created in Craft.io under the Jira Theme feature, ordered by their Epics. You can move them to different features across Craft.io using drag and drop in the Editor or by bulk action in the Search and Filter tool. For more about Search and Filter, look Here
Synchronize Jira Back to Craft.io
From the user menu, select Integrations and click Sync Jira back to Craft. You will see 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 product 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.
To verify your webhook configuration, try to update a story in Jira and check the corresponding story in Craft. You can also check for webhook connection indication here:
Sync a Single Story
Sometimes you may want to update or send a single story to Jira. This can be a new story that you created or one that you updated. You can do this from the Jira section in the story’s right panel:
- Click Sync Item to sync story to Jira.
- Click the Jira issue ID to open the corresponding issue in Jira.
Modifying Integration Settings
You can always return and update your mapping configuration from the 3 dots integration menu:
You can also choose to view a detailed log of the last sync, disconnect Jira integration or update your API token.
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's IP address for whitelisting:
188.8.131.52 port 8080