Syncing items from Jira to Craft.io
Once your integration with Jira is successfully in place, it’s time to import your items from Jira to Craft.io, which will ensure full transparency of the dev work, all within the Craft.io platform.
Initial sync
To complete the initial sync of your Jira project to Craft.io, please complete the following steps:
Go to Settings -> Integrations.
2. Click on the ‘Options' (three dots icon) next to your Jira project name.
3. Click on ‘Sync’
4. Choose the sync direction ‘Jira=>Craft’, select 'Sync all open issues' from the bottom drop-down and then click on ‘Sync’.
5. In cases when you don’t want to sync all items from your Jira project to Craft.io, you can utilize a JQL query. Select ‘Sync issues matching JQL’ and insert your query in the designated text box.
Important Notes
|
6. The sync should take a few minutes, and once completed, the items that were synced will appear in your Craft.io spec editor under a bucket named: “Jira Theme %project_prefix%“.
Organize your imported items
Now you can start moving the items within the spec editor into the appropriate parent item in the hierarchy. There are two ways to achieve this:
The first way is to drag and drop the item within the product tree.
2. The second way is to click on the item. Press the three dots next to the title and click on 'Move to Product/Epic'.
Syncing your items on an ongoing basis
With a webhook in place, from now on, creating new items and editing existing items will automatically sync into Craft.io. The parent-child relationship between epics and stories in Jira will be maintained as items are synced to Craft.io.
All new items that are synced into Craft.io via the webhook will appear under the Jira theme in the spec editor. Once you move them under the appropriate parent, they will remain there.
When creating a story with no linked parent item, the story will sit under an Epic Bucket in your product tree in Craft.io. These can be easily identified by going to the Spec Editor and searching for an Epic with the following naming convention: “Jira Epic %project_prefix%“ within “Jira Theme %project_prefix%“.
2. Syncing items from Craft.io to Jira
After completing your planning and prioritization work in Craft.io, your item(s) is ready to be pushed to Jira. Keep in mind that syncing items from Craft.io to Jira is done manually, in order to avoid overriding the developers’ data.
This can be done in one of the following five ways:
1. Properties Tab in the Properties Panel
The first way to sync an item with Jira is by double-clicking on the item to open the Item’s properties panel. Then click 'Sync' under Dev Status.
2. Jira Tab in the Properties Panel
The second way to sync an item to Jira is by double-clicking on the item to open the Item’s properties panel. Then click on the ‘Jira’ tab. Then click 'Sync item'.
Good to know! You can always have a direct link to your Jira work items within Craft.io at all times. Here's how to find it. Within the Jira integration tab, you can click the icon next to the Jira item ID to open the Jira ticket in a new tab.  |
3. Integrations in Workspace Settings
The third way is by going to the Integrations menu and clicking on the ‘Options' button (three dots icon) next to your Jira project name, and selecting 'Sync' from the menu.
Next, choose the sync direction ‘Craft=>Jira’ and select whether you want to sync the entire workspace, a specific sprint or release, and click on 'Sync'.
4. Bulk syncing
Bulk syncing from the Table/Kanban views allows you to sync multiple items to Jira at once. You can do it by following these steps:
Select as many items as you want to sync by checking the box next to their names.
Navigate to the toolbar at the bottom of the screen.
Click on the Jira icon to sync all the items at once.
5. Jira ID field
The Table View allows fast and easy identification of items that haven’t been synced to Jira yet.
This can be done by opening a Table View and adding a ‘Jira ID’ column. Items that include a ‘Sync item’ button rather than presenting their Jira ID, are items that haven’t been synced to Jira yet. Click the 'Sync item' button inside the column itself in order to sync them.
Deleting an item in Jira
If an item is deleted in Jira, the item will not automatically be erased in Craft.io, though the sync will stop working. As a best practice, we recommend changing the item’s status within Craft.io to ‘cancelled’ or moving it to the parking lot.
3. Updating Field & Type mapping
The Craft.io<>Jira integration allows you to fully customize how Craft.io fields are mapped in Jira. The initial Field & type mapping is defined during the integration set up. However, you can always go back and update the mapping. By following these steps:
Go to the integrations menu
Click on the options button next to the relevant integration name
Select ‘Field & type mapping’
a. Default Fields
The following items are automatically mapped to the relevant fields in Jira by default, so no adjustments are needed.
Attachments (visual specs in Craft.io are sent as attachments too)
Title
Description
Sprint
Importance
Dev. Assignee
b. Optional Fields
You can also choose to map the following fields:
Release
Dates
Labels
Story points
Objective
Key Results
Value
Effort
Jira Advanced Roadmap Teams
Jira Advanced Roadmap Initiatives
Custom fields - You can choose to map any custom field you create in Craft.io to Jira and vice versa, as long as the field types (text, single select, numeric, etc.) are the same in both tools. Some examples include RICE, MoSCow, Region, and T-shirt size.
We also recommend watching this short video that we've created and shows all the different options of syncing items from Craft.io to Jira:
If you get stuck, please reach out to our Customer Success team. Our team is made up entirely of product experts and responds fast.