Warning
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-Source-Elanza
HelloID-Conn-Prov-Source-Elanza is a source connector. The purpose of this connector is to import plannedWorkers and their shifts. A shift represents a timetable entry and translates into a person contract.
Currently the following endpoints are being used where the plannedWorkers is custom made for HelloID.
Endpoint |
---|
/plannedWorkers |
/department/{id} |
/product/{id} |
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 |
HistoricalDays | - The number of days in the past from which the workers and shifts will be imported. - Will be converted to a [DateTime] object containing the current date minus the number of days specified. |
Yes |
FutureDays | - The number of days in the past from which the workers and shifts will be imported. - Will be converted to a [DateTime] object containing the current date plus the number of days specified. |
Yes |
ShiftDetailsStart | The number of days for which the shift details will be added as a contract rule | Yes |
The purpose of this connector is to import plannedWorkers and their shifts. A shift represents a timetable entry and will result a contract.
Planned workers are imported within a specified timeframe, configured by the HistoricalDays
and FutureDays
settings in the configuration.
Each plannedWorker typically has multiple shifts (one per day), we selectively import shifts as contracts from within the defined time frame.
The logic is as follows:
Data will be imported within a specified time frame, Controlled by the $historicalDays
and $futureDays
settings. Both values in days.
For example, if $historicalDays
is set to 60 and $futureDays
is set to 14, a total of 74 days will be imported.
As mentioned earlier, each shift corresponds directly to one day, resulting in 74 shifts and, consequently, 74 contracts.
However, an additional configuration setting is $shiftDetailsStart
.
If, for example, this is set to 7, the last 7 days of the $historicalDays
will result in individual contracts.
The remaining shifts will be aggregated into a single contract identified by a unique uuid.
That means that with the settings: $historicalDays
60, $futureDays
14 and $shiftDetailsStart
7, a total of 21 shifts will result in individual contracts plus one additional contract with the remaining historical data.
- 14 future contracts.
- 7 past contracts from the 60
$historicalDays
. - The remainder of 53 of the 60
$historicalDays
aggregated to 1 contract wit a fixed uuid.
Ultimately, a total of 22 contracts will be imported.
We made the assumption that this is not possible. Since the plannedWorkers API call is custom made for HelloID and because this call is meant to return shifts within the specified mandatory time frame. However, we added some simple logic in case it happens.
The PastDays
and FutureDays
configuration settings are used to specify the time range within which the plannedWorkers will be imported. Both will result in [DateTime]
object formatted as a: ISO8601 object. Example: 2023-12-14T11:50:19Z.
During testing we sometimes stumbled upon workers without a workerNumber
. The workerNumber
is mandatory since its gets mapped to the ExternalId
within HelloID. We made the assumption that this issue won't occur in a production environment.
Unfortunately there are no API calls to retrieve a list of departments or products. Both can only be retrieved by making an API call using the uuid
on a worker.shift.
The response to retrieve all plannedWorkers is as follows:
[
{
"worker": {
"email": "string",
"workerNumber": 0
},
"shifts": [
{
"startAt": "2024-02-04T11:00:00.000Z",
"endAt": "2024-02-04T17:00:00.000Z",
"productUuid": "1bd6cd19-1eb2-487e-bd8e-c4f66cb567fa",
"departmentUuid": "1bd6cd19-1eb2-487e-bd8e-c4f66cb567fa",
}
],
}
]
Both the productUuid
and departmentUuid
are part of the shifts object.
-
The productUuid_ contains a uuid that corresponds with a product. The product contains the skill or 'competitie'. Its mapped to the title attribute within HelloID.
-
The departmentUuid contains the uuid of the department and corresponds with a department object.
Both the product and department have a 1:N relation.
Because the product and department have a 1:N relation, we added some logic to prevent retrieving the same object in both the person and department import.
The Elanza API does not return a whole lot of error information. The error handling logic is tested on both Windows PowerShell and PowerShell Core.
One important thing to note is that the Invoke-ElanzaRestMethod
function is modified to NOT throw in case a product or department uuid
does not exist. This way, we ensure that the import does not fail.
ℹ️ For more information on how to configure a HelloID PowerShell connector, please refer to our documentation pages
ℹ️ If you need help, feel free to ask questions on our forum
The official HelloID documentation can be found at: https://docs.helloid.com/