Workday

Integration Guide

Overview

Data Bridge connects to Workday Financial Management through two parallel stacks:

  • Entity sync (primary): Workday Web Services (WWS) SOAP Revenue_Management and Human_Resources v46.2, authenticated with a WS-Security UsernameToken
  • PDF sync only: customerAccounts v1 REST, authenticated with the OAuth 2.0 JWT Bearer Grant

The Workday WWS WSDLs offer no SOAP equivalent for the system-generated invoice PDF. The Attachments_Data element on SOAP holds manual invoice attachments, which differ from the printed invoice layout.

The Workday integration has these characteristics:

  • ERP type: workday
  • Entity API: SOAP WWS (not REST) for customers, invoices, workers, contracts, contacts and notes
  • Naming: Workday SOAP vocabulary with PascalCase_With_Underscores field names (Customer_ID, Invoice_Number, Amount_Due) and camelCase entity set names (customers, invoices, invoiceLines)
  • Primary key: scalar top-level id, which is a real Workday ID (WID) for most entities and synthesized for customerNotes
  • References: arrays of extracted maps { WID, …namedIds } in every *_Reference field, even when the field holds one entry
  • Entity authentication: Integration System User (ISU) username and password as a WS-Security UsernameToken ({isuUsername}@{tenant})
  • PDF authentication: optional clientId and RSA privateKey for a JWT bearer grant that returns a REST token
  • PDF-capable entity:invoices only (supportsPdfSync = true)

NOTE: Use the SOAP field names in this guide. Pre-migration REST field names (totalAmount, dueAmount, paymentStatus as nested objects and camelCase REST shapes) can still appear on old merge-updated MongoDB documents. The current SOAP sync never produces them.

Setup and credentials

Required fields

Enter these fields for every Workday connection.

Field Description
ERP Type workday
API Base URL REST API gateway base URL without the product, version or tenant, for example https://impl-services1.wd12.myworkday.com/ccx/api. Data Bridge also uses this host to derive SOAP endpoints
Tenant Workday tenant alias, for example billtrust_dpt2
Integration System User Exact Workday username of the ISU. Serves as the JWT sub (REST and PDF) and the UsernameToken user (SOAP)
Password ISU password. Serves as the UsernameToken PasswordText for all SOAP entity sync

Optional fields for PDF sync

Enter these fields only if you use PDF sync.

Field Description
Client ID Workday API Client ID (Client Grant Type: Jwt Bearer Grant)
Private Key (PEM) RSA private key that signs the JWT assertion (RS256). Upload the matching public certificate to the API Client's x509 field

Entity sync works without Client ID and Private Key. PDF sync does not run, or fails authentication, when you omit them.

Authentication flows

Data Bridge handles each stack as follows.

SOAP (entity sync)

  • Data Bridge sends a WS-Security UsernameToken with each request.
  • The username format is {isuUsername}@{tenant}.
  • SOAP requires no token endpoint or JWT.
  • Data Bridge derives SOAP base URLs from apiBaseUrl. For confirmed classic hosting, …/ccx/api becomes …/ccx/service/{tenant}/{Service}/v46.2.
  • The connector uses Revenue_Management/v46.2 and Human_Resources/v46.2.
  • If apiBaseUrl does not end in /ccx/api, derivation returns an error. Newer hosting shapes are not yet confirmed for SOAP.

REST JWT (PDF only)

  • Data Bridge signs a JWT (iss=clientId, sub=isuUsername, aud=token endpoint) with the private key.
  • Data Bridge exchanges the JWT at the token endpoint. It derives the endpoint by swapping the trailing /api for /oauth2: …/ccx/oauth2/{tenant}/token.
  • The customerAccounts base is {apiBaseUrl}/customerAccounts/v1/{tenant}.

NOTE: Get the exact apiBaseUrl from the tenant's API Client or API Explorer screen. Classic hosts use a /ccx/ prefix. Some newer cloud gateways omit it for REST. SOAP derivation currently requires the /ccx/api shape.

Setting up Workday

Complete these steps in Workday.

  1. Create an Integration System User with password authentication enabled.
  2. Grant the security domains and groups for these operations:
    • Get_Customers, Get_Customer_Invoices, Get_Customer_Contracts and Get_Business_Entity_Contacts (Revenue Management)
    • Get_Workers (Human Resources)
  3. For PDF sync, create an API Client with the grant type Jwt Bearer Grant. Upload the public certificate, add the customerAccounts scopes and map the ISU.
  4. Allow Data Bridge egress to the Workday hosts.

What Data Bridge accesses

Data Bridge calls these operations and endpoints.

Operation or endpoint Stack Purpose
Get_Customers SOAP Customer master plus embedded Note_Data (forked to customerNotes)
Get_Customer_Invoices SOAP Invoice headers plus embedded line data (forked to invoiceLines)
Get_Workers SOAP Employee and representative roster
Get_Customer_Contracts SOAP Rep-debtor link through the salesperson on the contract
Get_Business_Entity_Contacts SOAP Contacts (client-filtered to customer-side only)
GET …/invoices/{id}/printRuns → GET …/invoicePDFs/{pdf.id} REST Generated invoice PDF binary
NOTE   

All access is read-only.