{"id":19504385,"url":"https://github.com/tools4everbv/helloid-conn-prov-target-topdesk-operators","last_synced_at":"2025-10-12T20:12:00.010Z","repository":{"id":113211828,"uuid":"321653343","full_name":"Tools4everBV/HelloID-Conn-Prov-Target-Topdesk-Operators","owner":"Tools4everBV","description":"TOPdesk - Create and manage operators","archived":false,"fork":false,"pushed_at":"2025-09-12T13:56:50.000Z","size":154,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-12T16:13:31.373Z","etag":null,"topics":["css","itm","itsm","provisioning","target"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tools4everBV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-12-15T11:55:14.000Z","updated_at":"2025-09-03T07:13:55.000Z","dependencies_parsed_at":"2025-01-08T10:41:12.413Z","dependency_job_id":"36fb1291-23c0-46bb-a1b0-9438e3b600c1","html_url":"https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-Topdesk-Operators","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Tools4everBV/HelloID-Conn-Prov-Target-Topdesk-Operators","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Topdesk-Operators","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Topdesk-Operators/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Topdesk-Operators/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Topdesk-Operators/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tools4everBV","download_url":"https://codeload.github.com/Tools4everBV/HelloID-Conn-Prov-Target-Topdesk-Operators/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Target-Topdesk-Operators/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279012798,"owners_count":26085187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css","itm","itsm","provisioning","target"],"created_at":"2024-11-10T22:25:32.632Z","updated_at":"2025-10-12T20:12:00.005Z","avatar_url":"https://github.com/Tools4everBV.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# HelloID-Conn-Prov-Target-TOPdesk-Operators\n\n\u003e [!IMPORTANT]\n\u003e 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.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/Tools4everBV/HelloID-Conn-Prov-Target-Topdesk-Operators/blob/main/Logo.png?raw=true\"\u003e\n\u003c/p\u003e\n\n## Table of contents\n\n- [HelloID-Conn-Prov-Target-TOPdesk-Operators](#helloid-conn-prov-target-topdesk-operators)\n  - [Table of contents](#table-of-contents)\n  - [Introduction](#introduction)\n  - [Getting started](#getting-started)\n    - [Provisioning PowerShell V2 connector](#provisioning-powershell-v2-connector)\n      - [Correlation configuration](#correlation-configuration)\n      - [Field mapping](#field-mapping)\n    - [Connection settings](#connection-settings)\n    - [Prerequisites](#prerequisites)\n    - [Remarks](#remarks)\n  - [Setup the connector](#setup-the-connector)\n    - [Remove attributes when updating a TOPdesk operator instead of corelating](#remove-attributes-when-updating-a-topdesk-operator-instead-of-corelating)\n    - [Disable department or budgetholder](#disable-department-or-budgetholder)\n    - [Managing tasks permissions](#managing-tasks-permissions)\n  - [Getting help](#getting-help)\n  - [HelloID docs](#helloid-docs)\n\n## Introduction\n\nSupported features:\n| Feature                             | Supported | Actions                                                                     | Remarks |\n| ----------------------------------- | --------- | --------------------------------------------------------------------------- | ------- |\n| **Account Lifecycle**               | ✅         | Create, Update, Enable, Disable, Delete (disable with option to clear data) |         |\n| **Permissions**                     | ✅         | Operator groups, operator filters, category filters and tasks               |         |\n| **Resources**                       | ❌         | -                                                                           |         |\n| **Entitlement Import: Accounts**    | ✅         | -                                                                           |         |\n| **Entitlement Import: Permissions** | ❌         | -                                                                           |         |\n| **Governance Reconciliation Resolutions** | ✅        | Disable, Delete                                       | Delete is treated as a disable action with the option to update values. Please adjust the configuration accordingly in the delete script |\n\n_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](https://developers.topdesk.com/explorer/?page=supporting-files#/) provides details of API commands that are used.\n\n| Endpoint                   | Description                                                  |\n| -------------------------- | ------------------------------------------------------------ |\n| /tas/api/operators         | `GET / POST / PATCH` actions to read and write the operators |\n| /tas/api/branches          | `GET` braches to use in `PUT / PATCH` to operators           |\n| /tas/api/departments       | `GET` departments to use in `PUT / PATCH` to operators       |\n| /tas/api/budgetholders     | `GET` budgetholders to use in `PUT / PATCH` to operators     |\n| /tas/api/archiving-reasons | `GET` archiving-reasons to archive operators                 |\n\n## Getting started\n\n### Provisioning PowerShell V2 connector\n\n#### Correlation configuration\n\nThe 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_.\n\nTo properly setup the correlation:\n\n1. Open the `Correlation` tab.\n\n2. Specify the following configuration:\n\n    | Setting                   | Value                             |\n    | ------------------------- | --------------------------------- |\n    | Enable correlation        | `True`                            |\n    | Person correlation field  | `PersonContext.Person.ExternalId` |\n    | Account correlation field | `employeeNumber`                  |\n\n\u003e [!TIP]\n\u003e _For more information on correlation, please refer to our correlation [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems/correlation.html) pages_.\n\n#### Field mapping\n\nThe field mapping can be imported by using the [_fieldMapping.json_](./fieldMapping.json) file.\n\n\u003e [!TIP]\n\u003e You can add extra fields by adding them to the account mapping. For all possible options please check the [TOPdesk API documentation](https://developers.topdesk.com/explorer/?page=supporting-files#/)\n\n\u003e [!NOTE]\n\u003e Starting November 2025, it will be mandatory to link a TOPdesk person to a TOPdesk operator.  \n\u003e This is done by setting the `linkedPerson.id` field with the TOPdesk Person ID.  \n\u003e You can achieve this by making the TOPdesk Operator target dependent on the TOPdesk Person target, and assigning the Person’s TOPdesk account ID to the `linkedPerson.id` field.  \n\u003e By default, this mapping is included in the `fieldMapping.json` file.  \n\u003e For more information, please refer to the [official documentation](https://docs.topdesk.com/en/step-2--api-changes.html).\n\n### Connection settings\n\nThe following settings are required to connect to the API.\n\n| Setting                             | Description                                                                                                             | Mandatory |\n| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- |\n| BaseUrl                             | The URL to the API                                                                                                      | Yes       |\n| UserName                            | The UserName to connect to the API                                                                                      | Yes       |\n| Password                            | The Password to connect to the API                                                                                      | Yes       |\n| Archiving reason                    | Fill in an archiving reason that is configured in TOPdesk                                                               | Yes       |\n| 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       |\n| When no department in source data   | Stop processing and generate an error or clear the department field in TOPdesk                                          | Yes       |\n| When no budgetholder in source data | Stop processing and generate an error or clear the budgetholder field in TOPdesk                                        | Yes       |\n\n### Prerequisites\na archiving reason that is configured in TOPdesk\nCredentials with the rights listed below. \n\n| Permission                | Read  | Write | Create | Delete | Archive |\n| ------------------------- | ----- | ----- | ------ | ------ | ------- |\n| __Supporting Files__      |\n| Persons                   | __X__ |       |        |        |         |\n| Operators                 | __X__ | __X__ | __X__  |        | __X__   |\n| Operator groups           | __X__ | __X__ | __X__  |        |         |\n| Permission groups         | __X__ | __X__ |        |        |         |\n| Filters                   | __X__ | __X__ |        |        |         |\n| Login data                |       | __X__ |        |        |         |\n| __API access__            |\n| REST API                  | __X__ |       |        |        |         |\n| Use application passwords |       | __X__ |        |        |         |\n\n\u003e [!NOTE]\n\u003e 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.\n\n\n### Remarks\n\n## Setup the connector\n\n### Remove attributes when updating a TOPdesk operator instead of corelating\nIn the `update.ps1` script. There is an example of only set certain attributes when corelating a operator, but skipping them when updating them.\n\n```powershell\n    if (-not($actionContext.AccountCorrelated -eq $true)) {\n        # Example to only set certain attributes when create-correlate. If you don't want to update certain values, you need to remove them here.    \n        # $account.PSObject.Properties.Remove('email')\n        # $account.PSObject.Properties.Remove('networkLoginName')\n        # $account.PSObject.Properties.Remove('loginName')\n        # $account.PSObject.Properties.Remove('exchangeAccount')\n    }\n```\n\n### Disable department or budgetholder\n\nThe 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. \n\nFor example:\n\n\n```JSON\n\"id\": \"90ee5493-027d-4cda-8b41-8325130040c3\",\n\"name\": \"EnYoi Holding B.V.\",\n\"externalLinks\": []\n```\n\nIf 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. \n\n\u003e [!IMPORTANT]\n\u003e The branch lookup value `branch.lookupValue` is still mandatory.\n\n### Managing tasks permissions\n\u003e [!IMPORTANT]\n\u003e 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.\n\n## Getting help\n\n\u003e [!TIP]\n\u003e _For more information on how to configure a HelloID PowerShell connector, please refer to our [documentation](https://docs.helloid.com/en/provisioning/target-systems/powershell-v2-target-systems.html) pages_.\n\n\u003e [!TIP]\n\u003e  _If you need help, feel free to ask questions on our [forum](https://forum.helloid.com/forum/helloid-connectors/provisioning/1266-helloid-conn-prov-target-topdesk)._\n\n## HelloID docs\n\nThe official HelloID documentation can be found at: https://docs.helloid.com/\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-target-topdesk-operators","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-target-topdesk-operators","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-target-topdesk-operators/lists"}