Craft.io allows you to set up two-way synchronization with Jira. The following instructions will take you step by step through the setup.
How it works:
Craft.io allows you to sync a Jira project with each Craft.io workspace. This means that as a Product Manager, you can push items to Jira directly from Craft.io and receive updates as the work progresses in Jira.
The primary steps outlined in this article are as follows:
- Connect Craft.io to Jira. This step involves creating a new integration with Jira and defining how Craft.io items and fields should map to your Jira project's equivalent.
- Syncing in bulk: Decide whether to pull items into Craft.io or push items into Jira. On first sync, you will have the choice to import your Jira project directly into Craft.io to help you get started
- Setup a webhook within Jira to ensure that changes in Jira are automatically synced back to Craft.io
- Pushing single items that you've created or updated in Craft.io to Jira
- Additional information related to modifying your integration settings and configuring Jira on-premise integrations
- Before setting up the connection, please verify that you have administrative privileges for the Jira project and board you plan to integrate with.
- We currently support integrating to a single Jira project at the Craft workspace level. We will release multi-project support within a single workspace in Q1-2020.
- Craft.io will not delete items in Jira. We create and update items but will not delete.
- Integrating with Jira can be a complex task so please reach out to our Customer Success team who will gladly support you throughout the setup.
1. Connecting Craft.io to Jira
Connect to Jira:
The first step of the configuration will connect Craft.io to Jira. Click Integrations from the user menu on the lower left of the sidebar and choose to connect to Jira.
You will be prompted for Jira credentials. This includes the Jira URL, username and API token.
- Please ensure to remove any trailing white spaces from the end of the Jira URL.
- An API token is required only for Jira 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.
Select the Jira project and board to sync with. Click Next to continue.
In the Type Mapping step you can map Craft.io item types with the corresponding Jira types.
See our recommended type mapping between Craft.io and Jira below but please feel free to customise to your own specific needs.
You are also asked to select an override option in case of type differences between Craft.io and Jira. As an example, with the selection below, an item pushed to Jira as a story, but later changed to a task in Jira will appear as a task when synced back to Craft.
- If you've used custom terminology for Section, Feature and Sub-feature then you will see those terms as Craft.io types in the Type Mapping section.
- If you prefer to not map a specific field then click the enabled option to deselect. However, certain types are required and you will not be able to deselect these. Please see notes in the table above for specific examples.
- Sprints and Releases will be synchronized automatically. Please ensure that the names are identical in both Craft.io and Jira. If you do not wish to synchronize Releases then deselect that mapping within the Field Mapping step.
- By default, Craft.io attachments and Page designs are sent to Jira as attachments. You cannot configure the mapping for these types.
Each type in Craft.io and Jira has a set of default fields. In the Field Mapping step we map these fields so that your items transfer seamlessly.
See our recommended field mapping between Craft.io and Jira below. You can always customize the mapping based on your specific Jira configuration:
- Title, Description, Importance and Sprint are sent by default to Jira. You cannot configure this mapping.
- If you've used custom terminology for Release, Objective and Key result then you will see your terms here as field mapping options.
- Any Craft.io custom fields that you have created will appear here as an optional field that you can map to Jira fields.
- If you make a change to your Jira fields during the configuration process then click the refresh icon at the top of the screen and field updates will be loaded in.
In the Assignee Mapping step, you can choose to sync team workflow statuses between Craft.io and Jira. If you choose not to sync workflow, don't worry as you will always be able to see Jira status for a given item within it's properties.
This is an advanced feature so here's some important background:
- Each team in Craft.io has it's own workflow and each workflow step has it's own column. For example, you can have a Craft team called 'Engineering' with workflow columns of 'to do, in progress, done'.
- When you enable workflow sync you are creating a mapping between a single Craft.io team and a single Jira board. For example, you may find it useful to sync your Jira 'Scrum board' columns with your Craft 'Engineering' team's workflow columns.
- When enabling workflow sync, it's important that the Craft team you select has workflow columns that corresponds to the Jira board's columns. For example if your Jira board has columns of 'To Do, In progress, Done' and you select to sync workflow with the Craft.io 'Engineering' team, then that Craft.io team must have workflow columns of 'To Do, In Progress, Done'. Learn more about Craft.io workflows here.
Click the switch to turn 'on' Sync Workflow
Once the workflow sync is toggled on, you are asked to select a team in Craft to sync Jira workflow statuses with.
Congratulations! - you are ready for your first sync!
2. Syncing in bulk
At this point, you can choose to synchronize for the first time or you can do it later. You can also choose to skip this step and sync individual Craft items instead. For more information about syncing a specific item, see ‘Sync a Single Item’ section below.
Note: you can always return to this step by clicking Push button:
First time sync between Craft.io and Jira
When synchronizing you have the option to:
- Push Craft.io items into your Jira project.
- Pull Jira project items into your Craft.io Workspace. For your first sync with Jira, this will import all open Jira items. Closed items in Jira will be ignored.
- A combination of 1 & 2 based on most recent updates in both Craft.io and Jira.
Next filter which specific changes your want to reflect in any push of Craft items to Jira.
The following options are available:
- Workspace - Pushes the entire Craft.io workspace to Jira.
- Releases - 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 the payload, the procedure could take several minutes to complete.
When the sync is completed, you will see messages showing what was synced and/or skipped.
- All Jira issues are created in Craft.io under the Jira Theme product. 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. When you sync again with Jira the updates will be reflected in their current location.
- Any Jira item that does not exist in Craft will be placed in the Jira Theme product. It's therefore important that you regularly triage this product to ensure no additional important items are filtered out of your view.
3. Creating a webhook to automatically sync Jira with Craft
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 workspace 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 an item in Jira and check the corresponding item in Craft. You can also check for webhook connection indication here:
4. Sync a Single Item
Sometimes you may want to push a single Item into Jira. This can be a new Item that you created or one that you recently updated. You can do this from the Jira section in the Craft.io item's right panel:
- Click Sync Item to sync the item to Jira.
- Click the Jira issue ID to open the corresponding issue in Jira.
5. Additional settings
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 IP address for whitelisting:
126.96.36.199 port 8080