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-UbeeoATS
HelloID-Conn-Prov-Target-UbeeoATS is a target connector. UbeeoATS provides a set of REST API's that allow you to programmatically interact with its data.
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
|---|---|---|
| ClientId | The ClientId to connect to the API | Yes |
| ClientSecret | The ClientSecret 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 UbeeoATS to a person in HelloID.
| Setting | Value |
|---|---|
| Enable correlation | No |
| Person correlation field | PersonContext.Person.ExternalId |
| Account correlation field | EmployeeID |
Tip
Correlation is handled by Ubeeo. When you send an account to be created with an existing EmployeeID, the existing account will be updated. Correlation - Update
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) Enabled account. |
| delete.ps1 | Removes an existing account or entity. |
| update.ps1 | Updates the attributes of an account. |
| importEntitlements.ps1 | Not applicable - No Get Calls! |
| 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.
The EmployeeID is used to correlate existing users. If the EmployeeID is found, the current account will be updated. If the EmployeeID is not found, a new account will be created.
When the customer wishes to use the user provisioning module, the customer must choose a 'UserName' strategy. Depending on the chosen strategy, some properties in the User JSON will become mandatory.
Please check the API documentation for additional information
The connector is designed to use only the primary contract for orgUnits. Although the API supports a list of orgUnits, we currently add only the primary one. If you want to use a list of units, it is possible, but it requires changes to the connector.
The EmailAddress property is unique in Ubeeo. When an account is disabled, the email address remains in the application. Therefore, if a new person joins the company with the same email address, it cannot be added to the new account in Ubeeo.
For the Ubeeo ATS connector, set the concurrent sessions setting to 1. The authentication token that HelloID requests is only valid within the current session. If a new token is requested in a parallel process, any existing token becomes invalid. This can lead to authentication errors or failed actions. Setting the session concurrency to 1 ensures that only one action is executed at a time, preventing token invalidation and avoiding errors.
The API does not support a GET request to retrieve account details.
There is no comparison in the update script, so a HelloID update trigger always updates the Ubeeo account.
There is no enable/disable call because the disabled state can be overridden by an update action. So, when an update is performed on a disabled account, the account will be automatically enabled. Therefore, the 'disable' call is performed in the delete script.
There is no import entitlements script because there is no API available to retrieve users.
Please note that Ubeeo will also need to whitelist the IP addresses of the server(s) that will consume the API. Without whitelisting the addresses, the consuming IP address will be blacklisted when calling an endpoint too many times.
The API returns an HTML error page when a 401 or 415 error occurs. The connector handles 401 errors and returns a custom error message when they occur. A 415 error only happens if the Content-Type is incorrect, which is hardcoded, so this error should not occur.
The error message Required request body is missing is not very clear. For example, if orgUnits is sent as a string instead of an array, or if the body contains incorrectly formatted JSON, the error is returned.
The following endpoints are used by the connector
| Endpoint | Description |
|---|---|
| /api/oauth/token | Retrieve Authorization Token |
| /api/users | Retrieve user information |
| /api/users/:id | Disables an user |
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/