| The latest version of this connector requires no longer contains Custom.AssociateOID in the mapping. As this is a required field for most configuration, please add and mapp this field manually. |
| ℹ️ 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. |
| Version | Description | Date |
|---|---|---|
| 2.1.2 | Update readme, added opton for cloud agent | 13/12/2023 |
| 2.1.1 | Update readme | 08/09/2023 |
| 2.1.0 | Added support for cloud by using base64 pfx string | 06/09/2023 |
| 2.0.1 | release of v2 | 13/07/2023 |
| 1.1.0 | Performance updates and added support for custom fields | 05/05/2022 |
| 1.0.0 | Initial release | 28/02/2022 |
- The 'Execute on-premises' switch on the 'System' tab is toggled if using the certificate file
- Windows PowerShell 5.1 installed on the server where the 'HelloID agent and provisioning agent' are running if using the certificate file
- The public key *.pfx certificate belonging to the X.509 certificate that's used to activate the required API's.
- The password for the public key *.pfx certificate.
- HelloID-Conn-Prov-Source-ADP-Workforce
- HelloID Docs
ADP 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. Note 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.
| API | Description |
|---|---|
| Worker-Demographics | Contains the employees personal and contract data |
| Organization-Departments | Contains data about the organisation structure |
The 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.
PowerShell 7.0.3 Core is supported when using the option "Base64 string of certificate".
To get access to the ADP Workforce API's, a x.509 certificate is needed. Please follow the steps below to provide this.
- The customer creates a CSR and sends this to ADP. Please follow the ADP documentation to create the Certificate Signing Request
- ADP will create the X.509 certificaat, client_id and client_secret and will send these to the customer.
- The customer sends the X.509 certificaat, client_id and client_secret to Tools4ever (or any other implementer).
Note: Each ADP environment requires its own certificate. If there is an Accept and a Production environment, 2 certificates are required.
APD will register an application that's allowed to access the specified API's. worker-demographics and organizational_departments. Other API's within the ADP Workforce environment cannot be accessed.
Here's an improved version of the README text:
There are two methods available for importing the *.pfx file:
This 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.
Option 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.
-
Execute the following code to copy the base64 string of your *.pfx file to your clipboard:
[System.Convert]::ToBase64String((Get-Content "C:\*.pfx" -Encoding Byte)) | Set-Clipboard
-
Leave the configuration of "Certificate Path" empty.
-
If deploying on a cloud agent, replace the following code (approximately at line 281 and 282 in the person script and 260 and 261 in the department script):
$datasetCorrected = [Text.Encoding]::UTF8.GetString([Text.Encoding]::GetEncoding(28591).GetBytes($datasetJson.content)) $dataset = $datasetCorrected | ConvertFrom-Json
With:
$dataset = $datasetJson.content | ConvertFrom-Json
This updated version clarifies the options, provides clearer instructions for using Option 2, and includes formatting for better readability.
In 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.
Tokens 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
Paging is only supported by ADP for the 'worker-demographics' endpoint. Paging is implemented in the connector for the 'worker-demographics' endpoint.
If a worker has multiple assignments, each assigment will be imported in HelloID.
Both the worker and assigment(s) may contain custom fields. Custom fields will be automatically imported in HelloID.
Custom fields can be selected in both the person and contract mapping.
A basic person and contract mapping is provided. Make sure to further customize these accordingly.
[worker.businessCommunication]
The [worker.businessCommunication] array contains information about the:
- Fixed Phone Number
- Mobile Phone Number
- Email Address
All three are array's. Implying that they may contain multiple items.
Since the demo data doesn't have array's 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.
if ($null -ne $worker.businessCommunication.landLines){
$PhoneNumberFixed = $worker.businessCommunication.landLines[0].formattedNumber
}[worker.assignment.reportsTo]
The [worker.assignment.reportsTo] array for an assignment contains the information about the manager(s) a worker reports to.
The 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.
All PowerShell functions have comment based help. Both in the sourcecode and within the Github repository. https://github.com/Tools4everBV/HelloID-Conn-Prov-Source-ADP-Workforce/tree/main/docs/en-US
If you want to customize the connector according to your own needs, you can use the demo data from ADP.
The connector configuration supports an import from a JSON file for both persons and departments.
- Make sure you can access the ADP Workforce API's.
Obtain the accesstoken:
$authorization = "$($CientID):$($clientSecretString)"
$base64String = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($authorization))
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("grant_type", "client_credentials&scope=worker-demographics organization-departments")
$headers.Add("Authorization", "Basic $base64String)
$response = Invoke-RestMethod 'https://accounts.dex.adp.com/auth/oauth/v2/token' -Method 'POST' -Headers $headers
$response | ConvertTo-Json
$response.access_tokenTest 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.
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Bearer _your_access_token_")
$response = Invoke-RestMethod 'https://api.dex.adp.com/test ' -Method 'GET' -Headers $headers
$response | ConvertTo-Json-
Add a new 'Source System' to HelloID and make sure to import all the necessary files.
- configuration.json
- mapping.json
- persons.ps1
- departments.ps1
-
Fill in the required fields on the 'Configuration' tab.
The official HelloID documentation can be found at: https://docs.helloid.com/