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 enables you to 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.

Download the Workday connector from the ForgeRock BackStage download site and place it in the /path/to/openidm/connectors/ directory.

Download the Workday connector dependencies and copy them to the /path/to/openidm/lib/ directory. If you are running the connector remotely, copy the dependencies to the /path/to/openicf/lib/ directory on the remote system.

Configuring the Workday Connector

  1. The easiest way to configure the connector is to use the Admin UI. Select Configure > Connectors > New Connector, then select Workday in the Connector Type field.

    Alternatively, use the sample configuration file provided in /path/to/openidm/samples/example-configurations/provisioners/provisioner.openicf-workday.json. Copy that file to your project's conf/ directory, and set enabled to true.

  2. 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.

  3. 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, with the following settings:

    • 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 that are returned for every worker included by the parameters in the previous section.

    For performance reasons, set all of these to false initially, then include only the properties that you need.

    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, then include only the properties that you need:

    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".

Testing the Workday Connector

When your connector is configured correctly, you can 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.20.12",
      "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"
{
  "_id": "3aa5550b7fe348b98d7b5741afc65534",
  "title": "Vice President, Human Resources",
  "country": "USA",
  "postalCode": "94111",
  "userID": "lmcneil",
  "hireDate": "2000-01-01-08:00",
  "address": [
    "3939 The Embarcadero"
  ],
  "state": "California",
  "postalAddress": "3939 The Embarcadero\nSan Francisco, CA 94111\nUnited States of America",
  "addressLastModified": "2011-06-20T13:54:02.023-07:00",
  "firstName": "Logan",
  "gender": "Female",
  "employeeID": "21001",
  "managerID": "21431",
  "email": "logan.mcneil@workday.net",
  "city": "San Francisco",
  "preferredName": "Logan McNeil",
  "birthDate": "1971-05-25-07:00",
  "active": true,
  "preferredFirstName": "Logan",
  "employee": true,
  "workerType": "Full time",
  "positionEffectiveDate": "2016-06-01-07:00",
  "preferredLastName": "McNeil",
  "dateActivated": "2000-01-01-08:00",
  "legalName": "Logan McNeil",
  "lastName": "McNeil",
  "mobile": [
    "+1 (415) 789-8904"
  ],
  "terminated": false
}

Reconciling Users from Workday to IDM

To reconcile users from Workday to the IDM repository, set up a mapping, either using the Admin UI or in a sync.json file in your project's conf directory. For information about mapping resources, see Mapping Data Between Resources.

When you have created a mapping, you can 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"
}

Updating 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 update's user lmcneil'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"
{
  "_id": "3aa5550b7fe348b98d7b5741afc65534",
  "title": "Vice President, Human Resources",
  "country": "USA",
  "postalCode": "94111",
  "userID": "lmcneil",
  "hireDate": "2000-01-01-08:00",
  "address": [
    "3939 The Embarcadero"
  ],
  "state": "California",
  "postalAddress": "3939 The Embarcadero\nSan Francisco, CA 94111\nUnited States of America",
  "addressLastModified": "2011-06-20T13:54:02.023-07:00",
  "firstName": "Logan",
  "gender": "Female",
  "employeeID": "21001",
  "managerID": "21431",
  "email": "logan.mcneil@workday.net",
  "city": "San Francisco",
  "preferredName": "Logan McNeil",
  "birthDate": "1971-05-25-07:00",
  "active": true,
  "preferredFirstName": "Logan",
  "employee": true,
  "workerType": "Full time",
  "positionEffectiveDate": "2016-06-01-07:00",
  "preferredLastName": "McNeil",
  "dateActivated": "2000-01-01-08:00",
  "legalName": "Logan McNeil",
  "lastName": "McNeil",
  "mobile": [
    "+1 (415) 859-4366"
  ],
  "terminated": false
}

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.

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.

Configuration properties

PropertyTypeDefault Encrypted [a] Required [b]
includeManagementChainDataForWorkers Boolean true

Description is not available

includeOrganizationsForWorkers Boolean true

Description is not available

includePersonalInformationForWorkers Boolean true

Description is not available

excludeCostCentersForWorkers Boolean false

Description is not available

excludeCustomOrganizationsForWorkers Boolean true

Description is not available

includeRolesForWorkers Boolean false

Description is not available

includeStaffingRestrictionsDataForOrganizations Boolean false

Description is not available

excludeMatrixOrganizationsForWorkers Boolean true

Description is not available

includeEmploymentInformationForWorkers Boolean true

Description is not available

includeAccountProvisioningForWorkers Boolean false

Description is not available

excludeBusinessUnitHierarchiesForWorkers Boolean true

Description is not available

includeRelatedPersonsForWorkers Boolean false

Description is not available

includePhotoForWorkers Boolean false

Description is not available

excludeSupervisoryOrganizationsForWorkers Boolean true

Description is not available

excludeTeamsForWorkers Boolean false

Description is not available

includeTransactionLogDataForWorkers Boolean true

Description is not available

includeSupervisoryDataForOrganizations Boolean false

Description is not available

excludeCompaniesForWorkers Boolean false

Description is not available

includeAdditionalJobsForWorkers Boolean false

Description is not available

excludeBusinessUnitsForWorkers Boolean false

Description is not available

includeHierarchyDataForOrganizations Boolean false

Description is not available

includeEmployeeContractDataForWorkers Boolean false

Description is not available

includeUserAccountForWorkers Boolean true

Description is not available

excludeRegionsForWorkers Boolean false

Description is not available

includeRolesDataForOrganizations Boolean false

Description is not available

includeMultipleManagersInManagementChainDataForWorkers Boolean false

Description is not available

[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM.

[b] A list of operations in this column indicates that the property is required for those operations.

Basic Configuration Properties

PropertyTypeDefault Encrypted [a] Required [b]
hostname String null

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.

tenant String null

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

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

password GuardedString null

The user password for logging into the Workday service

excludeInactiveWorkers boolean false

Excludes from the response terminated employees or contingent workers whose contracts have ended (defaults to false)

excludeContingentWorkers boolean false

Excludes contingent workers from inclusion in a query response.

excludeEmployees boolean false

Excludes employees from inclusion in a query response.

connectionTimeout int 30

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.

receiveTimeout int 60

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.

pageSize long 100

Set the page size used for search operations (defaults to 100).

proxyHost String null

If defined the connection to Workday will go through this HTTP proxy server

proxyPort int 8080

The HTTP proxy server port number (defaults to 8080).

xslTransformer File null

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

asOfEffectiveDate String null

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

Set 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

Set 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[] null

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

[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM.

[b] A list of operations in this column indicates that the property is required for those operations.

Read a different version of :