{"id":19504328,"url":"https://github.com/tools4everbv/helloid-conn-prov-source-adp-workforce","last_synced_at":"2026-02-18T14:35:23.069Z","repository":{"id":94206289,"uuid":"464553120","full_name":"Tools4everBV/HelloID-Conn-Prov-Source-ADP-Workforce","owner":"Tools4everBV","description":"ADP Workforce - Source","archived":false,"fork":false,"pushed_at":"2025-11-26T08:39:04.000Z","size":125,"stargazers_count":1,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-11-29T08:22:58.485Z","etag":null,"topics":["cloud","hrm","provisioning","source"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tools4everBV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-28T16:11:48.000Z","updated_at":"2025-11-26T08:39:07.000Z","dependencies_parsed_at":"2024-01-15T14:46:27.694Z","dependency_job_id":"c7306f75-e8e6-47bb-8520-30a88eea01c0","html_url":"https://github.com/Tools4everBV/HelloID-Conn-Prov-Source-ADP-Workforce","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Tools4everBV/HelloID-Conn-Prov-Source-ADP-Workforce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Source-ADP-Workforce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Source-ADP-Workforce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Source-ADP-Workforce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Source-ADP-Workforce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tools4everBV","download_url":"https://codeload.github.com/Tools4everBV/HelloID-Conn-Prov-Source-ADP-Workforce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tools4everBV%2FHelloID-Conn-Prov-Source-ADP-Workforce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29582318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T13:56:48.962Z","status":"ssl_error","status_checked_at":"2026-02-18T13:54:34.145Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud","hrm","provisioning","source"],"created_at":"2024-11-10T22:25:22.461Z","updated_at":"2026-02-18T14:35:18.062Z","avatar_url":"https://github.com/Tools4everBV.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HelloID-Conn-Prov-Source-ADP-Workforce\n\n| :warning: Warning |\n|:---------------------------|\n| The latest version of this connector requires a few custom fields to be set. See [custom mapping](#custommapping) for more details.\n\n| :information_source: Information |\n|:---------------------------|\n| 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.       |\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://www.tools4ever.nl/connector-logos/adp-logo.png\" width=\"500\"\u003e\n\u003c/p\u003e \n\u003cbr /\u003e\n\n\u003c!-- Version --\u003e\n## Version\n| Version | Description | Date |\n| - | - | - |\n| 3.0.0   | Update readme, changed endpoints, minor fixes | 27/01/2025  |\n| 2.1.3   | Update readme, added filter for past contract, mod endDate mapping | 14/05/2024  |\n| 2.1.2   | Update readme, added option for cloud agent | 13/12/2023  |\n| 2.1.1   | Update readme | 08/09/2023  |\n| 2.1.0   | Added support for cloud by using base64 pfx string | 06/09/2023  |\n| 2.0.1   | release of v2 | 13/07/2023  |\n| 1.1.0   | Performance updates and added support for custom fields | 05/05/2022  |\n| 1.0.0   | Initial release | 28/02/2022  |\n\n\u003c!-- Requirements --\u003e\n## Requirements\n- The 'Execute on-premises' switch on the 'System' tab is toggled if using the certificate file\n- Windows PowerShell 5.1 installed on the server where the 'HelloID agent and provisioning agent' are running if using the certificate file\n- The public key *.pfx certificate belonging to the X.509 certificate that's used to activate the required API's.\n- The password for the public key *.pfx certificate.\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n## Table of Contents\n- [HelloID-Conn-Prov-Source-ADP-Workforce](#helloid-conn-prov-source-adp-workforce)\n  - [Version](#version)\n  - [Requirements](#requirements)\n  - [Table of Contents](#table-of-contents)\n  - [Introduction](#introduction)\n    - [API's being used by the HelloID connector](#apis-being-used-by-the-helloid-connector)\n  - [Getting started](#getting-started)\n    - [Supported PowerShell versions](#supported-powershell-versions)\n    - [X.509 certificate / public key](#x509-certificate--public-key)\n    - [X.509 certificate / Private key](#x509-certificate--private-key)\n    - [AccessToken](#accesstoken)\n    - [Paging](#paging)\n    - [Assignments](#assignments)\n    - [Custom Fields](#custom-fields)\n    - [Mappings](#mappings)\n    - [Custom mapping](#custommapping)\n    - [Caveats](#caveats)\n  - [PowerShell functions](#powershell-functions)\n    - [Sample data](#sample-data)\n  - [Setup the PowerShell connector](#setup-the-powershell-connector)\n- [HelloID Docs](#helloid-docs)\n\n\u003c!-- Introduction --\u003e\n## Introduction\nADP Workforce is a cloud based HR management platform and provides a set of REST API's that allow you to programmatically interact with it's data. The HelloID source connector uses the API's in the table below.\nNote that the _'HelloID-Conn-Prov-Source-ADP-Workforce'_ implementation is based on ADP Workforce environments for the Dutch market. If you want to implement the connector for the US market, changes will have to be made within the source code.\n\n### API's being used by the HelloID connector\n| _API_ | _Description_|\n| - | - |\n| _accounts.eu.adp.com/auth_ | _Url for autorisation is different than baseurl_ | \n| _Workers_ | _Contains the employees personal and contract data_ |\n| _Organization-Departments_ | _Contains data about the organisation structure_ |\n\n\u003c!-- Getting started --\u003e\n## Getting started\n\n### Supported PowerShell versions\nThe recommended PowerShell version for the  _'HelloID-Conn-Prov-Source-ADP-Workforce'_ is _Windows PowerShell 5.1_. The connector is not tested on older versions of Windows PowerShell. This is only applicable if using the option \"Certificatepath\" in the configuration.\n\n_PowerShell 7.0.3 Core_ is supported when using the option \"Base64 string of certificate\".\n\n### X.509 certificate / public key\n\nTo get access to the ADP Workforce API's, a x.509 certificate is needed. Please follow the steps below to provide this.\n1. The customer creates a CSR and sends this to ADP. Please follow the [ADP documentation to create the Certificate Signing Request](https://developers.adp.com/articles/guides/adp-marketplace---getting-started?chapter=2)\n2. ADP will create the X.509 certificaat, client_id and client_secret and will send these to the customer.\n3. The customer sends the X.509 certificaat, client_id and client_secret to Tools4ever (or any other implementer).\n\u003e **Note:** Each ADP environment requires its own certificate. If there is an Accept and a Production environment, 2 certificates are required.\n\nAPD will register an application that's allowed to access the specified API's. _workers_ and _organizational_departments_. Other API's within the ADP Workforce environment cannot be accessed.\n\n## Importing *.pfx File Options\n\nThere are two methods available for importing the *.pfx file:\n\n### Option 1: Certificate Path\n\nThis option, labeled as \"Certificate Path,\" requires specifying the path to the *.pfx file on the machine where the agent is configured. This method is suitable for local on-premise agents.\n\n### Option 2: Base64 String of Certificate\n\nOption 2, named \"Base64 String of Certificate,\" involves providing a base64-encoded string of the *.pfx file. PowerShell then converts this string to a certificate object. This approach eliminates the necessity for a local on-premises agent.\n\n#### Steps to Use Option 2:\n\n1. Execute the following code to copy the base64 string of your *.pfx file to your clipboard:\n\n    ```powershell\n    [System.Convert]::ToBase64String((Get-Content \"C:\\*.pfx\" -Encoding Byte)) | Set-Clipboard\n    ```\n\n2. Leave the configuration of \"Certificate Path\" empty.\n\n### AccessToken\nIn order to retrieve data from the ADP Workforce API's, an AccessToken has to be obtained. The AccessToken is used for all consecutive calls to ADP Workforce. To obtain an AccessToken, we will need the ___ClientID___, ___ClientSecret___, ___The path to your pfx certificate___ and the ___password for the pfx certificate___.\n\nTokens only have access to a certain API scope. Default the scope is set to: 'worker-demographics organization-departments'. Data outside this scope from other API's cannot be retrieved\n\n### Paging\nPaging is only supported by ADP for the 'worker-demographics' endpoint. Paging is implemented in the connector for the 'worker-demographics' endpoint.\n\n### Assignments\nIf a worker has multiple assignments, each assigment will be imported in HelloID.\n\n### Custom Fields\nBoth the worker and assigment(s) may contain _custom fields_. Custom fields will be automatically imported in HelloID.\n\nCustom fields can be selected in both the _person_ and _contract_ mapping.\n\n### Mappings\nA basic person and contract mapping is provided. Make sure to further customize these accordingly.\n\n**Note:**  Fields in the JSON output are no longer displayed if they do not contain a value. Make sure to validated on objects when using complex mapping\n\n### Custommapping\nTo correctly import the mapping a couple customfields need to be added in HelloID.\n\n| _Model_ | _Field_ | _ADP source field_ | _type_ | _comment_ |\n| - | - | - | - | - |\n| Person | AssociateOID | associateOID | Field | Needed when updating the business e-mailadres through ADP target connector |\n| Person | IsManager | IsManager | Field | Calculated through importscript |\n| Contract | ADPReportingCode | occupationalClassifications.classificationCode.codeValue | Complex | Specific code value administrationvalue for employee |\n| Contract | ADPReportingCodeShortName | occupationalClassifications.classificationCode.shortName | Complex | Specific name value administrationvalue for employee |\n| Contract | DepartmentShortCode | organizationalUnit.departmentCode.shortName | Field | Department abbreviation, which is different than department id |\n| Contract | FormationPostion | positionID | Field | |\n| Contract | ParentDepartmentShortCode | organizationalUnit.parentDepartmentCode.codeValue | Complex | Specific code value of parentdeparment |\n| Contract | ParentDepartmentShortName | organizationalUnit.parentDepartmentCode.codeValue | Complex | Specific name value of parentdeparment |\n\n\n### Caveats\n__[worker.businessCommunication]__\n\nThe _[worker.businessCommunication]_ array contains information about the:\n\n- Fixed Phone Number\n- Mobile Phone Number\n- Email Address\n\nAll three are array's. Implying that they may contain multiple items.\n\nSince the data can contain an array with multiple items and since there's no way to determine which item is 'primary', at this point it's hardcoded to always pick the first __[0]__ based item in the array.\n\n```powershell\nif ($null -ne $worker.businessCommunication.landLines){\n    $PhoneNumberFixed = $worker.businessCommunication.landLines[0].formattedNumber\n}\n```\n\n__[worker.assignment.reportsTo]__\n\nThe _[worker.assignment.reportsTo]_ array for an assignment contains the information about the manager(s) a worker reports to.\n\nThe array may contain multiple items (managers) for an assignment. There's no way to determine which manager is the 'primary' manager for a particular contract/assignment. At this point it's hardcoded to always pick the first __[0]__ based item in the array.\n\n\u003c!-- PowerShell functions --\u003e\n## PowerShell functions\n\nAll PowerShell functions have comment based help. Both in the sourcecode and within the Github repository. \u003chttps://github.com/Tools4everBV/HelloID-Conn-Prov-Source-ADP-Workforce/tree/main/docs/en-US\u003e\n\n### Sample data\nIf you want to customize the connector according to your own needs, you can use the demo data from ADP.\n\nWorkers: \u003chttps://github.com/marketplace-esi/postman-samples/blob/master/workforce/hr/workers-v2-demographics/success/workers-v2-demographics-al-workers-http-200-response.json\u003e\n\nDepartment: \u003chttps://github.com/marketplace-esi/postman-samples/blob/master/workforce/core/success/core-organization-departments-http-200-response.json\u003e\n\nThe connector configuration supports an import from a JSON file for both persons and departments.\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Setup the PowerShell connector\n1. Make sure you can access the ADP Workforce API's.\n\nObtain the accesstoken:\n\n```powershell\n$authorization = \"$($CientID):$($clientSecretString)\"\n$base64String = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($authorization))\n\n$headers = New-Object \"System.Collections.Generic.Dictionary[[String],[String]]\"\n$headers.Add(\"grant_type\", \"client_credentials\u0026scope=worker-demographics organization-departments\")\n$headers.Add(\"Authorization\", \"Basic $base64String)\n\n$response = Invoke-RestMethod 'https://accounts.dex.adp.com/auth/oauth/v2/token' -Method 'POST' -Headers $headers\n$response | ConvertTo-Json\n$response.access_token\n```\n\nTest access to the ADP Workforce API's, replace the value from _$headers.Add(\"Authorization\", \"Bearer _your_access_token_\")_ with the value from _$response.access_token_.\n\n```powershell\n$headers = New-Object \"System.Collections.Generic.Dictionary[[String],[String]]\"\n$headers.Add(\"Authorization\", \"Bearer _your_access_token_\")\n\n$response = Invoke-RestMethod 'https://api.dex.adp.com/test ' -Method 'GET' -Headers $headers\n$response | ConvertTo-Json\n```\n\n2. Add a new 'Source System' to HelloID and make sure to import all the necessary files.\n\n    - [ ] configuration.json\n    - [ ] mapping.json\n    - [ ] persons.ps1\n    - [ ] departments.ps1\n\n3. Fill in the required fields on the 'Configuration' tab.\n\n---\n\n# HelloID Docs\nThe official HelloID documentation can be found at: https://docs.helloid.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-source-adp-workforce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-source-adp-workforce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftools4everbv%2Fhelloid-conn-prov-source-adp-workforce/lists"}