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 from Jira’
4. Select 'Sync all open issues' when you want to import all open issues, or ‘Sync issues matching JQL’ when you wish to import specific issues from your Jira project to Craft.io. Read more on how you can utilize a JQL query.
Important Notes
|
5. The sync could 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 a few ways to achieve this:
Drag and drop the item within the product tree in your Spec Editor.
2. Drag and Drop the item in a Table View (Product Backlog from Example).
3. Click on the item to open it > press the three dots next to the title > click on 'Move to Product' and choose a product from the list.
4. Bulk move of multiple items: in the Table View, check the boxed to the left of the relevant Epics (Features will follow automatically) > go to the Bulk Menu on the bottom of the screen > Click on 'Product' and choose from the list. This may take a few seconds.
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.
If you wish to continue syncing only specific items, please remember to insert your JQL into the webhook as well, or other items will be imported to Craft.io when the webhook is triggered.
When creating a story with no linked parent item, the story will sit under a new Epic under the “Jira Theme %project_prefix%“ Product in Craft.io. The new Epic will have the following naming convention: “Jira Epic %project_prefix%“.
2. Syncing items from Craft.io to Jira
Initial sync
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 for the first time is done manually, in order to avoid overriding the developers’ data.
This can be done in one of the following four 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'.
3. Directly from the Table View
In a Table View, add the 'Jira ID' column > Click on 'Sync item', without opening the item.
Good to know! Once you've synced the item once, you will have a direct link to your Jira work items within Craft.io. You will find it within the item Jira integration tab at the Property panel, or in a Table view with the 'Jira ID' Column. By clicking on it, you will be directed to your correlating issue in Jira.
|
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.
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.
Syncing your items on an ongoing basis
Auto-syncing vs manual syncing
Once an item was synced from Craft.io to Jira once, you can choose what happens when you update this item in Craft.io.
Auto-syncing: every item update will be automatically synced to Jira without a manual sync action being required.
Manual syncing: manually sync items for every update you want to push to Jira. Please note that when you choose manual sync, the 'Sync item' button is always on, and therefore, you need to make sure to click on it after every update.
This step is defined during the initial integration setup, but can be changed later. Here is how:
Go to Settings -> Integrations
Click on 'Integration Settings'
Choose and click 'Save'
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:
Quarter (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.