ADP Workforce Now Connector Setup

Overview

The ADP Workforce Now connector is a source connector that extracts the full HR surface from ADP Workforce Now into VersionForge's staging layer. It supports five object types, all pulled as separate record streams:

| Object type | ADP endpoint | Primary key | |-------------|-------------|-------------| | worker | GET /hr/v2/workers | associateOID | | organization | GET /core/v1/organization-departments | departmentCode | | assignment | GET /hr/v2/workers/{aoid}/work-assignments | itemID | | compensation | GET /payroll/v1/workers/{aoid}/base-remuneration | {aoid}:{itemID}:{effectiveDate} | | position | GET /core/v1/positions | positionID |

This connector is the first in VersionForge to use mutual TLS — the client authenticates every request with a certificate and key issued by ADP, on top of OAuth 2 client credentials.

Prerequisites

• ADP Workforce Now tenant with administrator access to the ADP Developer Portal or Marketplace API registration.
• Ability to generate an API client with read scopes for Worker, Organization, Work Assignment, Base Remuneration, and Position data.
• Access to the one-time download of the ADP-issued SSL certificate (.pem) and private key (.key).

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | apiBaseUrl | Yes | Data-plane base URL. https://api.adp.com for US production. Regional tenants may differ. | | clientId | Yes | Client ID from the ADP Developer Portal API client record. | | clientSecret | Yes | Client Secret from the ADP Developer Portal API client record. | | clientCert | Yes | ADP-issued SSL certificate, full PEM contents including -----BEGIN CERTIFICATE----- markers. | | clientKey | Yes | ADP-issued private key, full PEM contents including -----BEGIN PRIVATE KEY----- markers. |

The three secrets (clientSecret, clientCert, clientKey) are AES-256-GCM encrypted at rest. The two non-secret fields (apiBaseUrl, clientId) are stored in credential metadata.

Setup Steps

1. Register the API client in ADP

   In the ADP Developer Portal (or the ADP Marketplace partner registration flow if you're a Partner), create a new API client for your tenant.

   Grant the client read scope for the following product families:

   • Human Resources — Worker, Work Assignment
   • Core HR — Organization, Position
   • Payroll — Base Remuneration (read-only)

   Save the Client ID and Client Secret — you'll paste them into VersionForge in Step 3.

2. Generate the mTLS certificate

   ADP issues a tenant-specific SSL certificate and private key that every API call must present. In the API client configuration screen, click Generate SSL Certificate (or the equivalent in your ADP environment).

   Download both files:

   • your-tenant-cert.pem — the SSL certificate
   • your-tenant-key.key — the matching private key

   Store them securely. ADP does not retain the private key — if you lose it you must regenerate the pair and re-upload to VersionForge.

   Certificates typically have a 1-year lifetime. VersionForge's credential-check monitor warns you when the expiry is under 30 days.

3. Enter credentials in VersionForge

   Go to Dashboard → Connections → New Connection, pick ADP Workforce Now, and work through the 3-step wizard:

   1. Review the API-client registration steps.
   2. Review the certificate generation steps.
   3. Paste your apiBaseUrl, clientId, clientSecret, and the full contents of your .pem and .key files (including the BEGIN/END markers) into the form.

   VersionForge validates the PEM material before saving — if the certificate and key don't match each other, you'll see an immediate error so you can confirm you uploaded the pair issued together.

4. Verify connectivity

   After saving, VersionForge automatically runs a health check:

   1. Opens an mTLS connection to the OAuth 2 token endpoint (https://accounts.adp.com/auth/oauth/v2/token).
   2. Requests a client-credentials access token.
   3. Probes GET /core/v1/application-instance to confirm the token + scope.

   A green checkmark means the connection is live. If the probe fails, the Connections page shows the specific error — typically one of:

   • TLS handshake failure — cert or key is corrupted, or the pair doesn't match.
   • HTTP 401 on /token — Client ID or Secret is wrong.
   • HTTP 403 on /application-instance — the API client doesn't have the required scopes.
   • Certificate expired — regenerate the pair in ADP and re-upload.

Rate Limiting & Pagination

• All endpoints use ADP's $skip / $top pagination. The connector walks pages until a short page is returned.
• Worker-loop entities (assignment, compensation) pull the worker list once and fan out with bounded concurrency — default 5, configurable up to 10.
• 429 Too Many Requests responses are retried with jittered exponential backoff (3 retries), honouring Retry-After when present.
• Data-plane timeouts are 30 seconds per request; token calls time out after 15 seconds.

Content Hashing & Change Detection

Each emitted record carries a canonical SHA-256 contentHash over its flattened field set, deep-sorted for stability. Re-running the same extract against an unchanged ADP payload produces identical hashes, so downstream diffs only show real changes.

sourceUpdatedAt is populated from:

• workerStatus.statusEffectiveDate (worker)
• effectiveDate (organization, position, compensation)
• assignmentStatus.effectiveDate (assignment)

What's Not Covered (v1)

• Incremental cursor support — v1 does a full snapshot per run. ?modifiedSince= support requires live tenant validation and is tracked separately.
• ADP Vantage and ADP Run variants — different auth mechanics; follow-on connector.
• Bonuses, equity, and pay statements — the v1 compensation object covers base remuneration only.
• Multi-currency compensation normalization in the Adaptive push — the connector emits native currency codes as-is; downstream transforms handle normalization.
• Field-granular PII masking — all fields pass through; gate sensitive fields via override suppression if needed.

Next Steps

• Create a Sync Profile pairing ADP Workforce Now as the source with your EPM target (Adaptive Planning or Pigment).
• Use Field Mapping to map the flattened ADP payload into your target's column structure. The five object types appear as separate mapping tabs.
• For workforce-planning use cases, map organization and position first — they're the dimension-carriers that Adaptive's auto-create path depends on.