Craft allows you to set up two-way synchronization with Jira. This will allow your development team to keep using Jira for Sprint execution while using Craft for Ideation, Definition, Prioritization, Planning and Workflow management. Craft will then be used by you to manage your none-dev resources such as UX, Content, Research and other teams.
Through the two-way connection, you have the ability to synchronize the following items types: epics, stories, improvements, requirements, bugs, tasks, and subtasks.
There are two steps required to integrate between Craft and Jira. Follow them carefully so that the integration succeeds.
Important - In order to connect to Jira, you are required to have administrative privileges with the Jira project and board, and your product in Jira must have the Epic and Story TYPE in order to connect to Jira.
Important - to prevent importing of deleted Jira issues to Craft, make sure to grant 'Any logged in user' the permission to Delete Issues in Jira (see: Settings/Issues/Permission Schemes/Delete Issues/Application Access).
When you need to integrate with an on-premise JIRA system, you might be required to whitelist Craft's Server IP Addresses in your firewall. By doing so, Craft can connect to your JIRA server to create issues.
Craft's IP Addresses are:
Step 1 - Synchronize Craft to Jira
- Go to main Craft sidebar, select the product and click Sync.
2. The Sync your Product panel opens on the right side of the screen. Click Connect next to Jira in Development section.
3. In order to connect to your Jira project, enter your Jira account URL, your Username and your Password, and press Next.
Note: Make sure you don't use Google Authentication to login to Jira.
4. When you have succeeded logging in to Jira, the Jira projects and boards will be available for you to select. Select the Jira project and Jira board to sync with Craft. Click Next.
5. Type Mapping
At this step, you can map Craft item types with corresponding Jira issues types. You can map the following Craft types:
You can choose to not sync subtasks with Jira. To do so, leave Craft Subtask field unselected.
By enabling Create Labels as Jira Labels you can enable sync of labels in both systems.
You can also create Craft themes as Jira labels, or to not create them at all, or map them to a custom field in Jira on the next step - Field Mapping.
Override item types options allows you to determine what happens if type of the item is changed in one of the systems. You can choose to set Jira (the first option) or Craft (the second option) as a source of truth.
Sync Sprints and Roadmap Containers. Craft sprints and Roadmap Containers will be synced with Jira Sprints and Versions if they have the same names. Sprints and Containers with different names will appear in both systems after sync.
Note: syncing will never delete any items.
6. Field Mapping
At this step you can map the following Craft parameters with corresponding Jira fields:
- Story Points
- Epic Name
- Sync to Component
- Link to Craft
Select corresponding Jira fields in dropdowns.
Sync to Component: If you set a Jira Component in this dropdown, new Craft items will be created in Jira with this Component value.
Note: some fields will require you to set custom Jira fields.
By default, Craft item title and description will be synced with Jira issue title and description, Craft page designs and attachments will be synced with Jira attachments.
When you are done, click Next.
7. Assignee mapping
At this step, you can choose to sync workflow and assignees between one of Craft teams and Jira.
To do so, switch on Sync Workflow toggle.
Once you select a Craft team to sync with, members of this team will be displayed, and you will be assign a Jira user to each team member.
You can leave some users unassigned if there is no match for them in Jira.
When you are done, click Next.
8. You can choose to sync now or later. Click Yes to sync now.
9. Select whether to override items in Craft with items from Jira, override Jira Items with Craft items, or just use the latest date to determine the item to sync.
Note: On the first sync, second option "Override Craft items with Jira items" imports Jira items to Craft product. Import is performed once. To enable automatic Jira to Craft sync, you will need to set Webhook in Jira. See instruction below in this article.
10. Select the parts of your product in Craft you want to push to Jira.
- All Product - will sync the entire Craft product to Jira.
- Containers - allows you to select one or more Craft containers (versions) to be pushed to Jira
- Sprint Backlog - allows you to select one or more Craft 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.
11. Once the sync is completed, you will see a success messages showing what was synced and/or skipped.
You can also download more detailed log here.
Step 2 - Synchronize Jira to Craft
The second step in synchronizing Jira with Craft is to configure the setting in Jira so that changes made in Jira will be reflected to Craft automatically.
1. In Craft, go to Sync panel, and click 'Sync Jira back to Craft' under Jira connection.
You will see information on how to create a webhook in Jira, and a webhook link that you will need to copy and insert in Jira when configuring webhook.
2. In Jira, Go to Settings > System > Webhooks (in the Advanced section). Scroll down to the Advanced tab and select Webhook.
3. Click the +Create a Webhook button, 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' information in Craft.
- 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.
4. Click Create.
Now your two way Craft - Jira integration is enabled. Items will automatically sync via Webhook from Jira to Craft. When you need to push updates from Craft to Jira, go to Sync panel and click Push next to Jira connection.
Please note that you can push changes for All product, one or more Containers or Sprint.s For large projects, we recommend to push changes by Container or Sprint to make a sync faster.
You can also push changes to one single item on item level.
Single Item Sync
- Double-click an item and click Jira tab in the properties panel.
2. For already synced items the following information is displayed:
- Connected as: product shortcut in Jira
- Jira: clickable link to Jira item
- Position: backlog (?)
- Status: item's status in Jira
3. To sync changes made to the individual item, click Sync Item.
Modifying Sync Settings
When Jira is connected, you can configure settings in Type Mapping, Field Mapping, and Assignee Mapping available from 3-dots menu next to Jira connection.
Viewing Last Sync Log
When you have completed setting up the two way connection between Jira and Craft, you have the ability to view items whose status has changed.
To view the synchronization status, go to Sync Panel and in the 3-dot menu next to Jira connection, choose Show Last Sync Log.
The number of items that have been synced or skipped is displayed, and you have the option to download more detailed log by clicking Log.
Disconnecting Jira Integration
To disconnect integration, go to Sync panel > Jira > 3-dot menu > Disconnect. This action will remove links between Craft and Jira items.