HelloID-Conn-Prov-Source-Elanza

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.

Table of contents

• HelloID-Conn-Prov-Source-Elanza
  • Table of contents
  • Introduction
    • Endpoints
  • Getting started
    • Connection settings
    • Remarks
      • Logic in-depth
        • What if the startAt is empty?
      • HistoricalDays & FutureDays
      • Empty workerNumber
      • No API call to get a list of departments and products
        • Person / department import
      • Customized error handling
  • Getting help
  • HelloID docs

Introduction

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.

Endpoints

Currently the following endpoints are being used where the plannedWorkers is custom made for HelloID.

Endpoint
/plannedWorkers
/department/{id}
/product/{id}

Elanzi API documentation.

Getting started

Connection settings

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

Remarks

Logic in-depth

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.

What if the startAt is empty?

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.

HistoricalDays & FutureDays

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.

Empty workerNumber

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.

No API call to get a list of departments and products

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.

Person / department import

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.

Customized error handling

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.

Getting help

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

HelloID docs

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