Workday Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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 and Configure the Workday Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

Install the Workday Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

Download the connector .jar file from the ForgeRock BackStage download site.
- 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.12.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.
Download the Workday connector dependencies and copy them to the /path/to/openidm/lib/ directory. If you are using an RCS, copy the dependencies to the /path/to/openicf/lib/ directory on the RCS.

Configure the Workday Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

From the Admin UI, select Configure > Connectors, and click New Connector.
Note
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.
On the New Connector page, from the Connector Type drop-down list, select Workday Connector.
In the General Details and Base Connector Details areas, enter information, as necessary, and click Save.
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 form username@tenant).
username
The username used to log in to the Workday instance. Do not specify the complete username including the tenant. 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 to true, 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 to true. For performance reasons, set all of these to true 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, see "Workday Connector Configuration".

Test the Workday Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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, you might see the following warning in the console:

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

You can safely ignore this warning.

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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"

Implementation Specifics

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

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.

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.