Workday connector
Workday is a multi-tenant Software-as-a-Service (SaaS) application. The Workday connector lets you synchronize user accounts between IDM and Workday’s cloud-based HR system.
The connector supports reconciliation of users and organizations from Workday to an IDM repository, liveSync of users from Workday to IDM, and updating users in a Workday system.
To use the connector, you need a Workday instance with the required permissions and a set of credentials to access the instance, including the username, password, tenant name, and host name.
Install the Workday connector
If you are looking for the 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 | IDM | RCS |
---|---|---|
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.26.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:
-
From the navigation bar, click Configure > Connectors.
-
On the Connectors page, click New Connector.
-
On the New Connector page, type a Connector Name.
-
From the Connector Type drop-down list, select Workday Connector - 1.5.20.26.
-
Complete the Base Connector Details.
For a list of all configuration properties, refer to Workday Connector Configuration -
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",
...
}
Set at least the following properties:
hostname
-
The fully qualified name of the Workday instance. The connector uses the
hostname
to construct the endpoint URL. tenant
-
The tenant to which you are connecting. The connector uses the
tenant
name to construct the endpoint URL, and the complete username (in the formusername@tenant
). username
-
The
username
used to log in to the Workday instance. Do not specify the complete username including thetenant
. The connector constructs the complete username. password
-
The
password
used to log in to the Workday instance. connectionTimeout
-
The timeout (in milliseconds) that the connector should wait for a request to be sent to the Workday instance. The default timeout is 60000ms or one minute. Requests that take longer than a minute throw an exception.
receiveTimeout
-
The timeout (in milliseconds) that the connector waits to receive a response. The default timeout is 60000ms or one minute. Because the Workday can be slow, and the amount of information returned can be very large, you should set this parameter carefully to avoid unnecessary timeouts.
Check that the connector is retrieving the exact data that you need.
The configurationProperties
also specify the data that the connector should retrieve with a number of boolean include...
and exclude...
properties. These properties can be divided as follows:
- Worker types
-
By default, all worker types are retrieved. Use any the following settings to exclude specific worker types:
-
excludeContingentWorkers
- exclude contingent workers from query results,false
by default. -
excludeEmployees
- exclude regular employees from query results,false
by default. -
excludeInactiveWorkers
- exclude inactive workers from query results,false
by default.
-
- Specific worker data
-
These parameters specify the properties to return for every included worker type. For performance reasons, set all of these to false initially, and then include only the necessary properties.
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
-
Included in the data of each worker is the organization to which the user belongs. If you have set
includeOrganizations
totrue
, you can specify the organizational data that should be excluded from the query response. By default, all organizational data is included. To exclude data from a response, set its corresponding property totrue
. For performance reasons, set all of these totrue
initially, and then include only the necessary properties.Properties List
-
excludeCompanies
-
excludeBusinessUnits
-
excludeCustomOrganizations
-
excludeMatrixOrganizations
-
excludeGiftHierarchies
-
excludeCostCenterHierarchies
-
excludeGrants
-
excludeProgramHierarchies
-
excludeFunds
-
excludeOrganizationSupportRoleData
-
excludeGifts
-
excludeBusinessUnitHierarchies
-
excludeCostCenters
-
excludePrograms
-
excludeSupervisoryOrganizations
-
excludeRegionHierarchies
-
excludeTeams
-
excludeLocationHierarchies
-
excludeRegions
-
excludePayGroups
-
excludeFundHierarchies
-
excludeGrantHierarchies
For information about all the configurable properties for this connector, refer to Workday Connector Configuration.
-
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.
Test the Workday connector
When your connector is configured correctly, test its status by running the following command:
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?_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 status of "ok": true
indicates that the connector can contact the Workday instance.
To retrieve the workers in the Workday system, run the following command:
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" }, ... ] }
The first time the connector retrieves the employees from the Workday system, the following warning, which you can safely ignore, might display in the console:
WARNING: Default key managers cannot be initialized: Invalid keystore format java.io.IOException: Invalid keystore format
To retrieve a specific user, 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, set up a mapping between Workday and IDM managed users.
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
andpassword
) -
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"
Implementation specifics
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Workday connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.
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) |
---|---|---|---|---|
|
|
|
|
No |
Indicates if the Management Chain Data element is included in the response. |
||||
|
|
|
|
No |
Indicates if the Organization Data element is included in the response. |
||||
|
|
|
|
No |
Indicates if the Personal Data element is included in the response. |
||||
|
|
|
|
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. |
||||
|
|
|
|
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. |
||||
|
|
|
|
No |
Indicates if the Role Data element is included in the response. |
||||
|
|
|
|
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. |
||||
|
|
|
|
No |
Indicates if the Employment Data element is included in the response. |
||||
|
|
|
|
No |
Indicates that Account Provisioning Data will be included in the web service response. |
||||
|
|
|
|
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. |
||||
|
|
|
|
No |
Indicates if the Related Person Data element is included in the response. |
||||
|
|
|
|
No |
Indicates if the Photo Data element is included in the response. |
||||
|
|
|
|
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. |
||||
|
|
|
|
No |
Excludes the teams from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected. |
||||
|
|
|
|
No |
Indicates if the Transaction Log Data element is included in the response. |
||||
|
|
|
|
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. |
||||
|
|
|
|
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. |
||||
|
|
|
|
No |
Indicates if the Employee Contract element is included in the response. |
||||
|
|
|
|
No |
Indicates that User Account Data will be included in the web service response. |
||||
|
|
|
|
No |
Excludes the regions from the Organization Data element response. This can only be selected when the Include Organization Data boolean is also selected. |
||||
|
|
|
|
No |
If set to true, multiple managers in the management chain data are returned. |
||||
|
|
|
|
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) |
---|---|---|---|---|
|
|
|
|
No |
Indicates whether the Staffing Restrictions Data element is included in the response. |
||||
|
|
|
|
No |
Indicates whether the Supervisory Data element is included in the response. |
||||
|
|
|
|
No |
Indicates whether the Hierarchy Data element is included in the response. |
||||
|
|
|
|
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) |
---|---|---|---|---|
|
|
|
|
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. |
||||
|
|
|
|
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. |
||||
|
|
|
|
Yes |
The username for logging into the Workday service. It will be concatenated with the tenant name (user@tenant) |
||||
|
|
|
Yes |
Yes |
The user password for logging into the Workday service |
||||
|
|
|
|
No |
Excludes terminated employees or contingent workers whose contracts have ended from the query response (defaults to false). |
||||
|
|
|
|
No |
Excludes contingent workers from the query response. |
||||
|
|
|
|
No |
Excludes employees from the query response. |
||||
|
|
|
|
No |
Specifies the amount of time, in seconds, that the client will attempt to establish a connection before it times out. The default is 30 seconds). Set to 0 for no timeout. |
||||
|
|
|
|
No |
Specifies the amount of time, in seconds, that the client will wait for a response before it times out. The default is 60. Set to 0 for no timeout. |
||||
|
|
|
|
No |
Sets the page size used for search operations (defaults to 100). |
||||
|
|
|
|
No |
If defined, the connection to Workday goes through this HTTP proxy server. |
||||
|
|
|
|
No |
The HTTP proxy server port number (defaults to 8080). |
||||
|
|
|
|
No |
The file path to the XSL File to get the custom attributes. |
||||
|
|
|
|
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. |
||||
|
|
|
|
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. |
||||
|
|
|
|
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). |
||||
|
|
|
|
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.