1. Syncing items from Jira to Craft

    1. Completing the initial sync

    2. Moving the Items

    3. Syncing your items on an ongoing basis

  2. Syncing items from Craft.io to Jira

  3. Updating Field and type mapping

    1. Default Fields

    2. Optional Fields

Syncing items from Jira to Craft

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:

  1. 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

  • In cases when various teams are working on the same project or the project is mature and includes items that are no longer relevant, it’s recommended to sync only items with a specific label or status using the JQL query.

  • By default, work items with the status ‘Done’ will not be synced into Craft. To sync such items, please utilize the JQL query.

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%“.

Moving the 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:

  1. 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 your 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:

  1. Select as many items as you want to sync by checking the box next to their names.

  2. Navigate to the toolbar at the bottom of the screen.

  3. 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 and 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:

  1. Go to the integrations menu

  2. Click on the options button next to the relevant integration name

  3. 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.

  1. Attachments (visual specs in Craft.io are sent as attachments too)

  2. Title

  3. Description

  4. Sprint

  5. Importance

  6. Dev. Assignee - coming soon!

b. Optional Fields

You can also choose to map the following fields:

  • Release

  • Dates

  • Labels

  • Story points

  • Objective

  • Key Results

  • Value

  • Effort

  • 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.

Did this answer your question?