One of Craft.io’s core functionalities is native integration with development tools, enabling two-way synchronization of items between the two platforms.
The main benefit of integrating Craft.io with your Azure DevOps instance is that it enables the product management org to manage all none-dev resources such as UX, Content, and Research, while easily tracking the progress of the dev work and allowing smooth communication.
The integration supports key components such as hierarchical links, Sprint allocation, and status updates. Custom fields and key attributes can be mapped, in order to provide the clearest picture of the item’s fundamental characteristics.
Table of contents:
1. Connecting your Azure DevOps account to Craft.io
How to reach the Integrations screen
The first step of the integration is to connect Craft.io to Azure DevOps. Click Integrations from the Workspace Settings menu on the top right of the navigation bar and choose 'Connect to Azure DevOps'.
You will be prompted to enter your Azure DevOps credentials. This includes the Azure DevOps URL, Email/Username, API token/password, and connection name.
When filling in the required information please make sure to remove any trailing white spaces from the end of the Azure DevOps URL. Also, use a unique naming convention for ‘Connection name’.
Notes:
For both Azure DevOps Cloud and On-Premise Administrator permission is required to perform the connection.
We recommend creating a generic service account solely for the integration, granting it Admin permissions, and using its credentials when connecting Craft.io to Azure DevOps. This will prevent the need to update credentials etc. in case of an actual user who leaves the company or switches roles.
Integrating with Azure DevOps cloud
To integrate with a Cloud Azure DevOps server, after specifying the URL, insert the email address that is used to log into Azure DevOps.
Then, an API token is required to authenticate Craft.io access to Azure DevOps on an ongoing basis.
Click here to learn how to create an Azure DevOps API token.
Integrating with Azure DevOps On-Prem
To integrate with an On-Premise Azure DevOps 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 Azure DevOps server to create issues.
Craft.io IP address for whitelisting: 35.232.112.68 port 443
In addition to that, integrating with an On-premise Azure DevOps account requires you to insert the password you use to log in to Azure DevOps instead of an API token.
2. Add project integration to your workspace
Adding project integration
After clicking ‘Next’ on the connection screen, you will have the ability to add a project to the integration.
Click 'Add project integration' to continue, or 'Not now' if you wish to complete the integration setup later.
Project Integration specification
Select the first Azure DevOps Project to sync with. You will be able to add additional projects to the connection later on, from the same screen as seen above.
Lastly in this step, make sure to give a unique name to the integration.
Click 'Next' to continue.
Field & Type mapping screen
In the project's ‘Field & Type Mapping’ screen you’re invited to map Craft.io item types (left column) with the corresponding Azure DevOps item types, and map fields you’ve set up in Craft.io as properties with corresponding fields in Azure DevOps.
Primary Types mapping
Align your work item types and hierarchy in Azure DevOps to Craft.io.
This mapping depends on the four Azure DevOps default processes (Basic, Agile, Scrum, and CMMI). To learn more about your mapping options, please read here.
Field mapping
In the following sections of the screen, you can map between fields in Craft.io and their corresponding fields in Azure DevOps.
Primary fields - mapping primary fields between Craft.io and Azure DevOps, such as Azure DevOps Area, Story points, and Releases.
*These fields are not all configured by default, if you wish to map them please contact support@craft.io.
Default fields - mapping Craft.io's default fields with Azure DevOps, such as Objective, Key result, Value, and Effort.
Custom fields - You can choose to map any custom field you create in Craft.io to Azure DevOps and vice versa. Please note that the field types (text, single select, numeric, etc.) must be identical in both tools in order to successfully map.
Once you are done, click 'Save'.
You can go back to the ‘Field & Type Mapping’ screen at any time, clicking on the 3-dots menu next to the project name.
3. Initial sync from Azure DevOps to Craft.io
Next, you'll be directed to perform your initial sync from Azure DevOps to Craft.io. Click on 'Continue to sync' to import your Azure DevOps items now, or choose 'Finish and exit' if you want to do this later.
Sync settings
In this screen, you can select the Area Path to import from, decide which type of issues you want to import, and whether to bring all open issues from your project or only those marked with specific tags. To start the import, click 'Sync'. This may take up to a few minutes.
Once finished, you will receive a sync log, showing which items were imported and which were skipped. If the numbers don't match your expectations, please check your settings to make sure the items that weren't synced match the requirements. This could be due to the mapping in the 'Field & Type Mapping' or due to the usage of tags to sync only specific items. For further assistance, please contact support@craft.io.
If, for any reason, you wish to perform another manual sync from Azure DevOps to Craft.io later on, click on the 3-dots menu next to the project name > click 'Sync from Azure DevOps'.
The sync options screen will open again, and you can configure the settings to import the relevant items.
4. Adding Project Integrations
At this point, you can integrate additional Azure DevOps Projects. Click ‘+Add another Azure DevOps Project’ and repeat the above steps for each of the Azure DevOps projects you would like to integrate with.
Additional authentication will not be required should you wish to integrate with Projects that sit under the same Azure DevOps instance.
5. Setting up a Webhook
Note - a separate webhook is required for every project you integrate with.
At the bottom of the connection area, you can find instructions on how to sync Azure DevOps back to Craft.io. This can be done by setting up a webhook on Azure DevOps’s side, to get updates automatically.
Click to expand for the detailed steps to set up a webhook.
The detailed instructions include a unique URL that contains your workspace 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, three triggers in total need to be set- Work Item Created, Work Item Updated, and Work Item Deleted.
After selecting the Event Trigger to sync, choose the work item type- either stick to the default of any item type or select a specific type.
Note- If you select a specific type, you will have to repeat these steps for each item type.
Next, in the Action window, enter the provided webhook URL and click Finish.
Repeat the same actions for the remaining triggers.
As mentioned above, the webhook needs to be set on AzureDevOps side for each project you integrate with Craft.io. If you require integration with multiple AzureDevOps instances, a separate connection is needed for each one.
How can you tell if the webhook is connected or not?
On the Integrations screen, next to the connection name, you will find the webhook icon. The webhook icon will be lit in blue, to indicate when a webhook is connected and at least one event has been fired from Azure DevOps’s side.
6. Integration settings
For active integrations, the properties of the connection can be modified if and when needed.
Update connection
Needing to update integration settings is a common scenario, whether due to a need to change the API token or password for security reasons or because the person whose user’s credentials were used to create the connection is no longer in the company. For this reason, you can update the connection details, without having to disconnect.
Rename connection
Whether the company branding language changes or there has been a restructure that requires changing the name of the connection, this can be easily done with just a few clicks.
Disconnect connection
Performing this action will cut the connection between Craft.io and the integrated Azure DevOps instance, along with all connected projects.
Note - Should the connection be recreated with the same project(s), the Craft.io item associated with the corresponding item in Azure DevOps will not be restored.