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.
Note
This connector has limited support for Nedap employees. Please check the Fact Sheet for more details.
Extensive knowledge of HelloID provisioning and Nedap Ons (Nedap user and Nedap employee) are required.
Important
Upgrade warning!
Since the November 14, 2024 update, the connector has been changed from using a single mapping file to three separate files. If a customer prefers not to use three separate mapping files, they can continue to use the previous NedapEmployeeMapping.csv file for all three mappings by adding the same file three times in the configuration.
Important
Upgrade warning!
Since the June 12, 2025 update, the way the Account Reference is stored has changed. To upgrade from an existing V2 version to this version, a one-time fix should be performed in HelloID along with the "Update all Accounts" action to convert the Account Reference to the new format. See more: Account Reference Conversion
- HelloID-Conn-Prov-Target-NedapOns-Employee
- Table of contents
- Introduction
- Supported features
- Getting started
- Remarks
- Mapping Remarks
- Governance Remarks
- Employee Additional Mapping:
- Supported Properties
- Fact Sheet
- Development resources
- Getting help
- HelloID docs
This Repository does only contains the readme. The source code can be found in a private Repository and is meant only for internal use. Link to Repository: Nedap Ons Employee
Nedap Ons provides an API and XML import method to programmatically interact with its services and data. This connector has limited support for managing employees in Nedap. It does not support (employee nor client) scheduling or other none Identity and Access management functionality. It can create multiple employees accounts in Nedap for each employment (EmployeeId and Employment sequence number combination).
The following features are available:
| Feature | Supported | Actions | Remarks |
|---|---|---|---|
| Account Lifecycle | ✅ | Create, Update, Delete, Correlate only | |
| Permissions | ✅ | Set (Cluster, Education, RegistrationProfile) | |
| Resources | ❌ | - | |
| Entitlement Import: Accounts | ✅ | Import remarks | |
| Entitlement Import: Permissions | ✅ | Import remarks | |
| Governance Reconciliation Resolutions | ✅ | Reconciliation (Reporting Only) Governance Remarks |
- Nedap PFX Certificate
A valid Nedap certificate (.PFX) Tools4ever need to requests a certificate by Nedap to access the REST API - Credentials IOImport
Credentials for the IO Import Different account credentials as the REST API - Mapping Files
Mapping between HR departments/functions to Cluster/ Education/ registrationProfile - Custom HelloId Property
A custom property on the HelloID Person contract with a combination of the employeeCode and EmploymentCode called:custom.NedapOnsIdentificationNoExample:function getValue() { return sourceContract.PersonCode + "-" + sourceContract.EmploymentCode; } getValue();
The following settings are required to connect to the API.
| Setting | Description | Mandatory |
|---|---|---|
| Environment (Rest) | The Nedap Environment of the API (Development, Staging, Production ) | Yes |
| Certificate (.PFX) Path | Nedap-Cert.pfx | Yes |
| Certificate Password | Password of the certificate | Yes |
| IO ImportUrl | The URL to the IOImport, Example: "https://<.ioservice.net/importws/import" | Yes |
| IO ImportUsername | The UserName to connect to the IO Import | Yes |
| IO ImportPassword | The Password to connect to the IO Import | Yes |
| CSV Mapping Weekkaart | The Path to the mapping file Weekkaart | Yes |
| CSV Mapping Deskundigheid | The Path to the mapping file Deskundigheid | Yes |
| CSV Mapping Teams | The Path to the mapping file Teams | Yes |
| CSV Separation Character | Mapping File CSV Separation Character | Yes |
| Skip mapping for cluster | Don't use a mapping file for Teams, but directly use HelloID contract values | Yes |
| Encoding for the csv imports. | Default value is 'Default' | Yes |
| Import Only Active Employees. | When toggled, The Import script will only import employees that have currently active contracts in the Nedap ONS system. | Yes |
| Days before start of the contract. | Days before start of the contract. Only used when the Import Only Active Employees is enabled. |
Yes |
| Days after end of the contract. | Days after end of the contract. Only used when the Import Only Active Employees is enabled. |
Yes |
The correlation configuration is used to specify which properties will be used to match an existing account within NedapOns-Employee to a person in HelloID.
| Setting | Value |
|---|---|
| Enable correlation | True |
| Person correlation field | ExternalId |
| Account correlation field | _outputInfo.externalId |
Important
Correlation should be enabled even when no direct person properties are used for correlation in the account Life Cycle. When correlation is not enabled, a correlated account will not be updated during account correlation. The Update action will not be triggered when Correlation is disabled. See remark Correlation.
The correlation properties are solely for the import and reconciliation. See remark 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 multiple employee objects for each Employment (employeeId + SequenceNumber), based on the contracts in condition from the Business Rules. |
| delete.ps1 | Removes an existing account or entity. |
| update.ps1 | - Update attributes of the corresponding employee account as configured in the fieldMapping. - Create new employee account for each Employment (employeeId + SequenceNumber) combination. - Disable account reference from Account Reference -See delete action- |
| correlateOnly\Create.ps1 | Correlate existing accounts only. Script should be used in the Create and Update action. |
| import.ps1 | Import the existing account from Nedap (Configurable by active) |
| permissions/Cluster | Grant Cluster (Team) permissions to employee accounts |
| permissions/Cluster/permission | Cluster (Team) permissions reference |
| permissions/Cluster/import | Import all Cluster (Team) permissions (Configurable by active) |
| permissions/Education | Grant Education (DeskundigheidsProfiel) permissions to employee accounts |
| permissions/Education/permission | Education (DeskundigheidsProfiel) permissions reference |
| permissions/Education/import | Import all Education (DeskundigheidsProfiel) permissions (Configurable by active) |
| permissions/RegistrationProfile | Grant RegistrationProfile (Weekkaart) permissions to employee accounts |
| permissions/RegistrationProfile/permission | RegistrationProfile (Weekkaart) permissions reference |
| permissions/RegistrationProfile/import | Import all RegistrationProfile (Weekkaart) permissions (Configurable by active) |
| 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 using the _fieldMapping.json file.
In addition to the field mapping, some properties require extra mappings that are not included in the file. These properties are managed as follows:
- MutationAction - Added directly in the code
- Contract - Added directly in the code
- Cluster (Team) - Managed through permissions scripts
- Education (Deskundigheidsprofiel) - Managed through permissions scripts
- RegistrationProfile (Weekkaart) - Managed through permissions scripts
Besides the configuration and field mapping, you can also configure script variables to decide which property from the HelloID contracts is used to look up a value in the mapping tables and how the primary contract calculation should be done. Please note that the same configuration must be applied in the permissions scripts (Cluster, Education, and RegistrationProfile), as shown below:
The primary contract calculation is the same as the HelloID primary contract calculation. Note that the order of properties can be adjusted to meet the customer's requirements.
## Configuration
# Primary Contract Calculation foreach employment
$sortableEndDate = { if ([string]::IsNullOrEmpty($_.EndDate)) { [datetime]::MaxValue } else { $_.EndDate } }
$firstProperty = @{ Expression = { $_.ComputedIsActive }; Descending = $true }
$secondProperty = @{ Expression = { $_.Details.Fte }; Descending = $true }
$thirdProperty = @{ Expression = { $_.Details.HoursPerWeek }; Descending = $true }
$fourthProperty = @{ Expression = { $_.Details.Sequence }; Descending = $true }
$fifthProperty = @{ Expression = $sortableEndDate ; Descending = $true }
$sixthProperty = @{ Expression = { $_.StartDate }; Descending = $false }
$seventhProperty = @{ Expression = { $_.ExternalId }; Descending = $false }
# Priority Calculation Order (High priority -> Low priority)
$splatSortObject = @{
Property = @(
$firstProperty,
$secondProperty,
$thirdProperty,
$fourthProperty,
$fifthProperty,
$sixthProperty,
$seventhProperty)
}Script Mapping lookup values for Education and RegistrationProfile subPermission scripts
# Lookup values which are used in the mapping to determine the subPermissions
$primaryLookupKey = { $_.Title.ExternalId } # Mandatory
$secondaryLookupKey = { $_.Department.ExternalId } # Not Mandatory
Script Mapping lookup values for Cluster subPermission script
# Lookup values which are used in the mapping to determine the subPermissions
$primaryLookupKey = { $_.Department.ExternalId } # Mandatory
$secondaryLookupKey = { $_.Title.ExternalId } # Not Mandatory
if ($actionContext.Configuration.skipCsvMappingForCluster) {
Write-Information 'NO additional CSV Mapping used, using HelloID contract values'
$clusterId = { $_.Department.ExternalId }
$clusterName = { $_.Department.DisplayName }
}else ....Because Nedap contains multiple accounts per HelloID person, the accounts will be correlated based on a custom Contract property named custom.NedapOnsIdentificationNo. An example can be found in the Prerequisites. This is because HelloID does not support correlation based on Contract properties. Even though we cannot use the Person correlation configuration directly from HelloID, the connector correlation should be enabled. Otherwise, you will lose the update trigger when an account is correlated, and the correlated accounts will not be directly updated after correlation.
Tip
The import and reconciliation functionality uses the correlation directly on the Person property. See remark Import
This connector only supports a limited Employee object. When the required functionality is outside scope of this limited Employee connector, you will need an external supplier to configure a direct connection between your HRM system and Nedap Employees. It this situation, we can still manage your Ons user accounts and permissions.
Since the connector supports multiple accounts for a single HelloID person (per contract), the default primary contract calculation may not always be applicable for the permission scripts. The connector includes an example primary contract calculation that determines the primary contract for each employment in Nedap.
You can use this connector in combination with the Nedap-Users connector. When you use them both in the same environment. You must add the Employee Target system as "Use account data from system". To make sure the employee object exists in Nedap before starting to create the account object.
The connector includes a correlateOnly\Create.ps1 script that can be used in both the Create and Update actions. This script is designed to correlate existing Nedap employee accounts without making any changes to the account properties. This is particularly useful when using an HRM synchronization that does not support updating Weekkaart, Cluster, or DeskundigheidsProfiel. In this scenario, the HR synchronization creates and updates the employee accounts, and HelloID manages the additional properties without updating the actual accounts.
When updating an employee account, it's not possible to directly verify whether the properties are successfully updated in Nedap. To confirm this, you need to check the* Import Report* in the Nedap UI by going to: Beheer > Import > Importrapportage inzien.
Note that in preview mode (DryRun), all HelloID contracts of a Person are in scope. Therefore, it does not simulate the actual outcome when it comes to determining which account should be created, updated, or deleted. However, this DryRun mode is added to verify if the mapping, configuration settings, etc. are present and correct. The contracts in scope are normally configured in the business rules. This cannot be stimulated in Preview.
In the field mapping, some properties have a _outputInfo prefix. These properties are only used to return data from the connector, and the information is visible in the account data or in the notification. Since there can be multiple accounts, the connector returns the values as comma-separated strings. Note that there is no link between the individual values.
- NedapOnsIdentificationNo
- isDeleted
- isCreated
- externalId (Only used in Import.ps1)
The connector relies on the properties inside _outputInfo. When a specific outputInfo is not required and is removed from the field mapping, the code might need to be adjusted to prevent issues.
The connector is designed using the following steps: First, it calculates and verifies the actions for each desired account and stores the necessary information to create, update, or delete in an ActionDetails list. Once all the information is gathered, the connector proceeds with the standard process to execute the actions using the ActionList for each account.
There is a mismatch between the account object from the REST API and the IOImport. To compare the account properties, the connector uses a hardcoded object to compare the properties against the ActionContext.Data. This means that when you add a new property in the FieldMapping, you should also remember to add the property to this hardcoded comparison object.
[!TIP] The hardcoded object is also used in the import script. To retrieve the same property in both the import and the 'normal' account, these objects should match each other.
The connector has two properties: IsCreated and IsDeleted. These properties are used for custom notifications. The connector cannot use the standard notification because there are multiple accounts per person. Therefore, it is possible that an account is created in the Update script, or during creation, one of the two accounts is correlated, triggering an account update. This means there will be no standard creation trigger
The properties are populated with the accounts that are created or deleted, respectively, in the Create, Update, and Delete actions. When there are no creations or deletions, it returns null. Therefore, you will need multiple custom events to cover all cases. You can also use the Has Value filter. Example notification message: _Created accounts with the following NedapOnsIdentificationNo's: [{{DATA.outputInfo.isCreated}}]
Tip
Read more about Custom Notification.
To support Nedap Account import scripts, the account reference object has been changed to a HashTable. Previously, the account reference was stored as an array. If you already have a Nedap Employee V2 version running, you can copy the code block below to the top of the update script. After that, click "Update all Accounts" and run an Enforcement. This will convert the "old" account references to the current format. Once the process is complete, you may remove the code block. However, leaving it in the update script will not cause any issues.
# Fix to migrate from the old AccountReferences to the new AccountReference.
if (-not [string]::IsNullOrEmpty($($actionContext.References.Account))) {
if ($actionContext.References.Account.GetType().fullname -eq 'System.Object[]') {
$accountReferences = [PSCustomObject]@{}
foreach ($account in $actionContext.References.Account) {
$accountReferences | Add-Member @{
$account = $account
}
}
$actionContext.References.Account = $accountReferences
}
}Example mappings can be found in the Assets folder.
The connector manages three properties (Cluster, Education, and RegistrationProfile) through individual permissions scripts. These properties cannot be mapped directly from the person model in HelloID, so multiple mapping files are required. These files must include a mapping between HR departments and/or functions to a Nedap Cluster, Education, or Registration profile. The permissions scripts will fail when no mapping is found. Of course, this can be changed in the code, but it is not configurable by default.
The Teams/Cluster mappings are often a one-to-one relationship with the HelloID data model, meaning no mapping file is required. The Cluster permissions script offers a switch in the configuration that determines whether to use HelloID values directly. When using direct values, there is also a specific mapping that determines when these values should be used, as shown in Cluster Configuration
Tip
Please note that, starting with version 2.0.0, the connector was changed from using a single mapping file to three separate files. If a customer does not want to use three separate mapping files, they can use the previous NedapEmployeeMapping.csv file for all three mappings by simply adding the same file three times in the configuration.
The Nedap connector supports importing Nedap employee accounts, and the import functionality can be used as normal. However, there are some important remarks to keep in mind, see the Import remarks section for details. Reconciliation is intended for reporting purposes only.
When accounts are imported, any Nedap accounts for the employee are detected by HelloID and, as a result, will be revoked during the next enforcement or account update. Normally, this can only happen to (sub)permissions. But in Nedap, you can have multiple accounts for a single HelloID Person, so the same rule applies as for the Subpermissions.
The import only detects users without an existing linked Nedap account in HelloID. Users who already have a linked account and receive additional Nedap accounts won’t appear in the entitlement import. Therefore, the import script is primarily intended for initial implementation.
To perform person correlation, the IdentificationNo is split on the dash (-) to extract the employee number. This differs from the approach used in the Account Lifecycle, where a custom property combining the employee number and contract number is used to correlate individual accounts.
To store the employee number, the _outputInfo.externalId property is used in the field mapping. Please note that this field is only used by the import script.
The hardcoded account mapping used in the update script for comparison is also used in the import script. Make sure these objects are the same to keep the account properties consistent. (See: Compare)
The import scripts include configuration options for which accounts to retrieve. By default, all accounts are retrieved and shown in the import overview, but you may want to exclude past accounts. This can be done by toggling ImportOnlyActiveEmployees, which retrieves only accounts with active contracts.
The ImportOnlyActiveEmployees toggle also enables additional settings to expand the range of active contracts considered, using daysBeforeContractStartDate and daysAfterContractEndDate. These values can be adjusted in the configuration.
Warning
When using the import script on an initial implementation, be aware that employees are imported based on the employee number. This includes employees with an IdentificationNo not based on the contract sequence (123456-ABC vs 123456-1) but do contain the employee number. These contracts are included in the accountReference array. After an enforcement these accounts will be disabled, cause no related active contract can be found. During initial implementation these kind of accounts should be filtered out of the import population!
Account access is not used in the Nedap Employee Connector; therefore, no Account Access entitlements will be granted.
The Nedap API does now support retrieving the RegistrationProfile, Cluster, and Education properties; These properties are managed through individual permissions scripts (Cluster, Education, and RegistrationProfile)
Reconciliation for Nedap cannot be fully used because there is a one-to-many relationship between a HelloID person and Nedap accounts. Due to the risk of unwanted account deletions, reconciliation should be used only as a reporting tool to compare HelloID against Nedap. The deletion action is blocked, but creating accounts is still possible—although this is not yet fully supported.
However, if you try to delete the unmanaged account, HelloID executes the delete action from the account lifecycle, which deletes the account entitlement and consequently removes all accounts from HelloID. Normally, account deletions involving multiple accounts are handled in the Update.ps1 script to manage this situation.
- Therefore, deletion from reconciliation is blocked in the delete action to prevent accidental account deletions.
Reconciliation does not support custom or built-in events when deleting accounts through reconciliation.
Due to multiple accounts per HelloID person, old (unmanaged) accounts cause managed persons in HelloID to repeatedly appear in each report because of mismatches between accounts managed by HelloID and those still existing in Nedap. You cannot exclude the person entirely since they are still in scope, but only some of their accounts are not. Additionally, excluding accounts at this level is not possible.
To minimize this issue, you are able to filter in the import script to retrieve only active accounts. See Import configuration
When importing accounts from Nedap, a single person can have multiple accounts. Therefore, the connector choose one account’s properties which are displayed in the reconciliation report.
| Header | Description |
|---|---|
| Primary Contract calculation | Example of a Primary contract calculation. |
| HelloIDPrimaryLookupKey | The Primary property of the HelloID primary contract per employment |
| HelloIDSecondaryLookupKey | The Secondary Property of the HelloID primary contract per employment |
| EducationId | Deskundigheidsprofiel > Import Code |
| RegistrationProfile | Weekkaartprofiel > ProfileName |
| ClusterId | Organigram > Identificatie |
| ClusterName | Organigram > Naam |
Tip
That the mapped value will be created if they do not exist in Nedap! So if you choose in a RegistrationProfile that does not exist, it will be created. What might encounter some unexpected behavior.
| PropertyName | Notes |
|---|---|
| Id | IdentificationNo |
| Firstname | |
| Birthname | |
| Lastname | |
| DateOfBirth | |
| EmailAddress | |
| Gender | |
| Initials | |
| NameUsage | |
| AuthenticationNumber | Is required for second factor |
| Education | Deskundigheidsprofiel => Import Code (Managed via Permissions) |
| RegistrationProfile | Weekkaartprofiel => ProfileName (Managed via Permissions) |
| Cluster | Organigram > Identificatie (Team) (Managed via Permissions) |
| Contract | Only a single Employment. With start and EnDate. |
The following table displays an overview of the functionality for the Nedap Ons connector for HelloID Provisioning and Service Automation.
| Type of action | Nedap | HelloID provisioning | HelloID Service Automation |
|---|---|---|---|
| Create Employees | Yes | Yes, Simple employee, no scheduling | No |
| Update Employees | Yes | Yes, Simple employee, no scheduling | No |
| Delete Employee | No | No, Sets an endDate on contract | No |
| Manage Employee Contracts | Yes | Yes 1 contract, Simple employee, no scheduling | No |
| Set RegistrationProfile (Weekkaart) | Yes | Yes, Via Permissions, Additional mapping required | No |
| Set Cluster (Team) | Yes | Yes, Via Permissions, Additional mapping required | No |
| Set education (Deskundigheidsprofiel ) | Yes | Yes, Via Permissions, Additional mapping required | No |
| Set Dashboard Profile | No | No | No |
| Set Discipline | Yes | No | No |
| Set Profession (Beroepsgroep) | Yes | No, outside the scope of identity management. | No |
| VacationRight | Yes | No, outside the scope of identity management. | No |
| AccountAmount | Yes | No, outside the scope of identity management. | No |
| VacationAmounts | Yes | No, outside the scope of identity management. | No |
| CompensationAmount (compensatiesaldo) | Yes | No, outside the scope of identity management. | No |
| CompensationSetting (compensatieberekening instellingen) | Yes | No, outside the scope of identity management. | No |
| HourlyWages | Yes | No, outside the scope of identity management. | No |
| CollectiveAgreement | Yes | No, outside the scope of identity management. | No |
| Addresses | Yes | No, outside the scope of identity management. | No |
| FreeField | Yes | No | No |
The following endpoints are used by the connector
| Endpoint | Description | Type |
|---|---|---|
| /v0/administration/employees/by_identification_no/{identificationNo} | Retrieve single Employee Information | Rest |
| /v0/xstream/employees/data | Retrieve Employee Information List | Rest |
| /v0/xstream/contracts/data | Retrieve Contract Information | Rest |
| /v0/xstream/team_assignments/data | Retrieve Team/Clusters Assignments | Rest |
| /v0/administration/teams | Retrieve Teams/Clusters | Rest |
| /v0/administration/employees/{employeeId}/expertise_profiles | Retrieve Employee Expertise Profiles | Rest |
| /v0/administration/employees/{employeeId}/weeksheet_profile | Retrieve Employee Registration Profile | Rest |
| /v0/administration/employees/{employeeId}/clipped_teams?valid_from={date}&valid_to={date} | Retrieve Employee Cluster/Team Assignments | Rest |
| /importws/import | CRUD Employee Information | IOImport |
- Nedap API documentation → Click
- Nedap XML IOImport Manual → Click
- Nedap XML IOImport Documentation → Click
- Nedap ONS authorization Manual → Click
[!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/