HelloID-Conn-Prov-Target-Topdesk-Operators

Important

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.

Table of contents

• HelloID-Conn-Prov-Target-Topdesk-Operators
  • Table of contents
  • Introduction
  • Getting started
    • Provisioning PowerShell V2 connector
      • Correlation configuration
      • Field mapping
    • Connection settings
    • Prerequisites
    • Remarks
  • Setup the connector
    • Remove attributes when updating a Topdesk operator instead of corelating
    • Disable department or budgetholder
    • Managing tasks permissions
  • Getting help
  • HelloID docs

Introduction

HelloID-Conn-Prov-Target-Topdesk-Operator is a target connector. Topdesk provides a set of REST APIs that allow you to programmatically interact with its data. The Topdesk API documentation provides details of API commands that are used.

Endpoint	Description
/tas/api/operators	GET / POST / PATCH actions to read and write the operators
/tas/api/branches	GET braches to use in PUT / PATCH to operators
/tas/api/departments	GET departments to use in PUT / PATCH to operators
/tas/api/budgetholders	GET budgetholders to use in PUT / PATCH to operators
/tas/api/archiving-reasons	GET archiving-reasons to archive operators

The following lifecycle actions are available:

Action	Description
create.ps1	PowerShell create or correlate lifecycle action
delete.ps1	PowerShell delete lifecycle action (empty configured values and archive)
disable.ps1	PowerShell disable lifecycle action
enable.ps1	PowerShell enable lifecycle action
update.ps1	PowerShell update lifecycle action
grant.operatorGroup.ps1	PowerShell grant operator group lifecycle action
revoke.operatorGroup.ps1	PowerShell revoke operator group lifecycle action
permissions.operatorGroups.ps1	PowerShell permissions get operator groups lifecycle action
grant.categoryFilter.ps1	PowerShell grant category filters lifecycle action
revoke.categoryFilter.ps1	PowerShell revoke category filters lifecycle action
permissions.categoryFilter.ps1	PowerShell permissions get category filters lifecycle action
grant.operatorFilter.ps1	PowerShell grant operator filters lifecycle action
revoke.operatorFilter.ps1	PowerShell revoke operator filters lifecycle action
permissions.operatorFilter.ps1	PowerShell permissions get operator filters lifecycle action
grant.task.ps1	PowerShell grant task lifecycle action. Set concurrent actions to 1 to prevent timing issues
revoke.task.ps1	PowerShell revoke task lifecycle action. Set concurrent actions to 1 to prevent timing issues
permissions.task.ps1	PowerShell permissions with static list of tasks
configuration.json	Default configuration.json
fieldMapping.json	Default fieldMapping.json

Getting started

Provisioning PowerShell V2 connector

Correlation configuration

The correlation configuration is used to specify which properties will be used to match an existing account within HelloID-Conn-Prov-Target-Topdesk-Operators to a person in HelloID.

To properly setup the correlation:

1. Open the Correlation tab.

2. Specify the following configuration:

   Setting	Value
   Enable correlation	True
   Person correlation field	PersonContext.Person.ExternalId
   Account correlation field	employeeNumber

Tip

For more information on correlation, please refer to our correlation documentation pages.

Field mapping

The field mapping can be imported by using the fieldMapping.json file.

Tip

You can add extra fields by adding them to the account mapping. For all possible options please check the Topdesk API documentation

Connection settings

The following settings are required to connect to the API.

Setting	Description	Mandatory
BaseUrl	The URL to the API	Yes
UserName	The UserName to connect to the API	Yes
Password	The Password to connect to the API	Yes
Archiving reason	Fill in an archiving reason that is configured in Topdesk	Yes
When no item is found in Topdesk	Stop processing and generate an error or keep the current value and continue if budgetHolder or Department is not found	Yes
When no department in source data	Stop processing and generate an error or clear the department field in Topdesk	Yes
When no budgetholder in source data	Stop processing and generate an error or clear the budgetholder field in Topdesk	Yes
Toggle debug logging	Creates extra logging for debug purposes

Prerequisites

a archiving reason that is configured in Topdesk Credentials with the rights listed below.

Permission	Read	Write	Create	Delete	Archive
Supporting Files
Persons	X
Operators	X	X	X		X
Operator groups	X	X	X
Permission groups	X	X
Filters	X	X
Login data		X
API access
REST API	X
Use application passwords		X

Note

It is possible to set filters in Topdesk. If you don't get a result from Topdesk when expecting one it is probably because filters are used. For example, searching for a branch that can't be found by the API user but is visible in Topdesk.

Remarks

Setup the connector

Remove attributes when updating a Topdesk operator instead of corelating

In the update.ps1 script. There is an example of only set certain attributes when corelating a operator, but skipping them when updating them.

    if (-not($actionContext.AccountCorrelated -eq $true)) {
        # Example to only set certain attributes when create-correlate. If you don't want to update certain values, you need to remove them here.    
        # $account.PSObject.Properties.Remove('email')
        # $account.PSObject.Properties.Remove('networkLoginName')
        # $account.PSObject.Properties.Remove('loginName')
        # $account.PSObject.Properties.Remove('exchangeAccount')
    }

Disable department or budgetholder

The fields department and budgetholder are both non-required lookup fields in Topdesk. This means you first need to look up the field and then use the returned GUID (ID) to set the Topdesk operator.

For example:

"id": "90ee5493-027d-4cda-8b41-8325130040c3",
"name": "EnYoi Holding B.V.",
"externalLinks": []

If you don't need the mapping of the department field or the budgetholder field in Topdesk, you can remove department.lookupValue or budgetHolder.lookupValue from the field mapping. The create and update script will skip the lookup action.

Important

The branch lookup value branch.lookupValue is still mandatory.

Managing tasks permissions

Important

When managing tasks as permissions, we recommend you set concurrent actions to 1 to prevent timing issues. This is necessary because you can't update a task on an archived operator. When revoking the account access and the task permission at the same moment the operator could be left in the wrong state. This is not possible when concurrent actions are set to 1.

Getting help

Tip

For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages.

Tip

If you need help, feel free to ask questions on our forum.

HelloID docs

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