MS Azure DevOps Connector

The Microsoft Azure DevOps Connector connects ASM to Azure DevOps using API methodology.

Alemba is currently reviewing and updating the whole of the connector section, including all subsections. Expect this section to be updated by end of June, 2025.

About the ASM to Azure DevOps Connector

The Microsoft Azure DevOps Bi-Directional Connector connects ASM to Azure DevOps using API methodology, enabling you to create work items in DevOps from Calls in your ASM System, and create calls in your ASM System from work items in DevOps.

• The Microsoft Azure DevOps Connector enables you to integrate with any type of work item across all DevOps projects

• You can use Azure DevOps to update calls in ASM

• Calls in ASM can update or create work items in DevOps

This guide outlines how to set up bidirectional integration between Azure DevOps and your Alemba Service Management (ASM) system to create and update tickets.

OAuth 2.0 and Personal Access Tokens

Alemba recommends that you use the Personal Access Token over OAuth (PAT). However, should you decide to use OAuth 2.0, the callback URL needs to be that of the ASM callback URL (which should have been added to the app registration in Azure). Eg. https://{server-name}/{system-name}/oauth2callback.htm

Scope of the ASM to Azure DevOps Connector

The Microsoft Azure DevOps Connector is a Bi-directional connector that allows ASM to be connected to any MS Azure DevOps instance, both Cloud or On Premise using the Azure DevOps Services REST API 5.0 (Formerly TFS).

Get started with the REST APIs for Azure DevOps Services and Azure DevOps Server - Azure DevOps Services REST APIMicrosoftLearn

REST API- TFS Version Mapping

An MS Azure DevOps Webhook ensures that Work Items (Epic or Product Backlog Item) created and updated in Azure DevOps will trigger events such as Call creation and update in ASM using the Alemba RestAPI.

Exclusions

• The connector does not manage MS Azure DevOps Users, Groups and Group Memberships.

• Call Forwarding is not be supported.

• Connector does not perform any action on events such as Work Item “Deleted” or “Restored”.

Prerequisites

• Azure DevOps Setup: Ensure you have an active project with a defined process and at least one work item type.

• Personal Access Token (PAT): Create a PAT in Azure DevOps to facilitate secure API access.

• Service Hooks: Configure webhooks to trigger actions based on specific events in Azure DevOps to create calls in ASM from work items in Azure DevOps.

Configure ASM and Azure DevOps Integration, Step-By-Step

Installing the Microsoft Azure DevOps Connector

After installation, the Alemba.Connector.Azure.DevOps.dll file should exist on your server.

Note: You may need to run an IIS reset to stop unnecessary processes that will prevent the installation from running. On the Application Server, go to Start > Run (as Admin), and type iisreset. Be aware of other users before doing an IIS reset.

Installation with ASM Server Console Service

1. Open the ASM Core Server Console.

2. For each system, right-click the system name. From the menu that appears, select Database Tasks > Run Custom SQL Script .

3. In the Run Custom SQL Script dialog box, navigate to the Config folder in your system directory

4. Select the appropriate SQL installation script. For example, to install the CSV Connector select Infra.Connector.CSV.Install.scp

5. Open the file to run the script.

6. Select No when prompted if other any other scripts need to be executed. The Server Console then parses the query files. When completed, close the Server Console.

7. Go to Start > Run, and type iisreset.

8. Select OK. This completes the installation of the connector that is now ready for use within ASM Core.

Installation with Powershell

Installation of the connector with PowerShell involves the command Invoke-SQLScript

1. Access the Application Server for ASM.

2. Open Powershell and execute the following (replace [system name] with the name of your system):

Invoke-SQLScript -System [system name]- Alemba.Connector.Azure.DevOps.Install.scp ".\script.sql

Additional Considerations

• You need the permission Integration Setup in the General Access Security Role, to configure and use the Microsoft Azure DevOps Connector.

• To create calls in ASM from work items in Azure DevOps, the DevOps project must have Service Hooks configured for ASM.

Configure Azure DevOps for ASM

Process Overview

At a minimum, you will need a valid Project in Azure with a Process and at least one work item. To this work item, you will need to setup the fields to suit your particular configuration. A PAT is needed for the integration and finally, service hooks to control it.

Using Azure DevOps - Click Here for everything you need to know

• Setup your Project and Process

  1. Create a New Organization, or select an existing one

  2. Create an inherited process and add the fields you will need to the work items for the process. You must include a field to capture the ASM reference number (CALL_NO, etc...)
  3. Add a new Project to the Organization

     1. Create a test project and apply your customized inherited process to it to verify the changes and Fields (Add a Work Item).

  4. Open Project Settings in the lower left corner

  5. Click Service Hooks

  6. Add desired Web Hooks, See "Configuring Web Hooks"

     • Ensure you have the correct clientID. See "Client ID"

• Create a PAT (Personal Access Token)

  About Tokens

  • Alemba recommends that you use the Personal Access Token over OAuth (PAT). However, should you decide to use OAuth, the callback URL needs to be that of the ASM callback URL (which should have been added to the app registration in Azure). Eg. https://{server-name}/{system-name}/oauth2callback.htm

• Add the following WebHooks (at a minimum) for your selected work item type (bug, task, etc...), see also About Service Hooks, and enable:

  • Work Item Create

  • Work Item Update

Configuring Web Hooks for ASM

To create calls in ASM from work items in Azure DevOps, you will create Service Hooks.

1. Navigate to the Project Settings in Azure DevOps, and select Service Hooks from the menu on the left.

2. Press the Add button in the toolbar. The New Service Hook Subscription window appears.

3. Select Web Hooks from the menu on the left, and then press the Next button.

4. Select a value for the field Trigger on this type of event. These values are supported for ASM:

   • Work item commented on

   • Work item created

   • Work item deleted

   • Work item restored

   • Work item updated

5. Complete the trigger configuration by selecting filters as needed (Area Patch and Work Item Type), and then press the Next button.

   1. In the URL field, enter the URL for ASM in this format:

      https://Server_Name/System_Name/alemba.api/api/v1/webhook/azuredevops?$ClientId=########-####-####-####-############ (where Server_Name is the ASM server name, and System_Name is the ASM system name).

   2. e.g. 1 https://AlembaServer/Production/alemba.api/api/v1/webhook/azuredevops?$ClientId=?$ClientId=3566bf8b-08bc-5655-9f61-f21d2bfb1e90

   3. e.g.2 https://AlembaServer/Production/alemba.api/api/v2/webhook/azuredevops?$ClientId=?$ClientId=3566bf8b-08bc-5655-9f61-f21d2bfb1e90

   4. The Basic authentication username field requires the Login ID of an analyst record in ASM that has an IPK Management Security Role with permissions to create and update calls.

   5. Enter the corresponding password for that analyst record in the Basic authentication password field, and then select Finish.

For more information, visit the official Microsoft page Create a service hook with WebHooks.

For more information about how service hooks work, click here.

Configure ASM for Azure DevOps

Process Summary

Connect to the Source

1. In the Explorer pane, under Integration, select Sources to view the window.

2. Select the New button on the toolbar. In the pop up window, select Azure DevOps Connector from the drop-down list.

3. In the Integration Source Details window, complete the details. Refer to Connection parameters below for more information.

   1. Name of the Connection

   2. Status of the Connection

   3. Connection Parameters

      1. Endpoint is https://dev.azure.com/{your DevOps organization}/

      2. Access Token is the Personal Access you created in Azure DevOps+

      3. OAuth Token ID - An OAuth Token ID is a secure access token issued by an OAuth 2.0 authentication system that allows applications to access resources without exposing user credentials.

         1. It’s commonly used for API authentication in cloud services like Google, Azure, AWS, and APIs requiring secure access.

            🔹 Think of it like a temporary key that grants permission to an app or service to access specific data or perform actions on behalf of a user.

         2. Setting Up an OAuth Token for Microsoft Azure (Graph API, Office 365, etc.)

            Go to: Azure Portal

            1. Navigate to Azure Active Directory → App Registrations.

            2. Click New Registration → Configure app settings.

            3. Go to Certificates & Secrets → Generate a Client Secret.

            4. Use the Client ID, Tenant ID, and Client Secret to request an OAuth token.

            Microsoft OAuth token request command (via cURL):

            shCopyEditcurl -X POST https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token \
              -d "client_id=YOUR_CLIENT_ID" \
              -d "client_secret=YOUR_CLIENT_SECRET" \
              -d "scope=https://graph.microsoft.com/.default" \
              -d "grant_type=client_credentials"

      4. API Version (The version of the API for your ASM system that matches the supported version of Azure, typically 5.0)

   4. Fault Detection and Tolerance

      1. Max No of Transaction Attempts - Maximum number of time ASM will try the connection

      2. Time Between Transaction Attempts - Interval distribution of attempts. e.g., 30 minutes

      3. Asynchronous Transaction Timeout - How long before transaction timeout, e.g., 30 minutes

      4. Send Fault Notifications - Email notifications recipients

         1. Always

         2. After {X} Failed Attempts

         3. Add Recipients

            1. To add a recipient for notification, click Add Recipient.

            2. In the pop-up window, select the required recipient(s):

               1. People - Select to send emails to specific people. You can refine your selection to users, analysts or external contacts by selecting/deselecting the options. Then type a name into the Name field and then click Find. Choose from the results browse table and select Add. Repeat to add as many people as required. (You can use ctrl/click to select several entries from the same search results if you wish.)

               2. Group-Select to send emails to a Workflow Group (including all members of the group). Search using the Name field and click Find. From the browse table, select each group you want to receive the email and click Add.

               3. Other-Select to send emails to a recipient specified in the chosen field when the task becomes active. A list of fields appears, including fields added through ASM Designer. After selecting the fields, click Add.

                  e.g., To send a message to the Request Manager select Request No/Request Manager or to select the user linked to the request, select Request No/User.

4. Select the Test Connection icon on the toolbar to test the connection.

5. Save the details.

Enable Service Desk Actions

1. Select ≡ > Admin > Integration.

2. In the Explorer pane, under Integration, select Integration Platform Settings to view the window.

3. Under section heading Service Desk Actions, select the Enabled checkbox, then save the changes.

1. In the Explorer pane, under Integration, select Connectors.

2. On the Integration Connectors window, locate the Azure DevOps Connector, and ensure that the Service Desk and Visible checkboxes are selected.

Configure 'Service Desk Actions' for DevOps

In ASM, you will enable and configure "Service Desk Actions" for your bi-directional connection to Devops. This includes 5 tabs: Action, Criteria, Fields - Outgoing, Outgoing - Response, Fields - Incoming, and Attachment - Criteria.

1. In the Explorer pane, under Integration, select Service Desk Actions to view the window.

2. In the Filter by Source field, select the Integration Source you created for the connector.

3. All Azure DevOps projects and work item types are listed in the browse table. Select the one you want to work with and then select the action button.

1. The Service Desk Action Type window appears.

2. Select the New button to add a new mapping. The Mapping window appears.

Configuring Service Desk Actions - ACTION Tab

The Action tab allows System Administrators to set the “Action Type” to either Create or Update from the dropdown. Selecting one or the other will cause the display to be different in the Incoming tab.

The checkbox “Only process if Visible in Portal” is only active if Action Type is Update

***You have to set up separate mappings for Creation and for Update.

1. Name: Type a name for the mapping. This name appears in the Mappings table.

2. Screen Set: Select a call screen set from the multi-tiered list. The screen set determines:

   • the fields that will be available for this mapping

   • the calls that create and update work items in DevOps.

3. Action Type: Select the type of action this mapping performs:

   • Create work items in DevOps, and calls in ASM

   • Update work items in DevOps, and calls in ASM To create and update the same work item type and project in DevOps, you must create a mapping for Create and another for Update.

   • The same applies to creating and updating calls in ASM from DevOps.

4. Unique Ref: Not Applicable for the Azure DevOps Connector

5. Last Modified: Not Applicable for the Azure DevOps Connector

6. Send Notify for system generated history messages: Select this option to update the work item in DevOps whenever a system-generated entry (such as an agreement escalation) is added to the history of the call that resulted in the creation of the work item from this service desk action.

   • Unselect this option to update the work item in DevOps only when an Analyst or User action is added to the call history.

7. Only process if Visible in Portal: Select this option to update the work item in DevOps only when the Analyst or User action that was added to the history of the call is marked as "visible in the Self Service Portal".

   • Unselect this option to update the work item in DevOps whenever an Analyst or User action is added to the history of the call.

Configuring Service Desk Actions - CRITERIA Tab

Default Mapping - Select to specify that this is the default mapping for all calls with the screen set defined in the Actions tab.

Clear Default Mapping to set the conditions for applying this mapping. These conditions are set through defining a rule. You can only select internal fields or attributes as the criteria in your rule, since this is the criteria ASM uses to select items to create or update in DevOps.

**TIP: You may wish to only create work items in DevOps from calls assigned to a specific IPK Group in ASM. In this case, you would select the criteria, “Assigned Group”, the operator, equal to (=), and the value as the name of the IPK Group.

Configuring Service Desk Actions - FIELDS OUTGOING Tab

Ensure there is a field on the Work Item in MS Azure DevOps that can store the ASM Call ID.

1. Select the Fields - Outgoing tab to map fields to be updated in the DevOps work item created from the call that activated this mapping.

2. Map each field you wish to send to Azure DevOps.

3. Select the Outgoing-Response Tab

Configuring Service Desk Actions - OUTGOING RESPONSE Tab

Select the Outgoing - Response tab to map fields to be updated in the call when it creates the work item in DevOps. This tab can be ignored if this service desk action performs an Update.

Note: The DevOps field Work Item ID must be mapped (in the Action column) if this service desk action performs a Create in Azure DevOps.

Configuring Service Desk Actions - FIELDS INCOMING Tab

Select the Fields - Incoming tab to map fields to be updated in the call created from the DevOps work item that activated this mapping:

Service Hooks for ASM must be configured in the Azure DevOps project before mapping incoming fields. See Configuring Service Hooks for ASM.

1. *Default Incoming Field Mapping - Select to flag this as the default field mapping for calls created or updated in ASM from this DevOps project and work item type. This mapping will apply to an incoming service desk action if no other mapping for the project and work item type can be applied.

   • You must define a default incoming mapping

2. Using Template - Select the Call Template that ASM Core will use when creating the call, and determines the fields available for mapping.

3. Reference Field - Select the DevOps field to update with the number of the call created in ASM from this mapping. If the field is not blank in DevOps, the connector attempts to find the matching call in ASM, and creates the call if no match is found.

4. This field is required for mappings that create and update.

5. Fields Mapping browse Table - Map fields to be updated in ASM when a call is created or updated from a work item in DevOps using this service desk action mapping.

Configuring Service Desk Actions - ATTACHMENT CRITERIA Tab

**This mapping is required. The “Attachment – Criteria” tab prevents infinite update loops whereby ASM might update an Azure DevOps Work Item as a result of an update by Azure DevOps made to ASM and so on.

Configuration Example:

NOT Call: Last Updated By = “ADO Connector Test"

where "ADO Connector Test" is the Account used to connect to ASM.

This assumes that your organization will use a Person/System Account to log into ASM's API, and that that Account will not be used to log into any of ASM UIs (Core, Nano, Portal, Mobile).