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.
HelloID-Conn-Prov-Target-Planon-Persons is a target connector. Planon-Persons provides a set of REST API's that allow you to programmatically interact with its data.
- Connection settings
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
|---|---|---|
| AuthToken | The AuthToken to connect to the API | Yes |
| BaseUrl | The URL to the API | Yes |
The correlation configuration is used to specify which properties will be used to match an existing account within Planon-Persons to a person in HelloID.
| Setting | Value |
|---|---|
| Enable correlation | True |
| Person correlation field | PersonContext.Person.ExternalId |
| Account correlation field | Code |
Tip
For more information on correlation, please refer to our correlation documentation pages.
The following lifecycle actions are available:
| Action | Description |
|---|---|
| create.ps1 | Creates a new account. |
| disable.ps1 | Disables an account, preventing access without permanent removal. |
| enable.ps1 | Enables an account, granting access. |
| update.ps1 | Updates the attributes of an account. |
| resources/departments/resources.ps1 | Manages resources, such as creating departments. |
| resources/functions/resources.ps1 | Manages resources, such as creating functions. |
| configuration.json | Contains the connection settings and general configuration for the connector. |
| fieldMapping.json | Defines mappings between person fields and target system person account fields. |
The field mapping can be imported by using the fieldMapping.json file.
All the requests to the api are a POST even the ones that only retrieve information.
The connector makes use of two resource scripts to create the necessary functions and departments in the target system before the user gets created.
In these resource scripts, there is a GET call used to retrieve the functions and departments, but it requires an empty object to be sent in the request body, which appears somewhat unusual in the code.
The department resource script requires a value with a dot to be selected in HelloId. For example Department.Displayname.
The function resource script requires two value's a displayname and a code. For example Title.
There are 3 properties (DepartmentRef, EmploymenttypeRef and DisplayTypeRef) that need to have a dollar sign in front of them when creating or updating a person. However this is not possible in the fieldmapping, therefore the create and update scripts replace these properties in the actioncontext.data or correlatedAccount respectively.
The property FreeString41 gets populated with the reference of the manager in the create and update scripts.
The get call to retrieve users is a POST request. The request uses a filter in the body to retrieve the user based on Code
The following endpoints are used by the connector
| Endpoint | Description |
|---|---|
| /read/HelloIDAPI | Retrieve person information |
| /execute/HelloIDAPI/BomAdd | Create person |
| /update/HelloIDAPI | Update person |
| /read/HelloIDAPIEenheden | Retrieve department information |
| /execute/HelloIDAPIEenheden/BomAdd | Create departments |
| /read/HelloIDAPIFuncties | Retrieve function information |
| /execute/HelloIDAPIFuncties/BomAdd | Create functions |
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.
The official HelloID documentation can be found at: https://docs.helloid.com/