ICF 1.5.20.33

Workday connector

You can only use Workday connector version 1.5.20.29 and later with:

  • Connector framework 1.5.20.24 or later

  • RCS 1.5.20.24 or later

Learn more in Changed functionality.

Workday is a multi-tenant SaaS application. The Workday connector synchronizes user accounts between IDM and Workday’s cloud-based HR system. The connector integrates with Workday’s Human Resources WSDL, primarily using the Get_Workers operation to read worker data.

The connector supports reading a wide range of worker attributes, including personal, employment, and organizational data. For a complete list of available data, refer to Specific worker data and Specific organizational data. By default, the connector retrieves a minimal attribute set for performance reasons. Use XPath transformations to extract and map additional attributes.

The connector supports:

  • Reconciliation of users and organizations from Workday to an IDM repository.

  • LiveSync of users from Workday to IDM or Advanced Identity Cloud.

  • Limited updates to users in Workday.

To use the connector, you need a Workday instance with the required permissions and a set of credentials, including a username, password, tenant name, and hostname.

Install the Workday connector

To check for an Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Workday

No

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/workday-connector-1.5.20.33.jar /path/to/openidm/connectors/

  • If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the Workday connector

Create a connector configuration using the IDM admin UI:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Workday Connector - 1.5.20.33.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Workday Connector Configuration.

  6. Click Save.

When your connector is configured correctly, the connector displays as Active in the admin UI.

Refer to this procedure to create a connector configuration over REST.

Alternatively, copy the sample configuration file /path/to/openidm/samples/example-configurations/provisioners/provisioner.openicf-workday.json to your project’s conf/ directory, and set enabled to true. Edit the configurationProperties to specify the connection to the Workday instance, for example:

"configurationProperties" : {
    "hostname" : "example.workday.net",
    "tenant" : "example-tenant",
    "username" : "admin",
    "password" : "Passw0rd",
    ...
}

Connection properties

For a list of all configuration properties, refer to Workday Connector Configuration.

Set at least the following properties:

Property Description

hostname

The fully qualified hostname of the Workday instance. The connector uses this value to construct the endpoint URL.

tenant

The Workday tenant name. The connector uses this value to construct the endpoint URL and the complete username in the form username@tenant.

username

The username for the Workday instance. Don’t include the tenant. The connector constructs the full username@tenant value automatically.

password

The password for the Workday instance.

connectionTimeout

The time (in milliseconds) the connector waits to send a request. Requests that exceed this timeout throw an exception.

Default: 60000 (one minute).

receiveTimeout

The time (in milliseconds) the connector waits to receive a response. Because Workday responses can be large, set this value carefully to avoid premature timeouts.

Default: 60000 (one minute).

Data retrieval properties

The configurationProperties also control which data the connector retrieves, using boolean include... and exclude... properties.

Worker types

By default, the connector retrieves all worker types. Use the following properties to exclude specific types:

  • excludeContingentWorkers: Excludes contingent workers. Default: false.

  • excludeEmployees: Excludes regular employees. Default: false.

  • excludeInactiveWorkers: Excludes inactive workers. Default: false.

Specific worker data

The Get_Workers operation returns a large amount of data per worker, organized into sections such as Personal, Employment, Role, and Organization data. For performance reasons, set all of these to false initially, then enable only what you need.

Properties list

  • includeWorkerDocuments

  • includeDevelopmentItems

  • includeRoles

  • includeQualifications

  • includeTransactionLogData

  • includeCareer

  • includeContingentWorkerTaxAuthorityFormInformation

  • includeUserAccount

  • includeFeedbackReceived

  • includeEmployeeContractData

  • includeSkills

  • includeAccountProvisioning

  • includeGoals

  • includeSuccessionProfile

  • includeBackgroundCheckData

  • includeEmployeeReview

  • includeManagementChainData

  • includeOrganizations

  • includePhoto

  • includeRelatedPersons

  • includeBenefitEligibility

  • includeTalentAssessment

  • includeBenefitEnrollments

  • includeCompensation

Specific organizational data

When includeOrganizations is true, you can exclude specific organizational data subsections. By default, all organizational data is included. To exclude a subsection, set its property to true. For performance reasons, set all of these to true initially, then selectively enable only what you need.

Properties list

  • excludeCompanies

  • excludeBusinessUnits

  • excludeCustomOrganizations

  • excludeMatrixOrganizations

  • excludeGiftHierarchies

  • excludeCostCenterHierarchies

  • excludeGrants

  • excludeProgramHierarchies

  • excludeFunds

  • excludeOrganizationSupportRoleData

  • excludeGifts

  • excludeBusinessUnitHierarchies

  • excludeCostCenters

  • excludePrograms

  • excludeSupervisoryOrganizations

  • excludeRegionHierarchies

  • excludeTeams

  • excludeLocationHierarchies

  • excludeRegions

  • excludePayGroups

  • excludeFundHierarchies

  • excludeGrantHierarchies

Date filtering properties

The following optional properties control date filtering for Workday queries.

For a list of all configuration properties, refer to Workday Connector Configuration.
Property Description Accepted values

asOfEffectiveDate

Filters results to include only data that is effective as of a specific date or time. This property sets the Response_Filter/As_Of_Effective_Date element in the Workday request.

A date or duration.

effectiveFrom

Filters transaction log entries to include only those created on or after a specific date. This property sets the Effective_From element in the Workday request.

A date or the string Today.

effectiveThrough

Filters transaction log entries to include only those created on or before a specific date. This property sets the Effective_Through element in the Workday request.

A date or duration.

Date and duration formats

  • Date

  • Duration

An ISO 8601 date-time string, for example:

  • 2026-02-27T00:00:00Z

  • 2026-12-23T08:00:00-07:00

An XML dayTimeDuration string. The connector calculates the effective date as the current date offset by the duration.

  • P5D: Five days from now

  • P1DT12H: One day, 12 hours from now

  • PT2H30M: Two hours, 30 minutes from now

    Use the bare duration string only. Don’t use the full XPath function notation, such as xs:dayTimeDuration('P5D').

XPath transformations

XPath transformations require ICF Framework and RCS version 1.5.20.24 or later and Workday connector version 1.5.20.26 or later.

You can use XPath transformations to simplify and map Workday attributes directly to read-only connector object type properties. The xpathTransformations configuration property is an array of nested object configuration properties and must contain objectType, attribute, and transformation properties.

The XPath transformation implementation uses the javax.xml.xpath package, which supports the XPath 1.0 specification for transformation expressions.

An example XPath transformation:

{
  "xpathTransformations": [
    {
      "objectType": "__ACCOUNT__", (1)
      "attribute": "WORKER_NAME", (2)
      "transformation": "ns1:Worker_Data/ns1:Personal_Data/ns1:Name_Data/ns1:Preferred_Name_Data/ns1:Name_Detail_Data/@ns1:Formatted_Name" (3)
    },
    {
      "objectType": "__ACCOUNT__", (1)
      "attribute": "USER_ID", (2)
      "transformation": "ns1:Worker_Data/ns1:User_ID" (3)
    }
  ]
}
1 The ICF native objectType that the XPath-transformed property belongs to.
2 The target resource name (attribute) in the Workday object type.
3 The XPath transformation applied to extract or flatten the attribute value from Workday.

Extension attributes

The Workday connector can retrieve extension attributes (custom attributes) from Workday. To retrieve extension attributes, use an XPath transformation to map them to a connector object type property. Refer to XPath transformations.

Workday remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Workday connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Workday connector from here.

Refer to Remote connectors for configuring the Workday remote connector.

Configure connection pooling

The Workday connector uses ICF pooling to manage connections. Learn more about the different pooling mechanisms in Connectors by pooling mechanism.

Implementation specifics

For PATCH requests, the Workday connector supports only the replace operation. The connector doesn’t implement add or remove, so every PATCH request replaces the entire attribute value.

Limitations

The Workday connector has the following limitations:

  • It doesn’t support future-dated events.

  • It doesn’t support Workday’s Higher Education extensions (HigherEd).

Test the Workday connector

When the connector is configured, test its status:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/workday?_action=test"
  {
    "name": "workday",
    "enabled": true,
    "config": "config/provisioner.openicf/workday",
    "connectorRef": {
      "bundleVersion": "[1.5.0.0,1.6.0.0)",
      "bundleName": "org.forgerock.openicf.connectors.workday-connector",
      "connectorName": "org.forgerock.openicf.connectors.workday.WorkdayConnector"
    },
    "displayName": "Workday Connector",
    "objectTypes": [
      "employee",
      "__ALL__"
    ],
    "ok": true
  }

A response of "ok": true confirms the connector can reach the Workday instance.

Use the Workday connector

Workers

To retrieve all workers:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/workday/employee?_queryId=query-all-ids"
{
  "result": [
    {
      "_id": "3aa5550b7fe348b98d7b5741afc65534",
      "employeeID": "21001"
    },
    {
      "_id": "0e44c92412d34b01ace61e80a47aaf6d",
      "employeeID": "21002"
    },
    {
      "_id": "3895af7993ff4c509cbea2e1817172e0",
      "employeeID": "21003"
    },
    ...
  ]
}

On the first retrieval, the following warning might appear in the console. You can safely ignore it:

WARNING: Default key managers cannot be initialized: Invalid keystore format
java.io.IOException: Invalid keystore format

To retrieve a specific worker, include the user’s ID in the URL. For example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/workday/employee/3aa5550b7fe348b98d7b5741afc65534"

Reconcile users from Workday to IDM

To reconcile users from Workday to IDM or Advanced Identity Cloud, set up a mapping between Workday and IDM managed users or Advanced Identity Cloud identities.

When you have created a mapping, run reconciliation using the admin UI or with a REST call similar to the following:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemWorkdayEmployee_managedUser&waitForCompletion=true"
{
  "_id": "db2bc7f4-e9a8-4315-9dd1-e2cdcd85ae6e-33099",
  "state": "SUCCESS"
}

Update users in the Workday system

The connector supports updates to system users only for the following properties:

  • Account credentials (username and password)

  • email

  • mobile (telephone number)

The following command updates a user’s mobile number:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "replace",
    "field": "mobile",
    "value": "+1 (415) 859-4366"
  }
]' \
"http://localhost:8080/openidm/system/workday/employee/3aa5550b7fe348b98d7b5741afc65534"

OpenICF Interfaces Implemented by the Workday Connector

The Workday Connector implements the following OpenICF interfaces. For additional details, see ICF interfaces:

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector.

Any script that runs on the connector has the following characteristics:

  • The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.

  • The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.

  • The script has access to any script arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

Test

Tests the connector configuration.

Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

Workday Connector Configuration

The Workday Connector has the following configurable properties:

Worker Response Configuration Properties

Property Type Default Encrypted(1) Required(2)

includeManagementChainDataForWorkers

Boolean

true

No

Indicates if the Management Chain Data element is included in the response.

includeOrganizationsForWorkers

Boolean

true

No

Indicates if the Organization Data element is included in the response.

includePersonalInformationForWorkers

Boolean

true

No

Indicates if the Personal Data element is included in the response.

excludeCostCentersForWorkers

Boolean

false

No

Excludes the cost centers from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

excludeCustomOrganizationsForWorkers

Boolean

true

No

Excludes the custom organizations from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

includeRolesForWorkers

Boolean

false

No

Indicates if the Role Data element is included in the response.

excludeMatrixOrganizationsForWorkers

Boolean

true

No

Excludes the matrix organizations from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

includeEmploymentInformationForWorkers

Boolean

true

No

Indicates if the Employment Data element is included in the response.

includeAccountProvisioningForWorkers

Boolean

false

No

Indicates that Account Provisioning Data will be included in the web service response.

excludeBusinessUnitHierarchiesForWorkers

Boolean

true

No

Excludes the business unit hierarchies from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

includeRelatedPersonsForWorkers

Boolean

false

No

Indicates if the Related Person Data element is included in the response.

includePhotoForWorkers

Boolean

false

No

Indicates if the Photo Data element is included in the response.

excludeSupervisoryOrganizationsForWorkers

Boolean

true

No

Excludes the supervisory organizations from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

excludeTeamsForWorkers

Boolean

false

No

Excludes the teams from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

includeTransactionLogDataForWorkers

Boolean

true

No

Indicates if the Transaction Log Data element is included in the response.

excludeCompaniesForWorkers

Boolean

false

No

Excludes the company organizations from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

excludeBusinessUnitsForWorkers

Boolean

false

No

Excludes the Business Units from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

includeEmployeeContractDataForWorkers

Boolean

false

No

Indicates if the Employee Contract element is included in the response.

includeUserAccountForWorkers

Boolean

true

No

Indicates that User Account Data will be included in the web service response.

excludeRegionsForWorkers

Boolean

false

No

Excludes the regions from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected.

includeMultipleManagersInManagementChainDataForWorkers

Boolean

false

No

If set to true, multiple managers in the management chain data are returned.

includeAdditionalJobsForWorkers

Boolean

false

No

If true, the data for Additional Jobs and International Assignments is included in the response.

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.

Organization Response Configuration Properties

Property Type Default Encrypted(1) Required(2)

includeStaffingRestrictionsDataForOrganizations

Boolean

false

No

Indicates whether the Staffing Restrictions Data element is included in the response.

includeSupervisoryDataForOrganizations

Boolean

false

No

Indicates whether the Supervisory Data element is included in the response.

includeHierarchyDataForOrganizations

Boolean

false

No

Indicates whether the Hierarchy Data element is included in the response.

includeRolesDataForOrganizations

Boolean

false

No

Indicates whether the Roles Data element is included in the response.

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.

Basic Configuration Properties

Property Type Default Encrypted(1) Required(2)

hostname

String

null

Yes

The hostname for the Workday service. Example: https://[workday hostname]/ccx/service/[workday tenant]/. You need to configure the bracketed Workday hostname and tenant name to successfully connect to the proper instance.

xpathTransformations

Map[]

[]

No

List of xpath transformations to connector attributes (Supported by framework versions greater than 1.5.20.23).

tenant

String

null

Yes

The tenant in URL for the Workday service. For example: https://[workday hostname]/ccx/service/[workday tenant]/. You need to configure the bracketed Workday hostname and tenant name to successfully connect to the proper instance.

username

String

null

Yes

The username for logging into the Workday service. It will be concatenated with the tenant name (user@tenant)

password

GuardedString

null

Yes

Yes

The user password for logging into the Workday service

excludeInactiveWorkers

boolean

false

No

Excludes terminated employees or contingent workers whose contracts have ended from the query response.

excludeContingentWorkers

boolean

false

No

Excludes contingent workers from the query response.

excludeEmployees

boolean

false

No

Excludes employees from the query response.

connectionTimeout

int

30

No

Specifies the amount of time, in seconds, that the client will attempt to establish a connection before it times out. Set to 0 for no timeout.

receiveTimeout

int

60

No

Specifies the amount of time, in seconds, that the client will wait for a response before it times out. Set to 0 for no timeout.

pageSize

long

100

No

Sets the page size used for search operations.

proxyHost

String

null

No

If defined, the connection to Workday goes through this HTTP proxy server.

proxyPort

int

8080

No

The HTTP proxy server port number.

xslTransformer

File

null

No

The file path to the XSL File to get the custom attributes.

asOfEffectiveDate

String

null

No

Optional configuration of Response_Filter/As_Of_Effective_Date element. Valid values are: Date (http://www.w3.org/TR/xpath-functions/#date-time-values http://www.w3.org/TR/xmlschema-2/#dateTime-order) or Duration (http://www.w3.org/TR/xpath-functions/#dt-dayTimeDuration). If set to Duration, the effective date is calculated as current date + duration.

effectiveFrom

String

null

No

Sets the Get_Workers_Request/Request_Criteria/Transaction_Log_Criteria_Data/Transaction_Date_Range_Data/Effective_From for every outbound query request. Valid value could be Date (http://www.w3.org/TR/xpath-functions/#date-time-values http://www.w3.org/TR/xmlschema-2/#dateTime-order) or string Today representing the current time of the request.

effectiveThrough

String

null

No

Sets the Get_Workers_Request/Request_Criteria/Transaction_Log_Criteria_Data/Transaction_Date_Range_Data/Effective_Through for every outbound query request. Valid value could be Date (http://www.w3.org/TR/xpath-functions/#date-time-values http://www.w3.org/TR/xmlschema-2/#dateTime-order) or Duration (http://www.w3.org/TR/xpath-functions/#dt-dayTimeDuration).

externalFieldAndParameterCriteria

String[]

[]

No

A list of external fields to add to the search/query criteria.

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.