Azure DevOps Integration

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.

Click Next.

 

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 Craft.io Feature:

Field in Craft.io	Field in TFS	Notes
Importance	Priority	Optional
Release	Custom Field	Optional
Value	Custom Field	Optional
Effort	Effort	Optional
Story Points	Story Points	Optional
Kano	Custom Field	Optional
Label	Tags	Optional
Objective	Tags	Optional
Key Results	Tags	Optional

 

In addition, any custom or formula fields configured in Craft.io can be mapped to a corresponding custom field in TFS. For more about managing custom and formula fields, see this article.

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 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 TFS

When running sync for the first time you have the option to import TFS project into your Craft.io Workspace, push Craft.io  items into your TFS project or import both directions as described below:

• Override TFS Items with Craft Items - Push Craft items into TFS project.
• Override Craft Items with TFS Items - Pull TFS project into your Craft.io Workspace and push your Craft Workspace into TFS project. Note: import of the entire 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 the first sync.

Filter which Craft.io items you want to push to TFS:

 

The following options are available:

• Entire Workspace - Syncs the entire Craft.io workspace 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 the project, this can take from several seconds to several minutes.

Note: TFS items were created in Craft.io under the TFS Theme Product. You can move them to different Products within Craft.io using drag and drop in the Editor, or by bulk action in the Search and Filter tool. Learn more about Search and Filters 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 Item

Sometimes you may want to update or send a single item to TFS. This can be a new item that you created or one that you updated. You can do this from the TFS section in the item’s right panel:

 

Click Sync Item to sync the item 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:

Type of Craft.io	Type in TFS	Comment
Product	Epic
Section	Feature
Requirement	Requirement	CMMI Project Template
Requirement	Product Backlog item	Scrum Project Template
Feature	User Story	Agile Project Template
Task	Impediment	Scrum Project Template
Task	Issue	Agile Project Template
Improvement	Story
Task	Task
Requirement	User Story	Agile Project Template
Bug	Bug
Subtask	Subtask	Task with Parent
Page Design	Attachment
Attachment	Attachment

 

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.