Halo Service Desk Guides
Documentation to assist with the setup and configuration of the Halo Service Desk platform
Azure DevOps Integration
To activate the Azure DevOps integration, go to Configuration > Integrations and enable the module. Please note that this integration cannot be used in tandem with the Jira integration. Once enabled, click into the integration to begin configuring it:
The first step requires you to specify your Azure DevOps instance URL, including your organisation name. You then need to specify a personal access token – the hint for this fields contains a URL which tells you how to obtain this.
Ensure Software Releases is turned on in the configuration by pressing the ⊕ button in the Configuration Screen.
The next step is to link products in Halo with your projects in Azure DevOps. The most efficient way of doing this is to use the “Import Azure DevOps Projects” button:
This will create all projects in Halo that exist in Azure DevOps, and will assign the Azure DevOps project key to the database. You can do this process manually if you wish, by going to Product and Release Setup > Setup Products.
Creating and Updating Work Items:
To create work items in Azure DevOps from tickets in Halo, you will need to create an action which has a system use of “Create Bug/Issue/Work Item”. The action configuration screen can be accessed through the Azure DevOps module.
Once you have chosen the system use, an extra box will be available for you to choose which type of work item you would like to be created. If you would like to be able to choose between a selection of work item types, you will need to create a separate action for each type.
When performing this action to create the work item, if you have the above checkboxes enabled for the priority and target date fields, Halo will attempt to set the priority and target date of the work item. You must have correctly mapped your priorities across both applications (see later in this guide for more information) for this to be successful. The target date can only be set on certain work item types e.g. Epic.
Important: It is not possible to set the status of a work item when it is being created.
Once the work item has been created, any update to the linked ticket's status, priority or target date in Halo will be automatically synced to DevOps if you have enabled this feature.
It is also possible to sync comments to Azure DevOps. To do this, you must have an action which has the note field, accompanied by the "Send to Azure DevOps" field.
When performing the action, if the note is not blank and the Send to Azure DevOps field is checked, the note will be pushed to the work item. It is not possible to push a comment to DevOps in the same action as creating a work item.
Tip: A good idea is to create a new action that has all of the fields you are syncing between Halo and DevOps. This gives you one place to make any necessary changes in Halo.
Important: The Send to Azure DevOps field only controls when a comment is posted to the work item. If adding an action and changing the status, priority or target date, but the Send to Azure DevOps field is not selected, the state, priority or target date of the work item will still be updated.
Linking a Ticket to a DevOps Work Item:
In order for the action to update the correct work item in Azure DevOps, you will need to add the 'Product' field onto the ticket type and have the ticket select the correct product from the dropdown.
Receiving Updates from Azure DevOps:
New tickets can be created in Halo whenever a new work item is created in Azure DevOps. To set this up, you must subscribe to a webhook in Azure DevOps. Webhooks can be configured by going to Project Settings > Service Hooks. Follow the instructions in the Azure DevOps module and register a new webhook for the trigger "Work item created".
In the webhook you will need to use the Username and Password in the DevOps integration page, as shown in the screenshot below. The URL for the webhook will be your URL with /api/notify afterwards. For example, it would be http://localhost:49489/api/notify.
Once configured, you must choose a ticket type that new tickets will be created as. It is also possible to set the User of the ticket equal to the User who created the work item. This requires you to have a user record that matches either the creators name or email address. If no match is found, or you do not want to enable this feature, new tickets will be assigned to the default user that you specify.
Note: The priority fields value is not contained in the work item created webhook unless you physically change it on the new work item screen. If you would like to ensure that the priority of the new ticket always matches the priority of the new work item when they are created, you should set the default priority of the ticket type in Halo to the default priority value for work items in DevOps.
It is also possible to update tickets in Halo with the status, priority, target date, assigned agent and comments of a work item. Again, this involves configuring webhooks. The trigger for the webhooks should be equal to "Work item updated", and a separate webhook should be created with a field filter for each field listed below.
Important: It is possible to create only one webhook with the field set to "All". Whilst this will work, it means that every single time any field is updated in Azure DevOps, this information will be passed to Halo, which can add unnecessary overhead to the API.
Once configured, whenever any of these fields are updated on a work item, their corresponding fields will be updated on the linked ticket in Halo.
Priority & State/Status Mappings:
To successfully update the priority and status of tickets in Halo and work items in Azure DevOps, you must map status and priority values across the two applications. This can be done using the two tables at the bottom of the configuration screen:
Using the above setup as an example, if the status of a ticket in Azure DevOps is updated to Done, then the status of the linked ticket in Halo will be set to Closed.
If you would like to display the work item ID and assigned agent on the ticket in Halo, enable this setting under the Advanced heading.
These fields will then display on the side panel of a ticket under the Ticket Information heading (if they are set):
Note: The Assigned Agent field will not be set until the ticket is assigned to an agent in Azure DevOps.
Other fields such as target date can be made visible on a ticket by adding the field to the ticket type's field list.