TOPdesk provides a RESTful API that allows you to programmatically interact with its services and data. This article will first walk you through gaining API access to TOPdesk. Then, it will demonstrate how to create a PowerShell target connector to use TOPdesk as a target system in HelloID provisioning.
- 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.
- Select the Reporting API link to expand it.
- Select the Read permission for REST API, and the Write permission for Use application passwords.
- 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.
Customize the Connector's Lifecycle Stages
Once you have obtained API connection credentials, and you've installed the HelloID provisioning PowerShell connector, you are ready to begin customizing the lifecycle stages of the connector in HelloID.
The following scripts can be assigned to each of the lifecycle stages, and serve as basic examples of how to use TOPdesk as a provisioning target system.
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.
Extend these examples as you see fit.
- Correlation settings in the User Create Example script are found under the
#correlationcomment. By default, the script correlates persons based on a matching
- Mapping configuration in the User Create Example and User Update Example scripts are found under the
#mappingcomment. Use these settings to specify the mapping from fields in HelloID provisioning to the target system.
- If you're using AD as your IdP and you plan to enable SSO for TOPdesk, it is recommended to use the AD
sAMAccountNamefor the TOPdesk account username. To do so, first ensure AD has been added as a target system in HelloID Provisioning. Then, follow the tutorial How to use data from one target system in another target system to make the TOPdesk target system depend on the AD target system, to supply the
sAMAccountNameattribute. Assign it to both
tasLoginNamein the following scripts. For example:
networkLoginName = $p.Accounts.OnpremiseAD.SamAccountName;
- The TOPdesk API doesn't support deleting a user. Instead, the User Delete Example script removes the username and email from the user, so the same username and/or email can be reused with a different user in the future.