What is a Custom Options Sync?
A Custom Options Sync is a part of the Workday integration that can be enabled in addition to a candidate export and/or job import integration. This per-field integration will sync the list of options available on a custom field in Greenhouse with the list of available options for a corresponding field in Workday. It can be set up on most custom single-select and multi-select job, offer, and candidate fields in Greenhouse.
For example, if you create a custom job field in Greenhouse called "Cost Center" that includes a list of all available cost centers in Workday, a custom options sync will keep the list of cost centers available in your "Cost Center" field in Greenhouse up to date with the cost center options available in Workday.
Please note that this integration only syncs the list of available options one can select on a field, it does not sync updates to Workday position data to Greenhouse jobs. Updating job data would be part of the Job Import portion of the integration.
How does it work?
First, a single-select or multi-select custom field will be setup in Greenhouse. Then after the custom options sync is built and enabled for the field, it will be designated as a Workday sync field, so it is no longer editable inside of Greenhouse. Visually, this changes the custom field editor page from an editable list of options to an uneditable list.
Depending on how the integration is built, changes to the list of options may sync hourly or with a frequency determined by your development team. Please see the integration options below for more details.
To a bulleted list of options pulled from Workday:
How do I build a Custom Options Sync integration?
There are three different ways that Greenhouse can sync with Workday’s custom options:
- Workday Web Services - this option should be used if Workday’s Web Services API offers a service call to get the list of options directly.
- Workday RaaS - a RaaS is used when Workday does not offer a web services call to retrieve the list of options. This requires additional work to build the report by either the customer or their Workday service provider.
- Greenhouse Harvest API - you can also sync changes from Workday to Greenhouse using the Greenhouse Harvest API instead of a Workday RaaS or Web Services call; this connection would be built using Workday Studio.
How often do changes sync?
With the Workday Web Services and RaaS options, Greenhouse will initiate a call to the Workday endpoints hourly to sync the option changes. With the Harvest API option, Workday will push the changes to Greenhouse, so the team who is building the integration on the Workday side can choose the frequency of the updates.
Web Services Call
The Workday web service API offers several methods to retrieve option lists that are used in their system. Greenhouse can support many of the option lists described in Get References Operation in the Integrations Web Service, which includes over a hundred useful lists of country codes and various internal Workday category codes.
The following link provides detailed steps on how to enable this option in Greenhouse:
Custom Options RaaS
In some cases, customers may wish to sync a Greenhouse option list which does not have a direct service call in Workday. The most common example of this is the “Supervisory Organization” list from Workday -- This list is not offered on the Get References page, but is usually a required field to create a position.
In these cases, Greenhouse is still able to sync the lists, but it requires some extra work on the customer’s part. Either the customer or their Workday provider must provide an accessible list in XML format which Greenhouse can poll once daily to get the list of options. Once the list is retrieved, Greenhouse will attempt to reconcile the lists as described above.
The XML format must contain A) a unique ID, which Greenhouse will use to determine if the field is new, extant, or removed, and B) the text as the customer would like it to appear in the Greenhouse custom field selector.
The following link provides steps on how to enable this option in Greenhouse and the expected RaaS format:
Greenhouse Harvest API
The following Greenhouse Harvest API methods can be used to sync the list of options value for a field from Workday to Greenhouse. The connection would be built using Workday Studio, and the Workday development team can decide the frequency of the updates:
- POST Create Custom Field Options
- PATCH Update Custom Field Options
- DELETE Remove Custom Field Options
How do I decide if a field needs a custom options sync?
Generally we recommend setting up custom field syncs for fields that have a large number of options that would be difficult to input manually into the Greenhouse field configuration, or for fields whose options change often and would require frequent editing to stay up to date with what's configured in Workday.
If you are building a job import integration, it is important to keep in mind that in order to import a job field value from Workday that maps to a single-select or multi-select field in Greenhouse, the value that you are importing must match an existing available option in Greenhouse. An available option cannot be created in Greenhouse just by importing the value from Workday on one position. Similarly for exporting candidates, keying Workday business processes off of exported values from Greenhouse often requires that the values from Greenhouse match available options in Workday.
For this reason, it’s important to make sure that fields with many available options in Greenhouse are kept up to date with what’s available in Workday.
What happens if an option is deleted in Workday?
Greenhouse cannot prevent Workday from deleting an option, even if it is currently in use on a job in Greenhouse. You should use caution not to remove any fields from Workday unless you are absolutely sure they are no longer needed.
However, if the option has been selected as the field value on jobs in Greenhouse, the field value will be maintained on individual jobs for historical purposes, unless the value is changed at the job level in Greenhouse.