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-Ecare
- Table of contents
- Introduction
- Getting started
- Provisioning PowerShell V2 connector
- Connection settings
- Remarks
- Setup the connector
- HelloID docs
HelloID-Conn-Prov-Target-Ecare is a target connector. Ecare provides a set of REST API's that allow you to programmatically interact with its data. The HelloID connector uses the API endpoints listed in the table below.
| Endpoint | Description |
|---|---|
| /connect/token | Used for generating access token |
| /scim/v2/Users | Used for all SCIM operations |
The API specification can be found on: https://service-scim-o.ecare.nu/swagger
Note
Note that the endpoints listed in the specification may not be all implemented. The required endpoints for the connector however should be available.
The following lifecycle actions are available:
| Action | Description |
|---|---|
| create.ps1 | PowerShell create lifecycle action |
| delete.ps1 | PowerShell delete lifecycle action |
| disable.ps1 | PowerShell disable lifecycle action |
| enable.ps1 | PowerShell enable lifecycle action |
| update.ps1 | PowerShell update lifecycle action |
| permissions/grantPermission.ps1 | PowerShell grant lifecycle action. Grants a role to the user |
| permissions/revokePermission.ps1 | PowerShell revoke lifecycle action. Revokes a role from the user |
| permissions/permissions.ps1 | PowerShell permissions lifecycle action. list the available roles |
| configuration.json | Default configuration.json |
| fieldMapping.json | Default fieldMapping.json |
The field mapping can be imported by using the fieldMapping.json file. See the description of each field in this file (or in the HelloID Fields tab after import).
The correlation configuration is used to specify which properties will be used to match an existing account within Ecare to a person in HelloID.
To properly setup the correlation:
-
Make sure the Field mapping is configured first.
-
Open the
Correlationtab. -
Specify the following configuration:
Setting Value Enable correlation TruePerson correlation field ExternalId (field from Fields tab) Account correlation field employeeNumber (field from Fields tab)
Tip
For more information on correlation, please refer to our correlation documentation pages.
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 |
| TokenUrl | The URL to the identity provider that will generate the access token for the API connection | Yes |
| BaseUrl | The URL to SCIM service API root <https://> | Yes |
Note that an employee account is required before a user account can be created. If the employee doesn't exist, a 500 internal server error will be returned. The employee account is not managed by HelloID. Employee accounts are created by an external synchronization.
Make sure you set the number of concurrent actions (configuration tab) on 1. The external Api does at the moment not support simultaneous actions on the same user.
For some user properties as defined in the Field mapping, there is some additional mapping required and performed in the PowerShell scripts itself to create the actual the SCIM message.
At the moment, correlation is done by means of the externalId. The id that will be returned if an account is retrieved or created will be used as the account reference by HelloId.
The API returns limited error information when an error occurs, often resulting in an error 400 or 500 without additional information. For instance; creating an account with a username which already is used, will result in an error 500. A request lacking mandatory properties will result in an error 400.
Because error handling is limited within the API, the Resolve-EcareError function is still our basic / un-modified implementation.
The permission scripts are used to grant or revoke roles (i.e group memberships) to a user. Roles can only be revoked, when at least once a role has been granted by means of the API for the particular user.
Note
Roles that do not exist are ignored.
The list of possible roles (groups) is provided by the permissions.ps1 script, which currently contains a statically defined list within the script. Any roles not recognized by this list will be ignored by the API when attempting to grant or revoke roles.
During testing, we encountered situations where the email address and username provided during the account creation process were not accepted, resulting in a '500 Internal Server Error'. This suggests there may be hidden requirements or constraints that we are unaware of.
The fields: userName, WorkEmail, employeeNumber and ExternalId are required to be unique.
We have identified a potential issue where the employeeNumber and id can be the same, which might lead to conflicts. Specifically, a 'GET' to:scim\Users\{id} could result in returning a different account than intended. Situations like this are however unlikely to occur since the employeeNumber always is a unique number.
How to setup the connector in HelloID. Are special settings required. Like the primary manager settings for a source connector.
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/