Delta-N TOPdesk Change Management Integration

This extension will enable Azure Pipelines to create Change Requests in TOPdesks Change Management module. The extension consists of an Azure Pipelines task that can:

• Create a TOPdesk Change request
• Create a TOPdesk Change request and wait until the Change Request is either approved or rejected.
• Complete a Change request
• Cancel a Change request

The behaviour of the task is determined by providing an action as input parameter for the task.

About Delta-N / TOPdesk koppeling (connection)

Next to this extension, Delta-N offers a broader integration between Azure DevOps and TOPdesk. Many organizations that develop software use Azure DevOps to support this process. For registering and handling incidents and change requests, a different system is usually used, such as TOPdesk.

This leads to inefficiencies when tickets that require software modifications must be manually forwarded to the development department. This double work not only takes time but also increases the risk of errors. Additionally, necessary feedback to the user is often missing. Thanks to the TOPdesk - Azure DevOps integration, organizations can eliminate these inefficiencies and achieve significant efficiency gains.

The integration between Azure DevOps and TOPdesk works in both directions. TOPdesk notifications can be easily forwarded to Azure DevOps, where a work item is automatically created for the development team.

Conversely, tickets can be created in TOPdesk from Azure DevOps. With every change, automatic feedback is provided to the other system. This applies to both incidents and change requests. All information can be transferred, including attachments such as screenshots.

We have prepared two videos for demo purposes:

• Watch our webinar about the TOPdesk - Azure DevOps Integration ondemand.
• How the integration work

See our website for more information or contact us per e-mail.

Architecture of this extension

The current architecture of the Delta-N TOPdesk Change Management Integration is:

• The task runs in either your own infrastructure/agents or on the Microsoft-Hosted agents
• The agents need to have a line-of-sight connectivity to your TOPdesk SaaS instance
• The task uses a Service Connection that provide credentials to the TOPdesk instance. You provide the credentials to authenticate.
• The task using to the TOPdesk APIs to create, update and query the Change Requests
• No data is sent to third-parties

Points of attention

There are some points of attention:

• Preliminary Request for Change should be turned off in TOPdesk
• The task is provided as an agent task. That means that it will occupy an agent. If you want to wait for an approval in TOPdesk the task will occupy the agent.
• The task is created for use with multistage (yaml) pipelines. It can work with classic pipelines but we have not tested this.
• When the pipeline fails, the change will be cancelled by the task in TOPdesk. When the pipeline (or stage) starts again, a new change will be created by the task. You can make use of the retry options of stages and jobs, however, this does not affect the behaviour of the task.
• If you want to wait for an approval or rejection in TOPdesk, the task will wait aslong both 'reject' and 'approve' are actions on the Change Request.

In the feature we might deliver an Approval and Check task. However, implementing custom checks are not yet supported by Azure DevOps Services. It is on the roadmap of Azure DevOps.

Getting Started

This guide will help you configuring the TOPdesk integration

Configuring TOPdesk

Before you can use the task, some preperations needs to be done within TOPdesk

1 - Create an API user

Follow the instructions on the TOPdesk developer page to create an user that can use the API. The user needs to have Read and Write permissions to the REST API. You also needs to create an 'Application password'.

2 - Create an User, Operator and Operation Group

You need to create a new user and operator. This is the user that the task will use to create, update and close the change. The best thing is that you create a new 'Operator Group' first.

• Create a new Operator Group
• Create a new Operator. Add this operator to the Operator Group you created.
• Create an user. This user is used as the identity requesting the change. Link this user to the new Operator that you created. You can use the same name.

The Operator Group needs Task permissions:

• Change Coordinator
• Change Activities Operator
• Request for Change Operator
• Extensive Change Operator

3 - Create an Extensive Change Template

• Go to the 'Change management' settings
• Create a new template:
  • Set the change to 'Extensive'
  • Fill in all the mandatory fields that you need to be filled with a default value like type/category
  • Fill in the 'Operator Groups'

If you want to use automatically approve the Change Request, set the 'Authorisation' / 'Approved' checkbox. Don't forget to check the box 'Available in Request for Change' in the' Availability and Filters' tab.

4 - Create a 'Reason for Cancelation'

• Go to the 'Change Management' settings
• Go to 'Drop-down lists' / 'Change' and then 'Reason for Cancelation'
• Add reason 'Deployment failure'

Setting up the Service Connection in Azure DevOps

• Go to Azure DevOps and to the project where you want to create the service connection to TOPdesk.
• Create a new Service Connection and choose TOPdesk
• Fill in the fields:
  • The username and password fields corresponds to the API user that you created in step 1
  • Optional: The 'Change Requestor Identifier' corresponds to the User you created in Step 2 (so Firstname Lastname)
  • Optional: The 'Change Template Identifier' corresponds to the Template you created in Step 3

Please note. Also the task can use the inputs 'Change Requestor Identifier' and 'Change Template Identifier'. You can set those at both locations, however the task input prevails above the service connection settings.

Adding the tasks to the Pipeline

You can task DeltaNTOPdeskManageChangeRequest@1 to your pipeline. The task has a couple of input parameters:

The Service connection can also be configured when setting the 'Change Requestor Identifier' and 'Change Template Identifier'. You can set those at both locations, however the task input prevails above the service connection settings.

The task produces to output variables named TOPdeskChangeId and TOPdeskChangeNumber that can be used within the pipeline.

Creating a Change Request

You can create a change request by including the following task in the pipeline

Example:

steps:
  - task: DeltaNTOPdeskManageChangeRequest@1
    displayName: "Delta-N TOPdesk Management - Create Change Request"
    name: DeltaNTOPdeskManageChangeRequest
    inputs:
      action: "CreateChangeRequest"
      assetName: "Application1"
      serviceEndpoint: "TOPdesk"

Create and Wait For Approval

You can create a change request by including the following task in the pipeline if you want to wait for an approval.

Example:

steps:
  - task: DeltaNTOPdeskManageChangeRequest@1
    name: DeltaNTOPdeskManageChangeRequest
    displayName: "Delta-N TOPdesk Management - Create Change Request and wait for approval"
    inputs:
      action: "CreateChangeRequestAndWaitForApproval"
      assetName: "Application1"
      setChangeRequestStatusAfterCreation: "Pending approval"
      changeTemplateId: "CT-040"
      serviceEndpoint: "TOPdesk"

When the Change Request is approved, the pipeline will continue. When the Change Request is rejected the pipeline wil fail.

Complete Change Request

You can Complete the Change Request by setting the action to CompleteChangeRequest

Example:

steps:
  - task: DeltaNTOPdeskManageChangeRequest@1
    displayName: "Delta-N TOPdesk Management - Complete Change Request"
    inputs:
      action: "CompleteChangeRequest"
      serviceEndpoint: "TOPdesk"

Cancel Change Request

You can Cancel the Change Request by setting the action to CancelChangeRequest

Example:

steps:
  - task: DeltaNTOPdeskManageChangeRequest@1
    displayName: "Delta-N TOPdesk Management - Cancel Change Request"
    inputs:
      action: "CancelChangeRequest"
      serviceEndpoint: "TOPdesk"

Job Examples for Completing and Closing change

Example for a single job that does the deployment

In the example below we first create the Change Request. If the job succeeds we Complete the change. If the job is canceled or is failed we Cancel the change

steps:
  - task: DeltaNTOPdeskManageChangeRequest@1
    displayName: "Delta-N TOPdesk Management - Create Change Request"
    inputs:
      action: "CreateChangeRequest"
      assetName: "Application1"
      serviceEndpoint: "TOPdesk"

  # Deployment steps here

  - task: DeltaNTOPdeskManageChangeRequest@1
    displayName: "Delta-N TOPdesk Management - Complete Change Request"
    condition: succeeded()
    inputs:
      action: "CompleteChangeRequest"
      serviceEndpoint: "TOPdesk"

  - task: DeltaNTOPdeskManageChangeRequest@1
    displayName: "Delta-N TOPdesk Management - Cancel Change Request"
    condition: or(failed(), canceled())
    inputs:
      action: "CancelChangeRequest"
      serviceEndpoint: "TOPdesk"

Advanced example when a stage contains multiple jobs

In the example below there is a situation where multiple jobs are created. Note the following:

• The first job creates the Change Request
• We provide a Name of the taskinstance DeltaNTOPdeskManageChangeRequest. This is mandatory in this situation because we need the TOPdeskChangeId and TOPdeskChangeNumber variables
• The jobs CloseChange and CancelChange are always atleast dependent on the CreateChange job
• The jobs CloseChange and CancelChange uses conditions to control when and if they run
• The jobs CloseChange and CancelChange fetches variables TOPdeskChangeId and TOPdeskChangeNumber from the correct job. This is done with dependencies.

jobs:
  - job: CreateChange
    steps:
      - task: DeltaNTOPdeskManageChangeRequest@1
        name: DeltaNTOPdeskManageChangeRequest
        displayName: "Delta-N TOPdesk Management - Create Change Request"
        inputs:
          action: "CreateChangeRequest"
          assetName: "Application1"
          serviceEndpoint: "TOPdesk"

  - job: Deploy_WebApp
    dependsOn:
      - CreateChange
    steps:
    # Deployment steps here

  - job: CloseChange
    variables:
      TOPdeskChangeId: $[dependencies.CreateChange.outputs['DeltaNTOPdeskManageChangeRequest.TOPdeskChangeId']]
      TOPdeskChangeNumber: $[dependencies.CreateChange.outputs['DeltaNTOPdeskManageChangeRequest.TOPdeskChangeNumber']]
    condition: succeeded()
    dependsOn:
      - CreateChange
      - Deploy_WebApp
    steps:
      - task: DeltaNTOPdeskManageChangeRequest@1
        displayName: "Delta-N TOPdesk Management - Complete Change Request"
        inputs:
          action: "CompleteChangeRequest"
          serviceEndpoint: "TOPdesk"

  - job: CancelChange
    variables:
      TOPdeskChangeId: $[dependencies.CreateChange.outputs['DeltaNTOPdeskManageChangeRequest.TOPdeskChangeId']]
      TOPdeskChangeNumber: $[dependencies.CreateChange.outputs['DeltaNTOPdeskManageChangeRequest.TOPdeskChangeNumber']]
    condition: or(failed(), canceled())
    dependsOn:
      - CreateChange
      - Deploy_WebApp
    steps:
      - task: DeltaNTOPdeskManageChangeRequest@1
        displayName: "Delta-N TOPdesk Management - Cancel Change Request"
        inputs:
          action: "CancelChangeRequest"
          serviceEndpoint: "TOPdesk"

See Microsoft Learn for more information how to access output variables.

Support

Delta-N does not give any support to this free extension. If you have any questions or if you want to report a bug, you can use the Q&A section within the Azure DevOps Marketplace.

Consultancy

If you have problems configuring TOPdesk and/or Azure DevOps in relation to this extension, we can offer you paid consultancy. Please contact us through e-mail.

Feature requests

If you feature requests for this extension. Please contact us through e-mail.