> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/connector-configuration/adp.md).

# ADP connector

This page describes how to enable provisioning to manage ADP HR system users.

The ADP connector is used to connect to **ADP** human resources information systems (HRIS). It integrates OpenIAM with ADP to synchronize users and their status, authenticating with OAuth2 client credentials and a client SSL certificate.

| Operation                                             | Supported                                                                   |
| ----------------------------------------------------- | --------------------------------------------------------------------------- |
| Search / synchronize users                            | ✅                                                                           |
| Test connection                                       | ✅                                                                           |
| Create/update, delete, suspend/resume, reset password | ❌ Not supported — ADP is the authoritative HR source; OpenIAM reads from it |
| Group provisioning                                    | ❌ Not supported                                                             |

## Use cases

* Using **ADP as the authoritative HR source**: importing workers into OpenIAM to drive the joiner/mover/leaver lifecycle downstream.
* Keeping user **status** in OpenIAM aligned with ADP (active, leave, terminated).
* **Not** a provisioning target — OpenIAM does not write to ADP.

## Versions and compatibility

The end application is **ADP**, reached through ADP's own Marketplace connection library rather than by building REST calls directly. Authentication is OAuth 2.0 against ADP's token endpoint, and worker data comes from the ADP **HR API v2**.

<table><thead><tr><th width="222">Property</th><th>Value</th></tr></thead><tbody><tr><td><strong>Platform</strong></td><td>ADP</td></tr><tr><td><strong>Interface</strong></td><td>ADP Marketplace Java library over HTTPS</td></tr><tr><td><strong>Authentication</strong></td><td>OAuth 2.0, <code>/auth/oauth/v2/token</code>, with a client certificate</td></tr><tr><td><strong>Workers</strong></td><td><code>/hr/v2/workers</code></td></tr></tbody></table>

{% hint style="info" %}
ADP requires mutual TLS: the integration is identified by a client certificate that ADP issues for your account, not by a password alone. Obtain it before configuring the managed system.
{% endhint %}

## Prerequisites

* An ADP API integration: **Client ID** and **Client Secret** from the ADP side (see the [ADP documentation center](https://developers.adp.com/)).
* The **SSL certificate** generated by your ADP administrator for API access, placed on the server where the ADP connector runs, together with its key and store passwords.
* Network access from the connector host to your ADP instance (HTTPS).

## Installing the connector

### Kubernetes

In Kubernetes deployments, the connector is deployed as part of OpenIAM — enable it in your deployment configuration; no separate installation is required.

### RPM

Run the connector JAR directly, or use the connector service unit (`openiam-connector@adp-connector-rabbitmq`). To deploy on a separate host, see [Connectors via RPM](/installation/rpm/rpm-single-node/add-a-connector.md).

## Starting, stopping, and restarting

<table><thead><tr><th width="209">Deployment</th><th>Commands</th></tr></thead><tbody><tr><td>RPM (systemd)</td><td><code>systemctl start|stop|restart openiam-connector@adp-connector-rabbitmq</code></td></tr><tr><td>Kubernetes</td><td><code>kubectl rollout restart</code> the connector deployment.</td></tr></tbody></table>

## Command-line parameters and properties

The connector is a Spring Boot application. Its defaults ship inside the jar, and you override them in either of two places:

* **An external property file**, read at `${confpath}/conf/properties/adp-connector-rabbitmq.properties`. The file is optional, and `confpath` is itself a system property, set with `-Dconfpath=/data/openiam/`.
* **Directly on the command line**, as `-D` arguments, which win over the file.

{% code overflow="wrap" %}

```bash
java -Dconfpath=/data/openiam/ -Dlogging.level.root=INFO -Dorg.openiam.connector.queue=ADP_Connector_1_Request -jar adp-connector-rabbitmq.jar
```

{% endcode %}

<table><thead><tr><th width="320">Property</th><th>Default</th></tr></thead><tbody><tr><td><code>org.openiam.connector.queue</code></td><td><code>ADP_Connector_1_Request</code></td></tr><tr><td><code>org.openiam.connector.name</code></td><td><code>ADP</code></td></tr></tbody></table>

<table><thead><tr><th width="269">Property</th><th width="136">Default</th><th>Purpose</th></tr></thead><tbody><tr><td><code>org.openiam.adp.date.format</code></td><td><code>yyyy-MM-dd</code></td><td>Date format used when reading and writing ADP worker records</td></tr></tbody></table>

The connection details themselves are **not** set here — they are managed system parameters, covered under [Configuring the managed system](#configuring-the-managed-system).

## Verifying the connector is running

{% stepper %}
{% step %}
In the Webconsole, open the managed system — the **Running connector status** indicator must be green.
{% endstep %}

{% step %}
Click **Test Connection** — it must return success.
{% endstep %}

{% step %}
In the RabbitMQ management console, confirm the `ADP_Connector_1_Request` queue exists and has a consumer.
{% endstep %}

{% step %}
Check the connector log for startup errors.
{% endstep %}
{% endstepper %}

## Troubleshooting

<table><thead><tr><th width="232">Symptom</th><th width="264">Likely cause</th><th>Resolution</th></tr></thead><tbody><tr><td>Test connection fails</td><td>Wrong token endpoint, Client ID/Secret, or certificate settings</td><td>Re-verify each managed-system field; confirm the SSL cert path is valid <strong>on the connector host</strong> and the key/store passwords match.</td></tr><tr><td>Connection drops periodically</td><td>Token expiry handling</td><td>Expected behavior — the connector re-requests the token near expiry; investigate only if syncs actually fail.</td></tr><tr><td>Sync returns no users</td><td>Query filter too narrow or malformed</td><td>Start with <code>*</code>, then add status filters incrementally.</td></tr><tr><td>Attempts to provision to ADP do nothing</td><td>ADP is a read-only source</td><td>Expected — see the operations table above.</td></tr><tr><td>A provisioning request to ADP reports success</td><td>Every write operation is a stub</td><td>Create, update, delete, suspend, resume, password reset and group create/delete each return <code>SUCCESS</code> without calling ADP. OpenIAM records the operation as done; ADP is unchanged. Read from ADP and write elsewhere.</td></tr></tbody></table>

See also: [general connector troubleshooting](/connector-configuration/4-troubleshootingconnector.md) and the [connector error-code reference](/connector-configuration/4-troubleshootingconnector.md#connector-error-codes).

## Registering the connector in OpenIAM

The connector ships pre-registered; if you register it manually under **Provisioning → Connectors**, the queue name must match exactly:

## Configuring the managed system

OpenIAM ships a default managed system called **ADP Managed System**. Log in to the Webconsole, go to **Provisioning → Managed system**, find it, and click **Edit**. Key fields:

<table><thead><tr><th width="190">Field</th><th>Description</th></tr></thead><tbody><tr><td>Token endpoint</td><td>The URL of the ADP instance. OpenIAM hits different endpoints against it: <strong>TOKEN</strong> (<code>POST /auth/oauth/v2/token</code>), <strong>USERS</strong> (<code>GET /hr/v2/workers</code>), single <strong>USER</strong> (<code>GET /hr/v2/workers%s</code>).</td></tr><tr><td>Client ID</td><td>Copied from the ADP HRIS system (see the <a href="https://developers.adp.com/">ADP documentation center</a>).</td></tr><tr><td>Client Secret</td><td>Copied from the ADP HRIS system.</td></tr><tr><td>SSL cert</td><td>Path to the SSL certificate. It must be on the same server where the ADP connector runs.</td></tr><tr><td>Key password</td><td>Provided when the ADP administrator generates the SSL certificate.</td></tr><tr><td>Store password</td><td>Provided when the ADP administrator generates the SSL certificate.</td></tr></tbody></table>

Click **Save**.

### Token lifecycle

OpenIAM requests an **authorization token** from ADP. The token has its own lifecycle; when it expires, OpenIAM requests a new one. Because OpenIAM's IDM service tests the connection every minute, the connector treats the connection as live until the token is close to expiry (for example, with a 30-minute token, a new one is requested around minute 29) — this avoids overloading the ADP service.

## Attribute mapping and policy map

No outbound policy map is needed (the connector is read-only). Inbound mapping is done by the synchronization **transformation script**, which can transform all the user data stored in the HR system — names, phone numbers, emails, addresses, employment data, and user status. The fields the connector can fetch:

{% code overflow="wrap" expandable="true" %}

```
"associateOID"
"workerId"
"firstName"
"middleName"
"lastName"
"displayName"
"email"
"mobile"
"mobileCountryCode"
"mobileAreaCode"
"mobilePhoneNumber"
"mobileIsForNotification"
"mobileExtension"
"telephone"
"telephoneCountryCode"
"telephoneAreaCode"
"telephonePhoneNumber"
"telephoneIsForNotification"
"telephoneExtension"
"fax"
"faxCountryCode"
"faxAreaCode"
"faxPhoneNumber"
"faxIsForNotification"
"faxExtension"
"organization"
"department"
"supervisor"
"payrollGroupCode"
"payrollFileNumber"
"link"
"title"
"status"
"startDate"
"lastDate"
"legalAddress"
"legalStreetAddress1"
"legalStreetAddress2"
"legalStreetAddress3"
"legalStreetAddress4"
"legalStreetAddress5"
"legalCity"
"legalPostalCode"
"legalState"
"legalCountryCode"
"gender"
"assignmentStatus"
"assignmentTermCode"
"workLevelCode"
"managementPositionIndicator"
"wageLawCoverage"
"assignedWorkLocations"
"remunerationBasisCode"
"payCycleCode"
"baseRemuneration"
"baseRemunerationAmount"
"baseRemunerationCurrency"
"maritalStatusCode"
"otherPersonalAddresses"
"otherPersonalStreetAddress1"
"otherPersonalStreetAddress2"
"otherPersonalStreetAddress3"
"otherPersonalStreetAddress4"
"otherPersonalStreetAddress5"
"otherPersonalCity"
"otherPersonalPostalCode"
"otherPersonalState"
"otherPersonalCountryCode"
"personalEmail"
"personalLandLines"
"personalLandLinesCountryCode"
"personalLandLinesAreaCode"
"personalLandLinesPhoneNumber"
"personalLandLinesIsForNotification"
"personalLandLinesExtension"
"personalMobile"
"personalMobileCountryCode"
"personalMobileAreaCode"
"personalMobilePhoneNumber"
"personalMobileIsForNotification"
"personalMobileExtension"
```

{% endcode %}

## Reconciliation and synchronization

Synchronization is the connector's purpose. OpenIAM ships a default configuration named **ADP User Example**:

{% stepper %}
{% step %}
Log in to the Webconsole and go to **Provisioning → Synchronization**.
{% endstep %}

{% step %}
Find the `ADP User Example` configuration and click **Edit**. The fields are pre-filled to synchronize Employee ID and Worker ID, with a pre-selected transformation script.
{% endstep %}

{% step %}
Set the search query:

* `*` — all users.
* `*statuses: ACTIVE, LEAVE`, etc. — filter by status; the ADP status filter `("workers/workerStatus/statusCode/codeValue eq '%s'")` is applied.
* A query starting with `/` searches a single user (the `/hr/v2/workers%s` filter is applied).
* Combine criteria with `&`.
  {% endstep %}
  {% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/connector-configuration/adp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.