HelloID-Conn-Prov-Target-Topdesk

ℹ️ Information
This repository contains the connector and configuration code only. The implementer is responsible to acquire the connection details such as username, password, certificate, etc. You might even need to sign a contract or agreement with the supplier before implementing this connector. Please contact the client's application manager to coordinate the connector requirements.

Introduction
Connector Icon
Getting Started
- Permissions
- API Access
Usage

Introduction

TOPdesk provides a RESTful API that allows you to programmatically interact with its services and data.

Connector Icon

https://avatars1.githubusercontent.com/u/14311896?s=200&v=4

Getting Started

By using this connector you will have the ability to create one of the following items in TOPdesk:

Simple changes
Extensive changes
Incidents
Accounts

In this project we are connecting to the TOPdesk API using the Powershell Invoke-RestMethod cmdlet. Before we can start using this, we have to setup and configure our API access first.

Permissions

The following permissions are required to use this connector. This should be configured on a specific Permission Group for the Operator HelloID uses.

Permission	Read	Write	Create	Archive
Call Management
First line calls	x	x	x
Second line calls	x	x	x
Escalate calls		x
Link object to call		x
Link room to call		x
Change Management
Requests for Simple Change	x	x	x
Requests for Extensive Change	x	x	x
Simple Changes	x	x
Extensive Changes	x	x
New Asset Management
Templates	x
Supporting Files
Persons	x	x	x	x
Operators	x	x	x	x
Operator groups	x
Suppliers	x
Rooms	x
Login data		x
Reporting API
REST API	x
Use application passwords		x

(To create departments and budgetholders, you will need to allow the API account read and write access to the "Instellingen voor Ondersteunende bestanden".)

API Access

Getting Connected to the API

Go to your TOPdesk portal (e.g., https://customer.topdesk.net/), and log into an operator account.
Go to Modules > Supporting Files > Overview > Permission groups.
Select the New Permission Group button.
Enter a Name for the permission group.
Configure te correct permissions as described in the table above.
Select the Save button.
Select the Operators tab.
Select the Links Wizard button.
Select the operator whose credentials you wish to use to access the TOPdesk API.
Select the Link button.
Select the user account icon in the top-right corner of the screen, and in the drop down, select My Settings.
Under the Application passwords section, select the Add button.
Enter an Application name.
Select the Create button.
Copy the Application password.

To work with the API TOPdesk expects an application password, not the password used to login to the web interface. More information about this specific password can be found on the following Documentation page.

For more information about the TOPdesk API see the following TOPdesk Documentation page.

Usage

When running into 403 issues when creating changes, make sure the configured change template is available for use in change requests. This option can be enabled from the second tab of the change template configuration page.

Update the scripts with your own values, under the #TOPdesk system data comment:

url: Replace 'xxxx' with your organization's TOPdesk subdomain.
apiKey: The application password you copied.
userName: The TOPdesk operator username that you linked to the new permission group you created.

(Optional) when using the connector to handle Incidents or Changes you have to configure the path to where your exampleChanges.json or exampleIncidents.json are being stored

path = C:\Temp\Powershell\TOPDesk\exampleChanges.json

For more information about our HelloID PowerShell connectors, please refer to our general Documentation page

It is now possible to use the manager or the employee as a requester of a change, by using the words 'employee' or the word 'manager' as a value in the 'Requester' parameter. Please make sure the person is enabled(not archived) when setting the employee as the requester when creating a change. Usually you need to disable any action in the disable task, and archive the user in the delete task. An example for a dummy disable task is displayed below:

#Initialize default properties
$success = $False;
$p = $person | ConvertFrom-Json
$aRef = $accountReference | ConvertFrom-Json
$auditMessage = " not disabled succesfully";

if(-Not($dryRun -eq $True)){  
    $success = $True
    $auditMessage = "disabled successfully";
}

#build up result
$result = [PSCustomObject]@{ 
	Success = $success;
	AuditDetails = $auditMessage;
};

Write-Output $result | ConvertTo-Json -Depth 10;

HelloID Docs

The official HelloID documentation can be found at: https://docs.helloid.com/

niekdemelker / helloid-conn-prov-target-topdesk Goto Github PK