Transitioning your work to Craft.io means you can stay focused on what’s important to you as a product manager. To do so, it’s important to ensure your development tool is integrated correctly and that your development team’s workflow isn’t impacted as you transition to Craft.io. In this article, we’ll introduce the key building blocks to successfully set up an integration in Craft.io to your preferred development tool.
We integrate with the world’s most used development tools including Jira, Azure DevOps, Github, Gitlab and Pivotal Tracker. At the end of this article, we’ve included links to detailed pages for each individual integration setups.
There are 4 key steps involved in configuring and managing a development tool integration.
Configure your integration settings so that we know how to map data between Craft.io and the development tool
Import your data to Craft.io to get started and fill Craft up with requirements
Establish a webhook on the development tool to ensure updates in that system are automatically sent back to Craft.io
And on a day to day basis, sync Craft.io with your development tool. You have the flexibility to decide to sync single items or in bulk, and to choose between manual and auto-syncing for updated items that were already synced from Craft.io to the devtool once. Note that Craft.io will never delete items in your development tool.
Let’s dive into each of the steps:
1. Configure the integration:
First, you need to establish an integration with your preferred development tool. Click on the Cogwheel icon on the top right side of your screen to open the Integration settings page.
Each development integration allows you to define the following information:
Configuration step | Status | Why | Requirement |
Which Project or instances to connect with | Required | So Craft.io knows which division of your tool to integrate with and has the authority to do so. | Administrator privileges to the specific project or instance. |
Issue type mapping | Required | To define what each Craft.io issue type maps to, e.g., Craft.io’s Features mapping to User Stories in Jira. This allows us to ensure data types are synced correctly. | Understanding of Craft.io’s data model and decisions on what data types are important to import from your development tool. |
Field type mapping | Required | To define a relationship between Craft.io field types and the available field types in your development tool. E.g., to define which field Craft.io’s Story points should be sent to within your Jira integration. | In certain instances, you may need to configure custom fields within your integration if there are important data in Craft.io you wish to pass down to your development tools. |
2. Import your existing data to Craft.io
Once the configuration is complete, you will have the choice to import your data directly to Craft.io. Here are some pointers:
All data is imported into a new Product within your workspace. You can move these items in bulk using the Product Backlog view, or using drag and drop within the Spec Editor view of your Workspace.
You can decide to not import specific issue types to help keep your Workspace focused.
3. Establish a webhook
A webhook helps ensure that any recent changes in your development tool are automatically sent back up to Craft.io. Setting this up will help ensure that you are kept informed of recent changes automatically without needing to update the connection manually. Each development tool’s article provides in-depth steps to configure each integration’s webhook (see the links at the end of the article).
4. Sync your data
Initial Sync
Once you created new items in Craft and are ready to push them to your development tool, you’ll have the following choices:
Option 1: Single item
Click on any item and select the relevant integration icon on the right-hand side properties. Click Sync item.
If you connected more than one project/area path from your devtool to Craft.io. - choose the relevant one to sync to.
Options 2: Bulk sync
Check the boxes to the left of the relevant items
In the bottom toolbar, click on the integration icon > sync.
If you're syncing to Jira, you will need to choose the project to sync.
If you're syncing to ADO, it will go to the default area path, unless you define it manually first: In the bottom toolbar, click on the 3-dot menu > ADO Area > Select and sync.
Syncing updated items
If you defined manual sync - you will need to click on the sync item each time you make an update to item in Craft. If you have defined the Project/Area Path in the first sync, it will automatically sync to the one you initially chose.
If you defined auto-sync - every update will be automatically pushed to your devtool.
Next up: Review the specific development tool article relevant to your organization: