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-NewBlack is a target connector. NewBlack 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 |
|---|---|---|
| ApiKey | The ApiKey to connect to the API | Yes |
| BaseUrl | The URL to the API | Yes |
| OrganizationUnitIdMapping | The mapping file between HelloID department and New Black OrganizationUnitId | Yes |
| CSVDelimiter | The Delimiter for the mapping file | Yes |
The correlation configuration is used to specify which properties will be used to match an existing account within NewBlack to a person in HelloID.
| Setting | Value |
|---|---|
| Enable correlation | True |
| Person correlation field | ExternalId |
| Account correlation field | EmployeeNumber |
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. |
| delete.ps1 | n/a |
| disable.ps1 | n/a *Account access will be managed with a login group |
| enable.ps1 | n/a *Account access will be managed with a login group |
| update.ps1 | Updates the attributes of an account. |
| permissions/roles/subPermissions.ps1 | Grants and revoke permissions to an account to the associated organizationUnits. (Based on ExternalMapping CSV file.) |
| permissions/groups/permissions.ps1 | Retrieves all available permissions (Roles). |
| 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.
Important
Granting and revoking Roles is done by editing roles after receiving the currently assigned roles. For this reason, the concurrent actions need to be set to 1.
- Enable/Disable is managed through a separate group that must be created specifically for each system. In New-Black, there is no standalone account property for enabling or disabling. However, there is a permission that handles this. This permission can be assigned to a group, which HelloID can then use as a login permission.
- This group can be named for example 'Login' and managed like any other group.
- There are two separate account objects in New Black, one for the user and one for the employee.
- The relation between those object is always one-on-one.
- Currently the EmployeeNumber and the function are fields of the Employee Object, the rest are fields of the user object.
- The property
EmployeeNumberandBackendRelationIDare NOT unique. - The
NickNameand theEmailAddressare unique in New Black. TheNickNameis not used by this connector. - The
CreateEmployeeUserendpoint, which is used to create accounts, can also update an existing account based on the NickName or EmailAddress. If the EmailAddress already exists, it will not create a new account but will instead update the existing account associated with the corresponding email address. The connector is designed to prevent this unintended behavior.
-
Currently, there is no logic added to the connector to support reboarding, such as renaming or clearing the email address during the delete action. This is mostly because the way accounts are deleted or disabled is often customer-specific. However, reboarding can be an issue in the New Black Connector, as the API does not support deleting accounts, and the email address must be unique within NewBlack.
-
The connector currently checks if the email already exists and throws an error if it does. This must be discussed with the customer to determine how to handle it. For example, it is also possible to reuse a previously created account. To make this possible, you can remove the email uniqueness check, and the connector will handle the rest. In this case, the create action will update the existing account with the matching email instead of creating a new one.
- This results in a different result number, and currently, the connector shows a warning when this happens.
The connector is created for the HelloID agent; therefore, the encoding is based on PowerShell 5.1. This presents a drawback when using the connector in the cloud. You need to convert the response differently to correctly display diacritics, as demonstrated below in multiple places in the code.
$responseSearchUser = (Invoke-WebRequest @splatSearchUser)
$correlatedAccount = ([Text.Encoding]::UTF8.GetString([Text.Encoding]::GetEncoding(28591).GetBytes(($responseSearchUser.Content))) | ConvertFrom-Json).Result.PagePowershell 7.1 Example:
$correlatedAccount = (Invoke-RestMethod @splatSearchUser).Result.Page- The roles include a UserType, where UserType '1' is specified for employees. The connector currently does not filter based on UserType, but this functionality can be incorporated into the permissions script to meet customer requirements.
- A role is assigned to a specific OrganizationUnit. If an employee is associated with multiple OrganizationUnits, the role can or must be assigned to each relevant unit. To support this, the connector implements SubPermissions to supports multiple assignments per role.
- To obtain the OrganizationUnitID, a mapping file is used to map the HelloID department to one or more New Black OrganizationUnits. (See: Mapping)
- The headers in the mapping file are fixed.
- The mapping is intended to create a mapping between a HelloID department and the New Black
OrganizationUnitIDs. - An example mapping file can be found in the
permissions\Rolesfolder asOrganizationUnitIdMapping.csv. - To define the property in the HelloID contracts, there is a script configuration in the
SubPermissions.ps1script.# Script Configuration $departmentLookupProperty = { $_.Department.ExternalId }
- IncludeAllCountries: By default the search will only return users from the same Country as the current OrganizationUnit. Optionally an extensive search can be performed by enabling this option. But keep in mind this will take some time in real production scenario's. It is advised to only show this option in the frontend after an initial search has been done in the current country.
The following endpoints are used by the connector
| Endpoint | Description |
|---|---|
| /message/SearchUsers | Retrieve user information |
| /message/GetUser | Retrieve user information by UserID |
| /message/GetEmployeeData | Retrieve Employee information by UserID |
| /message/CreateEmployeeUser | Create users and Employees |
| /message/UpdateUser | Update users |
| /message/CreateOrUpdateEmployeeData | Update Employees |
| /message/ListRoles | Retrieve roles information |
| /message/GetUserRoles | Retrieve existing user roles information |
| /message/SetUserRoles | Set roles to a user |
Access to the API documentation is restricted to users with valid credentials
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/