One of Craft.io’s core functionalities is native integration with development tools, enabling two-way synchronization of items between the two platforms.
The integration supports key components such as hierarchical links, Sprints allocation, and status updates.
In addition to that, custom fields and key attributes can be mapped, in order to provide the clearest picture of the item’s fundamental characteristics.
Table of content:
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 lower left 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’
Please note, for both Azure DevOps Cloud and On-Premise an Administrator's permission is required to perform the connection.
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: 126.96.36.199 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
After clicking ‘Next’ on the connection screen, you will have the ability to add a project to the integration.
Project Integration screen
Once the connection is in place, you will be directed to the Project Integration screen.
On this screen, you will later see all active integrations.
Click to add a new Project Integration.
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.
Lastly in this step, make sure to give a unique name to the integration.
Click 'Next' to continue.
Field & Type mapping screen
In the ‘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 metadata with corresponding fields on Azure DevOps.
Primary Types mapping
Align your item types and hierarchy in Azure DevOps to Craft.io.
On the left, you will see a reflection of your data model and item hierarchy in Craft.io. You can decide whether or not to map Azure DevOps Epic to Craft.io Product level. If you choose to ignore it, it will push all the primary item types one level down.
In the following sections of the screen, you are able to map between fields in Craft.io and their corresponding fields in Azure DevOps.
Primary fields- this section is dedicated to mapping primary fields between Craft.io and Azure DevOps. For example- Azure DevOps Area, Story points, and Releases.
*These fields are not all configured by default, if you wish to map them please contact firstname.lastname@example.org
Default fields- we support the ability to map Craft.io 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 map.
One time sync
Through the Integrations screen, it is possible to perform a sync of your items ad-hoc, either from Craft.io => Azure DevOps or Azure DevOps=>Craft.io.
When choosing this direction, decide whether you want to sync all open issues from Azure DevOps. Alternatively, select to sync specific item type(s) or focus the sync by using tags.
Craft.io => Azure DevOps
If you manage your backlog in Craft.io and you are now at the point where you’re ready to push items to development, you can perform a sync of the entire workspace or specific sprints/releases.
3. Adding Integration projects
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.
4. Setting up a Webhook
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.
The webhook needs to be set up only once per workspace, assuming that all Azure DevOps projects that you integrated into the workspace are from the same Azure DevOps instance. In case you integrate multiple Azure DevOps instances, the webhook will require configuration per Azure DevOps instance.
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.
5. Integration settings
For active integrations, the properties of the connection can be modified if and when needed.
Having the need 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 have the ability to update the connection details, without having the need to disconnect.
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.
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 Jira will not be restored.