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. Note that in this article we refer to Azure DevOps as TFS.
Synchronizing Craft.io to TFS
Connecting to TFS
Data synchronization from Craft to TFS is by manual push. The first step of the configuration will connect Craft.io to TFS. To get started, click Integrations from the user menu at the lower left and choose to connect to TFS (Visual Studio).
You will be prompted for TFS credentials. This includes the TFS URL, username and Access token.
Note: Use your Visual Studio URL (https://XXX.visualstudio.com) in the URL field.
You can generate a TFS Access Token via User Settings > Security > Personal Access Token.
The scope for the newly created access token should be: Work items (read and write). Enter your token and click Next to connect and move to the next screen.
Select the TFS project you want to sync with.
You can now select a TFS area and/or team to sync with. Note that these steps are optional; if you leave them blank, the entire TFS project will be synced with Craft.io.
To sync the TFS team workflow with one of the Craft.io teams’ workflows, enable the Sync Workflow toggle, and select a Craft.io and TFS team to sync.
Note: If you already selected a TFS 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 TFS
In the Field Mapping step, you can map Craft.io fields with the corresponding TFS fields:
Note the two-way Field Mapping per story:
Congratulations! You are now ready for your first sync!
At this point, you can choose to synchronize the systems for the first time or you can do it later. You can also choose to skip this step and sync selected stories instead. For more information about syncing a specific story, see ‘Sync a Single Story’ section below.
Note: you can always return to this step by clicking Push button:
First time sync between Craft.io and TFS
- Override TFS Items with Craft Items - Import Craft product into TFS project.
- Override Craft Items with TFS Items - Imports TFS project into Craft.io product and Craft product into TFS project. Note: import of TFS project to Craft.io is performed once. To enable automatic updates from TFS to Craft.io, you will need to set a Webhook in TFS. See “Synchronize TFS back to Craft.io” section below.
- Sync according to the last update - not applicable on first sync.
Select the parts of your product in Craft.io that you want to push to TFS:
The following options are available:
- All Product - Syncs the entire Craft.io product to TFS.
- Releases - Allows you to select one or more Craft.io releases to be pushed to TFS.
- Sprint Backlog - Allows you to select one or more Craft.io sprint backlogs to be pushed to TFS.
Click Sync and wait until the sync is finished. Depending on the size of project, this can take from several seconds to several minutes.
Note: TFS items were created in Craft.io under the TFS Theme Def feature, ordered by their Epics. 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. For more about Search and Filters look Here
Synchronizing TFS Back to Craft.io
The second step of the configuration will allow changes made in TFS to be updated in Craft.io automatically by Webhook.
From the user menu, select Integrations and click Sync TFS back to Craft.
You will see information on how to create a service hook in TFS, 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 TFS.
In TFS, 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 Story
Sometimes you may want to update or send a single story to TFS. This can be a new story that you created or one that you updated. You can do this from the TFS section in the story’s right panel:
Click Sync Item to sync the story to TFS.
Click the TFS item ID to open the corresponding issue in TFS.
Type Mapping Between Craft.io and TFS
The type mapping is fixed and cannot be customized. Note the two-way type and entities mapping between Craft.io and TFS:
Tip! To adjust Craft.io product terminology to TFS project terminology and avoid confusion, it is recommended that you change Craft.io terminology in the Product Settings (see the user menu), as follows:
Feature->Epic and Features->Epics
Epic->Feature and Epics->Features
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 and disconnect TFS integration.