Craft.io allows you to set up two-way synchronization with Azure DevOps. With this integration, you can manage all none-dev resources such as UX, Content, and Research at Craft.io, while keep tracking your dev work with Azure Kanban boards, backlogs, and team dashboards.
The following instructions will take you step-by-step through the setup.
Synchronizing Craft.io to Azure Devops
Connecting to Azure Devops
Data synchronization from Craft to Azure Devops is by manual push. The first step of the configuration will connect Craft.io to Azure Devops.
To get started, click Integrations from the Workspace Settings at the bottom left bar and choose to connect to Azure Devops (available for users with Admin/Team Leader permission only).
You will be prompted to insert your Azure Devops credentials. This includes the Azure Devops Project URL, Username and API token.
Note: Azure DevOps URL version: dev.azure.com/yourproject ; TFS URL version: https://XXX.visualstudio.com .
You can generate an Azure Devops Access Token via User Settings > Security > Personal Access Tokens.
The scope for the newly created access token should be: Work items (read, write and manage).
Note: the default token expiration is 30 days and can be extended up to one year. We recommend setting a reminder before the token expires to update the integration with a new token.
Enter your token and click Next to connect and move to the next screen.
Select the Azure Devops project you want to sync with.
You can now select an Azure Devops area and/or team to sync with. Note that these steps are optional; if you leave them blank, the entire Azure Devops project will be synced with Craft.io. Click Next.
To sync the Azure Devops team workflow with one of the Craft.io teams’ workflows, enable the Sync Workflow toggle, and select a Craft.io and Azure Devops team to sync.
Note: If you already selected an Azure Devops team in the previous step, it will be used for a workflow sync. This will sync statuses (columns) in both systems for the selected teams.
Click Next. The Field Mapping settings open.
Field Mapping Between Craft and Azure Devops
In the Field Mapping step, you can map Craft.io fields with the corresponding Azure Devops fields:
Note the two-way Field Mapping per Craft.io Feature:
Field in Craft.io
Field in Azure Devops
In addition, any custom or formula fields configured in Craft.io can be mapped to a corresponding custom field in Azure Devops. For more about managing custom and formula fields, see this article.
When you finish mapping the fields between the tools, scroll all the ay down and click on 'Save'.
Congratulations! You are now ready for your first sync!
At this point, you can choose to sync the systems for the first time by clicking on 'Continue to Sync', or you can click on 'Finish and exit' and do it later.
You can also choose to skip this step and sync selected 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 on the 3 dots menu next to the integration name and clicking on the 'Sync' button.
First-time sync between Craft.io and Azure Devops
When running sync for the first time you have the option to import Azure Devops project into your Craft.io Workspace, or push Craft.io items into your Azure Devops project.
Note: Import of the entire Azure Devops project to Craft.io is performed once. To enable automatic updates from Azure Devops to Craft.io, you will need to set a Webhook in Azure Devops. See “Synchronize Azure Devops back to Craft.io” section below.
Filter which Craft.io items you want to push to Azure Devops:
The following options are available:
Entire Workspace - Syncs the entire Craft.io workspace to Azure Devops.
Sprints - Allows you to select one or more Craft.io sprint backlogs to be pushed to Azure Devops.
Releases - Allows you to select one or more Craft.io releases to be pushed to Azure Devops.
Click Sync and wait until the sync is finished. Depending on the size of the project, this can take from several seconds to several minutes.
Note: Azure Devops items were created in Craft.io under the Azure Devops Theme Product. You can move them to different Products within Craft.io using drag and drop in the Spec Editor, or by bulk action in the Table view.
Synchronizing Azure Devops Back to Craft.io
The second step of the configuration will allow changes made in Azure Devops to be updated in Craft.io automatically by the Webhook.
From the Workspace Settings, select Integrations and click on "How to Sync Azure Devops back to Craft".
You will see information on how to create a service hook in Azure Devops, as well as the webhook listener URL to use in the webhook configuration. This is a unique URL that contains your product ID. Copy the URL to your clipboard and continue to the webhook configuration in Azure Devops.
In Azure Devops, go to Project Settings > Service Hooks and click the + button.
From the Service dropdown menu, select Web Hooks and click Next.
In the Trigger window, at the Trigger on this type of event, select Work Item Created.
Select the Work Item Type to sync. You can choose Any or select a specific type. If you select a specific type, you will have to repeat these steps for each item type.
In the Action window, enter the provided webhook URL and click Finish.
Repeat the same actions for the Work item updated trigger.
Syncing a Single Item
Sometimes you may want to update or send a single item to Azure Devops. This can be a new item that you created or one that you updated. You can do this from the Azure Devops tab in the item’s Properties panel:
Click 'Sync Item' to sync the item to Azure Devops.
Click the icon next to the 'Item ID' to open the corresponding issue in Azure Devops.
Items Type Mapping Between Craft.io and Azure Devops
The Items type mapping is fixed and cannot be customized. Note the two-way type and entities mapping between Craft.io and Azure Devops:
Type of Craft.io
Type in Azure Devops
CMMI Project Template
Product Backlog item
Scrum Project Template
Agile Project Template
Scrum Project Template
Agile Project Template
Agile Project Template
Task with Parent
Tip: To adjust Craft.io terminology to Azure Devops project terminology and avoid confusion, it is recommended that you change Craft.io terminology in the Workspace Settings (see the user menu), as follows:
Product > Epic and Products > Epics
Epic > Feature and Epics > Features
Feature > User Story and Features > User Stories
Modifying Integration Settings
You can always return and update your mapping configuration from the 3 dots menu next to the integration name:
You can also choose to view a detailed log of the last sync and disconnect Azure Devops integration.