BoldDesk allows you to manage Azure DevOps work item links through the Azure DevOps integration APIs. After the Azure DevOps integration is configured in BoldDesk, you can use the APIs to link an Azure DevOps work item to a BoldDesk ticket, retrieve linked work item details, and remove the link when it is no longer required.

This article explains the recommended API flow for linking, verifying, and unlinking Azure DevOps work items in BoldDesk.

Prerequisites

Before using the APIs, ensure that:

• Azure DevOps integration is configured in BoldDesk. Learn Installing and Configuring Azure DevOps in BoldDesk.
• The Azure DevOps work item has already been created or identified. Explore further information on How to Create and Link an Azure DevOps Work Item from a BoldDesk Ticket.
• You have the required BoldDesk ticket ID and Azure DevOps work item details needed for the API action.
• You have generated a valid BoldDesk API key, and the API key has the required permission to access Azure DevOps integration endpoints.

Create or Identify the Azure DevOps Work Item

Before managing the link in BoldDesk, create a new Azure DevOps work item or identify an existing Azure DevOps work item that needs to be associated with the BoldDesk ticket.

The work item must exist in Azure DevOps before it can be linked to a BoldDesk ticket.

Managing Azure DevOps Work Item Links Through APIs

After the Azure DevOps integration is configured, you can use BoldDesk APIs to manage the relationship between BoldDesk tickets and Azure DevOps work items.

The following flow explains how to identify or create the Azure DevOps work item, link it to a BoldDesk ticket, retrieve linked work item details, get the required itemMapperId, and unlink the work item from the ticket.

Link the Azure DevOps Work Item to the BoldDesk Ticket

Use the Link Azure DevOps Work Item API to link an Azure DevOps work item to a BoldDesk ticket.

POST https://{domain}/api/v1/integrations/devops/workitem/link?integrationId={integration_id}

Replace the placeholders as follows:

• {domain}: Your BoldDesk domain.
• {integration_id}: The Azure DevOps integration ID required by the API.

Send the following JSON payload in the request body:

{
  "boldDeskTicketId": 0,
  "workItemId": 0,
  "organizationId": "organization-id",
  "organizationName": "organization-name",
  "projectId": "project-id",
  "projectName": "project-name"
}

The endpoint URL and request body must be sent together as a single POST request. The endpoint identifies the API operation and integration record, while the request body provides the BoldDesk ticket and Azure DevOps work item details to be linked.

The following fields are used in the request body:

• boldDeskTicketId: The ID of the BoldDesk ticket to which the Azure DevOps work item should be linked.
• workItemId: The ID of the Azure DevOps work item that should be linked to the BoldDesk ticket.
• organizationId: The Azure DevOps organization ID.
• organizationName: The Azure DevOps organization name.
• projectId: The Azure DevOps project ID.
• projectName: The Azure DevOps project name.

Example

The following example shows the endpoint, query parameter, headers, and request body being sent together as one POST request:

curl -X POST "https://example.bolddesk.com/api/v1/integrations/devops/workitem/link?integrationId={integration_id}" \
  -H "accept: text/plain" \
  -H "x-api-key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "boldDeskTicketId": 0,
    "workItemId": 0,
    "organizationId": "organization-id",
    "organizationName": "organization-name",
    "projectId": "project-id",
    "projectName": "project-name"
  }'

After the work item is linked successfully, you can verify the linked work item using the Get Linked Items API.

Verify the Linked Azure DevOps Work Item

Use the Get Linked Items API to retrieve the Azure DevOps work items linked to a specific BoldDesk ticket.

GET https://{domain}/api/v1/integrations/devops/linked_workitem/{ticket_id}

Replace the placeholders as follows:

• {domain}: Your BoldDesk domain.
• {ticket_id}: The ID of the BoldDesk ticket.

Example

GET https://example.bolddesk.com/api/v1/integrations/devops/linked_workitem/12345

This API returns the Azure DevOps work items linked to the specified BoldDesk ticket.

Retrieve the Mapping ID

If a linked Azure DevOps work item must be removed from the BoldDesk ticket, first retrieve the mapping ID from the Get Linked Items API response.

GET https://{domain}/api/v1/integrations/devops/linked_workitem/{ticket_id}

In the API response, use the top-level id value from the required item in the result array. This value represents the mapping between the BoldDesk ticket and the linked Azure DevOps work item.

For example, in the following response, the mapping ID is 92:

{
  "result": [
    {
      "id": 92,
      "ticketId": 2351,
      "appName": "Azure DevOps",
      "linkedItems": {
        "id": 12,
        "projectName": "Feature Request"
      }
    }
  ]
}

In this response:

• The top-level id value, 92, identifies the link between the BoldDesk ticket and the Azure DevOps work item.
• The linkedItems.id value, 12, identifies the Azure DevOps work item.

You must pass the top-level id value as the itemMapperId query parameter when calling the unlink API.

Remove the Azure DevOps Work Item Link from the Ticket

Use the Unlink Work Item API to remove the link between the BoldDesk ticket and the Azure DevOps work item.

DELETE https://{domain}/api/v1/integrations/devops/workitem/unlink?itemMapperId={mapping_id}

Replace {mapping_id} with the top-level id value retrieved from the Get Linked Items API response.

Example

DELETE https://example.bolddesk.com/api/v1/integrations/devops/workitem/unlink?itemMapperId=92

After the request is completed successfully, the Azure DevOps work item will no longer be linked to the BoldDesk ticket.

Verify That the Azure DevOps Work Item Was Unlinked

After calling the Unlink Work Item API successfully, verify the result from the API response, the Azure DevOps app panel, and the ticket History tab.

Before unlinking, the Azure DevOps panel in the ticket displays the linked work item details.

When the unlink request is successful, the API returns a 200 response with a success message.

After the work item is unlinked, refresh or reopen the ticket. The Azure DevOps panel should display No work item here, confirming that the work item is no longer linked to the ticket.

You can also verify the unlink action from the History tab of the ticket.

Frequently Asked Questions

1. How can I verify whether an Azure DevOps work item is linked to a BoldDesk ticket?
   You can verify the linked Azure DevOps work item by using the Get Linked Items API for the specific BoldDesk ticket.

   GET https://{domain}/api/v1/integrations/devops/linked_workitem/{ticket_id}
   

   Replace {domain} with your BoldDesk domain and {ticket_id} with the ID of the BoldDesk ticket.

   For example:

   GET https://example.bolddesk.com/api/v1/integrations/devops/linked_workitem/12345
   

   This API returns the Azure DevOps work items linked to the specified BoldDesk ticket. If the ticket has one or more linked work items, review the response to confirm the work item details.

2. What value should be used as the itemMapperId when unlinking an Azure DevOps work item?
   The Get Linked Items API response may not include a field named itemMapperId. In that case, use the top-level id value from the required object in the result array.

   For example, in the following response, the value to use as itemMapperId is 92:

   {
     "result": [
       {
         "id": 92,
         "ticketId": 2351,
         "appName": "Azure DevOps",
         "linkedItems": {
           "id": 12,
           "projectName": "Feature Request"
         }
       }
     ]
   }
   

   In this example:

   • The top-level id value, 92, identifies the link between the BoldDesk ticket and the Azure DevOps work item.
   • The linkedItems.id value, 12, identifies the Azure DevOps work item.

   When unlinking the work item, pass the top-level id value as the itemMapperId query parameter.

   DELETE https://{domain}/api/v1/integrations/devops/workitem/unlink?itemMapperId=92
   

3. Can I use the Azure DevOps work item ID to unlink a work item from a BoldDesk ticket?
   No. You should not use the Azure DevOps work item ID as the itemMapperId when calling the unlink API.

   The Azure DevOps work item ID is available as linkedItems.id in the Get Linked Items API response. This value identifies the work item in Azure DevOps. However, the unlink API requires the mapping ID, which is the top-level id value from the object in the result array.

4. What happens when I unlink an Azure DevOps work item from a BoldDesk ticket?
   When you unlink an Azure DevOps work item from a BoldDesk ticket, BoldDesk removes only the association between the ticket and the work item. The Azure DevOps work item itself is not deleted from Azure DevOps.

   To remove the link, first retrieve the correct mapping ID using the Get Linked Items API:

   GET https://{domain}/api/v1/integrations/devops/linked_workitem/{ticket_id}
   

   In the response, identify the specific work item link you want to remove and copy the top-level id value from that object in the result array.

   Then call the Unlink Work Item API and pass that value as the itemMapperId query parameter:

   DELETE https://{domain}/api/v1/integrations/devops/workitem/unlink?itemMapperId={mapping_id}
   

   If multiple Azure DevOps work items are linked to the same BoldDesk ticket, verify the response carefully and use the top-level id that belongs to the specific work item link you want to remove. Using the wrong mapping ID may remove an unintended work item link from the ticket.

Related Articles

1. Installing and Configuring Azure DevOps in BoldDesk
2. How to Link Azure DevOps Work Items to BoldDesk Tickets
3. How to Create and Link an Azure DevOps Work Item from a BoldDesk Ticket
4. BoldDesk REST API Overview for Developers
5. BoldDesk API Authentication Guide: Secure Access Made Simple