HelloID-Conn-Prov-Source-HR2Day

ℹ️ Information
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.

Versioning

Version	Description	Date
1.0.1	Hotfix for departments script: only send specific object and no longer all available data	2023/04/17
1.0.0	Initial release	2021/06/03

HelloID-Conn-Prov-Source-HR2Day

Introduction

HR2Day is an HR System and provides a set of REST API's that allow you to programmatically interact with it's data. The HelloID connector uses the API endpoints in the table below.

Endpoint	Description
/Emloyee	Contains the employee information.
/Arbeidsrelatie	Contains the information about employments. Employees can have multiple 'arbeidsrelaties'.
/Department	Contains the information about departments and managers.

Getting started

The HelloID-Conn-Prov-Source-HR2Day connector is created for both Windows PowerShell 5.1 and PowerShell Core. This means that the connector can be executed in both cloud and on-premises using the HelloID agent.

If you want to execute the connector using the HelloID agent, please check section: Execute the connector using the HelloID Agent

Connection settings

The following settings are required to connect to the API.

Setting	Description	Mandatory
ApiKey	The consumer key. This will be provided by HR2Day	Yes
ApiSecret	The consumer secret. This will be provided by HR2Day	Yes
UserName	The username to connect to the API	Yes
Password	The password belonging to the username + Plus security code	Yes
WG_Employees	The name of the 'werkgever' or 'employer' for the employees in HR2Day	Yes
WG_Deparments	The name of the 'werkgever' or 'employer' for the departments in HR2Day	Yes
Enable TLS1.2	Enables TLS 1.2	No
YearRange	The range of years in single digits e.g. 5, that determines the range for which the contract/workRelations [arbeidsrelaties] are retuned	No

The YearRange is used to decrease the dataset send back from HR2Day. Use this setting when the connector displays the error 'Could not retrieve arbeidsrelatiedata, the result exceeds the limit'

Prerequisites

Make sure to have gathered all necessary connection settings
The values for WG_Departments and WG_Employees

When using the connector in conjunction with the HelloID agent

The PSHR2DayAuth module files. Download from: https://github.com/Tools4everBV/HelloID-Conn-Prov-Source-HR2Day/tree/main/PSHR2DayAuth/bin
Windows PowerShell 5.1 installed on the server where the 'HelloID agent and provisioning agent' are running. Download from: https://www.microsoft.com/en-us/download/details.aspx?id=54616
.NET 4.7.2 (or higher) installed on the server where the 'HelloID agent and provisioning agent' are running. Download from: https://dotnet.microsoft.com/download/dotnet-framework/net472
Adjust the PowerShell code for both persons.ps1 and departments.ps1. See section Execute the connector using the HelloID Agent

Execute the connector using the HelloID Agent

Download all the files from the repository https://github.com/Tools4everBV/HelloID-Conn-Prov-Source-HR2Day/tree/main/PSHR2DayAuth/bin/
Copy the files to a sensible location.
Open the persons.ps1 and departments.ps1 files
Go to the Get-HR(Employee/Department)Data function
Add the folowing line within the try block on line 40

Import-Module "c:\temp\PSHR2Day.dll" -Force

Make sure to adjust the path [c:\temp\PSHR2Day.dll] and use the folder in which the PSHR2Day files are saved.
Replace the following lines:

$form = @{
    grant_type    = 'password'
    username      = $UserName
    client_id     = $ClientID
    client_secret = $clientSecret
    password      = $Password
}
$accessToken = Invoke-RestMethod -Uri 'https://login.salesforce.com/services/oauth2/token' -Method Post -Form $form

Replace with:

$splatTokenParams = @{
    UserName     = $UserName
    Password     = $Password
    ClientID     = $ClientID
    ClientSecret = $ClientSecret
}
$response = Get-HR2DayAccessToken @splatTokenParams
$accessToken = $response | ConvertFrom-Json

Remarks

When using the connector on Windows PowerShell 5.1 / The HelloID agent, you will need the PSModule DLL file to authenticate against HR2Day. Please not that the code will have to be changed in order to run on Windows PowerShell 5.1. See section Execute the connector using the HelloID Agent

TLS1.2

Enabling TLS 1.2 is not necessary when running the connector in the cloud

Pagination

Since the API does not support paging, we have to do our own paging. This is achieved by retrieving the arbeidsRelatieData in small yearly batches. If you provide a YearRange of 5 from the configuration, 5 consecutive API calls will be made. If the current year is 2021, the first batch contains data from [20160101 - 20170101]. And so on.

The last call in the do/until loop contains the data from [20200101 - 20210101]. We then have to make one additional call outside the loop to get the data from [20210101 - Now] where [Now] at this moment, is set to the last day of the current year.

Files	Description
Configuration.json	The configuration settings for the connector
Persons.ps1	Retrieves the person and contract data
Departments.ps1	Retrieves the department data
Mapping.json	A basic mapping for both persons and contracts

Setup the connector

Make sure to configure the Primary Manager in HelloID to: From department of primary contract

For help setting up a new source connector, please refer to our documentation

Change history

persons.ps1 [V1.0.0.4]

Updated to accommodate a preview (drynRun) import

persons.ps1 [V1.0.0.3]

Added YearRange to decrease the dataset
Added Errorhandling to throw when the dataset contains an error
Added logic to include only employees with one or more contracts in the raw data

departments.ps1 [V1.0.0.2]

Updated to accommodate a preview (drynRun) import

Getting help

If you need help, feel free to ask questions on our forum

HelloID Docs

The official HelloID documentation can be found at: https://docs.helloid.com/

tools4everbv / helloid-conn-prov-source-hr2day Goto Github PK