Skip to content

Tools4everBV/HelloID-Conn-Prov-Source-Clevergig

BranchesTags

Repository files navigation

HelloID-Conn-Prov-Source-Clevergig

Create Release

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.

Table of contents

Introduction

HelloID-Conn-Prov-Target-Clevergig is a source connector. Clevergig provides a set of REST API's that allow you to programmatically interact with its data. Clevergig represents a system where gigs (tasks or jobs) are assigned to workers who fulfill specific roles. The work done on these gigs is logged in worklogs.

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 gigs will be imported Yes
FutureDays The number of days in the future from which the gigs will be imported Yes
CSVMappingFile Specifies the file name (including the path) for the CSV mapping file that contains the CostCenter mapping Yes
CSVMappingDelimiter The delimiter used within the CSV mapping file to separate columns, ensuring the file can be parsed and processed correctly Yes
ReportOnNonExistingWorklogs The delimiter used within the CSV mapping file to separate columns, ensuring the file can be parsed and processed correctly No

Remarks

How to interpret the data

Gig

A gig represents a task or job. In this dataset, each gig can be related to multiple workers, roles, and worklogs.

The gig data set is split into two arrays:
- Data (contains all the gigs)
- Includes (basic role, worker and worklog information.)

{
  "data": [
    {
      "id": "001",
      "type": "gig",
      "attributes": {
        "id": 001,
        "bookmark": false,
        "created_by": "John Doe",
        "title": "First shift",
        "status": "",
        "description": null,
        "hidden_description": null,
        "workers_needed": 1,
        "parent_id": null,
        "created_at": "29-08-2024 12:15",
        "updated_at": "28-10-2024 14:39",
        "date": "26-10-2024",
        "organization_title": null,
        "start_at": "15:00",
        "real_finish_at": "23:00",
        "duration": 8,
        "shift_type": null,
        "timebreak": 0,
        "location_address": "",
        "location_description": null
      },
      "relationships": {
        "roles": {
          "data": [
            {
              "id": "002",
              "type": "role"
            }
          ]
        },
        "workers": {
          "data": [
            {
              "id": "003",
              "type": "worker"
            }
          ]
        },
        "worklogs": {
          "data": [
            {
              "id": "004",
              "type": "worklog"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "002",
      "type": "role",
      "attributes": {
        "id": 1,
        "title": "Helpende"
      }
    },
    {
      "id": "003",
      "type": "worker",
      "attributes": {
        "id": 003,
        "first_name": "Emma",
        "last_name": "Brown",
        "phone": "",
        "email": "ebrown@enyoi",
        "status": "active",
        "external_id": 123456,
        "created_at": "2024-05-17T12:17:43.000Z",
        "updated_at": "2024-10-28T09:24:35.000Z",
        "short_description": null,
        "birthdate": null
      },
      "relationships": {
        "roles": {
          "data": [
            {
              "id": "002",
              "type": "role"
            }
          ]
        }
      }
    },
    {
      "id": "004",
      "type": "worklog",
      "attributes": {
        "id": 004,
        "worker_id": 003,
        "start_at": "15:00",
        "finish_at": "23:00",
        "status": "correct",
        "distance": "63.72",
        "signature_owner": null,
        "approved_by": null,
        "created_at": "2024-08-29T12:15:35.000Z",
        "updated_at": "2024-10-28T07:44:16.000Z",
        "placement_entity_id": null,
        "approver_type": null,
        "approver_id": null,
        "planner_distance": "63.72"
      }
    }
  ]
}

Role

A role represents the job position or responsibility a worker has within a gig. Each gig can have multiple roles, and a worker may hold several roles across different gigs. However, it's uncommon for a worker to hold multiple roles within the same gig.

{
  "data": [
    {
      "id": "002",
      "type": "role",
      "attributes": {
        "id": 002,
        "title": "Helpende"
      }
    }
  ]
}

Worker

A worker is the individual assigned to complete a gig. A gig can have multiple workers.

Important

Worker information is only accessible within a gig through the included/workers/worker array.

{
  "id": "003",
  "type": "worker",
  "attributes": {
    "id": 003,
    "first_name": "Emma",
    "last_name": "Brown",
    "phone": "",
    "email": "ebrown@enyoi",
    "status": "active",
    "external_id": 123456,
    "created_at": "2024-05-17T12:17:43.000Z",
    "updated_at": "2024-10-28T09:24:35.000Z",
    "short_description": null,
    "birthdate": null
  },
  "relationships": {
    "roles": {
      "data": [
        {
          "id": "002",
          "type": "role"
        }
      ]
    }
  }
}

Worklog

A worklog is a record that tracks the time a worker has spent on a gig, along with its status (such as approved or draft) and the approver’s information. In Clevergig, worklogs are linked to both workers and gigs, serving as the central object that connects gig, worker, and organizational data.

Important

Within the connector, worklogs are retrieved and filtered based on the organizationId from a CSV mapping. Worklogs are transferred to a worklogDTO object containing the following:

  • OrganizationId
  • GigId
  • WorkerId
{
    "id": "004",
    "type": "worklog",
    "attributes": {
        "id": 004,
        "worker_id": 003,
    }
}

CSV mapping

An additional CSV mapping file is utilized to extract the CostCenterCode. The process involves: retrieving all worklogs for a specific organization, matching each worklog with the worker by checking the worklogid and worker_id. Upon a successful match, the organizationId is used to lookup the corresponding CostCenterCode within the CSV file.

Id;CostCenterCode
005;ORG-1

Warning

The CostCenterCode is only available if the contract is of type gig.

UML

For a visual representation of the relationships between the different entities and a HelloID person/contract, refer to the UML diagram below:

uml

The proces in-depth

1. Import CSV mapping

  • Goal: Import additional mapping to allow for lookups by organizationid to complete the contract information with the correct CostCenterCode.

2. Retrieve all roles

  • Goal: Retrieve all available roles to allow for lookups by roleid to complete the contract information with the correct Title. The roles are stored in the allRoles list.

3. Retrieve arganizations and worklogs

  • Goal: Retrieve all organizations and their associated worklogs, then filter them based on a specified date range.
  • Process:
    • Retrieve all organizations using the Invoke-ClevergigRestMethod with the organizations? endpoint.
    • For each organization:
      • Retrieve the worklogs by calling the worklogs?by_organizations endpoint, applying the date range filters (start_date and finish_date).
      • For each worklog in the retrieved data:
        • Create a DTO object ($organizationWorklogDTO) containing the OrganizationId, logId, and WorkerId.
        • Add the DTO object to the $allWorklogsDTO list for further processing.

4. Retrieve worklogs per organization and filter on date range

  • Goal: Retrieve all worklogs for a specific organization and filter by a date range. The date range is determined by the days specified in the configuration settings:
    • HistoricalDays
    • FutureDays

5. Retrieve gigs, associated data and filter on date range

  • Goal: Retrieve gigs along with their related roles, workers, and worklogs. The data is filter by a date range. The date range is determined by the days specified in the configuration settings:
  • HistoricalDays
  • FutureDays
  • Data structure:
    • Data: An array containing:
      • id: Unique identifier for each gig.
      • type: Type of data entry.
      • attributes: Contains details such as status and date.
      • relationships: Lists linked objects, including:
        • roles
        • workers
        • worklogs
    • Includes: An array containing basic information for:
      • role
      • worker
      • worklog

6. Separate the gigs and associated data into lists

  • Goal: Separate the gigs and the included array into different lists for easier processing.

7. Gather all workers

  • Goal: Build a list of all workers associated with each gig.
  • Process:
    • Loop through gig.relationships.workers to collect all workers.
    • For each worker:
      • Look up the worker object in includes by matching id and type.
      • Add each worker to a list for further processing.

8. Process all workers

  • Goal: For every worker, build up the full person object.
  • Process:
    • For each worker:
      • Retrieve the gigs associated with them and lookup the worker details in the includes array.
      • Contract Details:
        • Duration: Use the date field (start and end dates) of each gig as the contract period.
        • Cost Center: Derived from a CSV lookup based on worklog/organization.id.
        • Title: Retrieved from the roles data using title.id.

9. Retrieve worklogs and associate CostCenter details

  • Goal: Retrieve all worklogs for a specific worker and gig, then associate the corresponding cost center details from a CSV mapping.
  • Process:
    • Loop through all worklogsDTO to find logs that match the workerGig.relationships.worklogs.data.id and worker.workerId.
    • For each matching worklog:
      • Add the worklog to the $gigDTOWorklogs list.
    • Retrieve the organizationId from the first matching worklog in the list.
    • If the organizationId is found:
      • Look up the corresponding cost center details in the $costCenterCodes CSV mapping file by matching the organizationId.
      • Extract the following cost center details:
        • Id
        • Title
        • LocatiesAdressen
        • IntusResourceGroupId
        • FactureringKostenplaats
      • Store the extracted details in the $gigContract.CostCenterDetails object for further processing.

10. Get title information by looking up the roleid within the allRoles list

  • Goal: Retrieve the role information associated with a gig and set the gig contract title based on the role.
  • Process:
    • Check if the gig.relationships.roles.data is not null.
    • If roles are present:
      • Use the role ID from gig.relationships.roles.data[0].id to find the matching role in the allRoles list.
      • Set the Title of the $gigContract to the title attribute of the matching role.

11. Construct the startDate and endDate

  • Goal: Set the start and end dates for the gig contract based on the worker gig's date.
  • Process:
    • Parse the workerGig.attributes.date using the format "dd-MM-yyyy" to set the StartDate of the $gigContract.
    • Set the EndDate of the $gigContract to one day after the StartDate, subtracting one second to ensure it reflects the end of the day.

12. Complete person object with contract informtion

  • Goal: Create the contract objects for both the gig and role type contracts.

Development resources

API endpoints

The following endpoints are used by the connector

Endpoint Description
/gigs Retrieve information about gigs. The data set is split into two arrays:
- Data (gigs)
- Includes (basic roles information, workers, and basic worklog information)
/roles Retrieve all available roles.
Since the /gigs/includes/roles only contains the role.id, we need to look up specific information within the full role object.
/worklogs/{id} Retrieve information about worklogs.
Since the /gigs/includes/worklogs only contains basic worklog information, we need the full worklog object to extract organizational data.

API documentation

The API documentation can be found on: https://api.clevergig.nl/api-docs/index.html

Getting help

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.

HelloID docs

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

About

Clevergig - Source

Topics

cloud source provisioning hrm

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

4 watching

Forks

0 forks
Report repository

Releases 2

v1.1.0 Latest
Dec 5, 2024
+ 1 release

Packages

No packages published

Contributors 2

  •  
  •  

Languages