Workday Read

In this article

Overview

Workday Read Snap is a Read-type Snap that you can use to read Workday data using the Workday service name, object, and optionally, output fields.

The output fields are the Include and Exclude fields typically defined by Workday in the request's Response_Group section. Output fields prefixed with include, add additional fields to the output document, whereas the output fields prefixed with exclude, excludes fields from the output document. Output fields prefixed with include add additional fields to the output document, whereas the output fields prefixed with exclude excludes fields from the output document.

See Workday Web Services (WWS) Directory for information on the Workday output section to specifically determine the nature and effect that each output field has on the output document.

You can configure this Snap to query data specific to your requirements. This is especially useful when looking for data modifications in specific objects such as Name_Data, Birth_Date, etc. You can use Workday's Transaction Logs service to do so. Refer to this example to see how this works. 


The Workday Read Snap automatically sends multiple SOAP pagination requests to provide the complete set of Workday objects with no additional coding effort.

ETL Transformations & Data Flow

This Snap enables the following ETL operations/flows:

  1. Extract data from Workday
  2. Transform Workday SOAP XML response(s) to JSON output

Here's how it works:

  1. For the Snap to successfully receive data from Workday, you must provide at least the following information:
    1. The user account information needed to log into Workday
    2. The name of the Workday web service that must be used to access the data needed
    3. The name of the object containing the required data, and
    4. Output fields that the Workday server must use to populate the returned data
  2. The Snap evaluates any defined property expressions and then creates and submits a SOAP request with authentication.
  3. On successful Workday server response, the Snap converts the returned SOAP XML response into JSON for the output view.
  4. If there is an exception or error, the Snap performs the task specified for error management.

Prerequisites

  • You must have a Workday Account, data to query, and Workday security access to the objects concerned. Contact your organization's Workday Security Administrator for appropriate access.

  • Workday recommends using an Integration System User (ISU) with APIs.

Support for Ultra Pipelines

Works in Ultra Task Pipelines if batch size is set to 1. 

Limitations and Known Issues

None.

Snap Input and Output

Input/OutputType of ViewNumber of ViewsExamples of Upstream and Downstream SnapsDescription
Input 

Document


  • Min:0
  • Max:1
  • Mapper
  • JSON Generator

document that conforms to the input view schema of the Snap. The input view schema is provided to an upstream Mapper Snap based on the selected service object.

Output

Document


  • Min:1
  • Max:1
  • File Reader
  • Mapper
  • JSON Formatter

A document that represents the record structure of the retrieved Workday service object. Each record is represented as one document on the output view.

Snap Settings

Field Name

Field Type

Description


Label*


String

Specify the name of the Snap. You can modify this text to indicate what the Snap does. This is especially useful if you have more than one Workday Read Snap in your Pipeline.

Default ValueWorkday Read
Example: Get Cost Center List from Workday

Timeout*



Integer

Specify the timeout value for each Workday SOAP request. The value of 0 means no timeout. Because Workday Read supports Workday SOAP pagination, multiple SOAP requests can occur for one execution. Consequently, the timeout can be less than the time it takes to complete writing documents to the output view. 

Default value: 60 
Example: 0

Service*


String/Expression/Suggestion

Specify the name of the web service that you want to use. 

Default value: [None]
ExampleStaffing

Object*


String/Expression/Suggestion

Specify the name of the object from which you want to retrieve data. Select the object from the list of objects returned by the web service you selected in the Service field. For example, if you selected the Payroll Service, the Object field displays all the objects that were retrievable under the Payroll service from Workday.

Default value: [None] 
ExampleHuman_Resources-Get_Job_Profiles

Outputs


Use this field set to indicate the data you want the query to return from Workday. Add each output in a separate row. Click Add  to add rows. This field set contains Path and Value fields.

The Outputs fieldset limits the kind and amount of information returned by your query. Excluding unnecessary fields increases Snap throughput and simplifies downstream Snap pipeline development.

See Workday Web Services Directory for additional information on the Workday Web Services API.

PathString/Suggestion

Specify the output to be returned by the request. These work with the include and exclude fields defined by Workday in the request's Response_Group section and include or exclude fields in the output document. For example, the command 'Response_Group.Include_Worker_Documents' includes worker document details in the output.

Default Value: [None]
ExampleInclude_Reference

ValueDropdown list

Specify the value to be set for the path on the request.

Default ValueTrue
Example: False

Simplified output


Checkbox

Select this checkbox to simplify output documents by removing Workday namespace attributes from key names. It also converts the nested ID collection to a simple map data. You can use a JSON Splitter Snap to further simplify the output document data structure.

If not selected, the Snap produces an output in a tree structure with nested levels of information.

Default Value: Not selected

Page NumberInteger

Enter the specific page number from which you you want to retrieve data. Retain 0 to retrieve data from all the pages.

Default Value: 0
Example: 2

Page SizeInteger

Specify the number of records to fetch per page.

Default Value: 100
Example:100

This Snap submits a SOAP request to Workday with an output page size and converts the Workday SOAP XML response to JSON in the output view. If the Snap page setting is 0, and the Workday SOAP response indicates that more pages of data are available; it submits additional SOAP requests, collects all the pages of data, and transforms them into JSON.

Multi-threadedCheckbox

Select this checkbox to enable the Snap to expedite reading the requests by using multiple threads.

This feature may yield inconsistent results.

Max Pool SizeInteger

Activates when Multi-threaded checkbox is selected.

Specify the value for pool size to control the maximum number of threads in the pool for the instance.

Default Value: 10
Example: 5

Number of Retries Integer

Enter the integer value to specify the number of attempts the snap should make to perform the selected operation in case of connection failure or timeout.

Minimum value: 0

Default Value: 0
Example: 3

Retry Interval (seconds)Integer

Enter the time interval in seconds between retry attempts.

Minimum value: 1

Default Value: 1
Example: 3

Snap Execution

Dropdown list

Select one of the three modes in which the Snap executes. Available options are:

  • Validate & Execute: Performs limited execution of the Snap, and generates a data preview during Pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during Pipeline runtime.
  • Execute only: Performs full execution of the Snap during Pipeline execution without generating preview data.
  • Disabled: Disables the Snap and all Snaps that are downstream from it.

Troubleshooting

ErrorReasonResolution
HTTP/1.1 407 Proxy Authentication required.The Snap is unable to tunnel through proxy.

Add the following key-value pair values to your Groundplex configuration and restart the plex to reflect the changes.

Key: jcc.jvm_options
Value: -Djdk.http.auth.tunneling.disabledSchemes=""

Examples

Getting Applicants from Workday

This example Pipeline demonstrates how to get applicants from Workday by specifying the number of results you want to see in a page, and the number of pages of results you want in the output.

In this Pipeline, the Workday Read Snap retrieves records from the Get_Applicants object and writes the data to a JSON file

Workday Snap ConfigurationOutput
The Page size and the Page Number fields are set to their default values of 0 and 100 respectively. This means that the Read Snap retrieves all the records from the Get_Applicants object when executed.

The output preview shows all the rows of data, starting from the first row of data onwards and displays 100 records per page.

.


You can also use Pipeline parameters to specify short strings for complicated service and objects in Workday. For step-by-step information on managing properties of Pipelines, see Pipeline Properties Parameters.

The output preview shows all the rows of data, starting from the first row of data onwards.

Let us now set the Page Number value to 2 and the Page Size to 20. This enables the Workday Read Snap to retrieve records from the page 2, with 20 records in each page.

The output preview shows you 20 rows of data, starting from the second page of data onwards. For instance, in the screenshot below, you can see that there are only 20 rows displayed, and that name of the worker in the first row is different from the output screenshot above:

Download the Pipeline.

Viewing the Simplified Output of Documents

This example Pipeline demonstrates how to generate a simplified view of your Workday Read Snap output without the difficult-to-read attributes and metadata that typically accompany Workday output.

This Pipeline retrieves a list of workers, with detailed documents accompanying each worker. We shall see what the output looks like without the Simplified view restriction, and then generate a Simplified view of the output using the Workday Read Snap.

As you can see, in the screenshot above, the Simplified output checkbox is not selected; the output, therefore, is detailed:

We shall now select the Simplified output checkbox and see how the output changes. Here's the Workday Read Snap Settings popup with the Simplified output checkbox deselected:

As you can see in the screenshot below, the output is much easier to read:

You can also use pipeline parameters to specify short strings for complicated service and objects in Workday. For step-by-step information on managing properties of pipelines, see Pipeline Properties Parameters.

Download the sample pipeline here.

Querying for Precise Data Using the Workday Read Snap

This example demonstrates how you can query for all the data associated with an object, and for specific data within an object, using the Workday Read Snap.


 Querying for precise data using the Workday Read Snap

Once you have configured the Workday Read Snap with your Workday account details, you should be able to view the services and objects that Workday has enabled for your account. You can then use these services and objects to query the Workday database associated with your account.

Let us look at some of the important ways in which you can create Workday queries using the Workday Read Snap. You can:

  • Retrieve all the data associated by default with an object

  • Retrieve specific data from Workday by:

    • Specifying specific criteria for data inclusion

    • Specifying specific criteria for data exclusion

The following sections offer detailed guidance on how to perform each of these tasks.

Retrieving all the Data Associated by Default with an Object

To retrieve all the data associated by default with an object:

  1. Add the Workday Snap to your pipeline and configure your account details. For information on how to configure your Workday account, see Workday Read.

  2. Save the configuration details and wait for validation to complete. Once the Snap is validated, click Settings. This displays the Settings popup.

  3. In the Settings screen, enter a Label for the new Snap and change the default Timeout details if required.

    We recommend labeling your Snaps such that their names are indicative of their role in the Snap. This will help other users understand the purpose of the Snap better.

  4. Click the Suggestions icon on the right of the Service field. This displays a suggestion list containing all the Workday services accessible to your account. Select the service associated with the data you want to retrieve. You can also enter the initial letters of the service you are looking for to further filter the list of services displayed.

  5. Similarly, click the Suggestions icon on the right of the Object field. This displays a suggestion list containing all the objects associated with the service you selected in the Service field. Select the object that contains the data you want to retrieve. You can also enter the initial letters of the object you are looking for to further filter the list of objects displayed.

  6. Given the size of the data typically returned as a result of an object-level request, it's typically a good idea to limit the values of the Page Number and Page Size fields to 1, especially during the testing phase. This way, only the first data record is retrieved, and you can see the result returned by the query almost immediately.

    You can also use Pipeline parameters to specify short strings for complicated service and objects in Workday. For step-by-step information on managing properties of pipelines, see Pipeline Properties Parameters.

  7. Save your changes and close the popup. The application now validates your settings and displays a preview of the data retrieved if the validation is successful.
    Note that we only chose the service and object containing the data needed, and made no further specifications. The data retrieved, therefore, contains only the default data associated with the object we chose.

Specifying Criteria for Data Inclusion and Exclusion

 Specifying Criteria for Data Inclusion and Exclusion

Including Specific Data

Use outputs in Workday Snap settings to limit the kind of information Workday returns as the result of your query. Excluding unnecessary fields increases Snap throughput and simplifies downstream Snap pipeline development. Also, it allows you to retrieve only those pieces of information that you actually require, thereby reducing the need to search for relevant data in the query results.

To only include specific data in your results:

  1. Open the Workday Read Snap that you just used to retrieve the default list of data contained in the Staffing > Get_Workers object.

  2. Click the + button at the right of the Outputs fieldset. This adds a row of fields under Outputs. These are the fields that we will use to enter further specifications related to the data we want to retrieve from Workday.

  3. Click the Suggestions icon on the right of the Path field. This displays a suggestion list containing all the inclusions and exclusions that Workday has made available for the concerned object, to your account. Say you want to view all the organizational information associated with workers in your organization. Select Response_Group.Include_Organizations from the drop-down list.

  4. In the Value field adjacent to the Path field, True is selected by default. Leave it unchanged.



    You can also use pipeline parameters to specify short strings for complicated service and objects in Workday. For step-by-step information on managing properties of pipelines, see Pipeline Properties Parameters.

  5. Save your changes and exit the popup.

The application now validates your changes. Once this is complete, click the icon that appears adjacent to the Workday Read Snap. This displays a preview of the data retrieved using your modified query.

You can see that this is new data, and that the data that the application retrieved using just the service and object defaults is missing. In other words, the data retrieved using inclusions is different from the content retrieved by default for the concerned object.

Excluding Specific Data

In the screenshot above, you can view the data that Workday returned after being asked to include only organizational information associated with its workers. One of the data nodes at the bottom of the screenshot is "Organization_Support_Role_Data". This node contains details associated with each worker's role in the organization. If you wish to query Workday for all the organizational information associated with a worker without including historical details such as the name of the person from whom the worker took over, you can do so by combining an Exclude expression with the Include expression in the Output query. 

To exclude specific data from being returned as a result of a query:

  1. Click the Workday Read Snap to open the Workday Read popup. Navigate to the Settings tab.

  2. Click the + button at the right of the Outputs fieldset. This adds another row of fields under Outputs. We shall enter specifications related to the data we want to exclude here,

  3. In the field that appears under the column heading Path, enter Response_Group.Exclude_Organization_Support_Role_Data.

  4. The Value field defaults to True. Leave it unchanged.

    You can also use pipeline parameters to specify short strings for complicated service and objects in Workday. For step-by-step information on managing properties of pipelines, see Pipeline Properties Parameters.

  5. Save your changes and close the popup. Allow the application to validate your changes. Once this is done, click the icon to the right of the Workday Read Snap. This displays a preview of the data returned in response to your query:

As you can see in the screenshot above, the new output contains all the fields that were returned in the previous query, except for Organization_Support_Role_Data. Combining Include with Exclude expressions thus, you can control the data that Workday returns to queries.

See it work! Download the sample pipeline here.

Using the Workday Read Snap for Error Handling

This example demonstrates how you can use the Workday Read Snap for error handling.

 Using the Workday Read Snap for error handling

This example showcases how to implement error handling in the Workday Snap. Here, we assume a bad mapping.

Download the sample pipeline here.

You may need to update your tenant details in the downloaded example, because Workday reads queries by the WID of the requester.


In the following mapping, we assume that the data types that we mapped together are incompatible. Usually while mapping an object, you may have to make several attempts to map the data you need to appropriate fields; so it is good to understand how you can manage problematic mappings.

The Workday Read Snap is configured as follows:

When the pipeline is executed. the invalid type mapping of 'aaa' to '$Request_References[*].Worker_Reference[*].ID[*].type' will trigger the Workday Read Snap to write to the error view (Here we enabled the error view on the Snap explicitly.)

Understanding Workday Read Error Views

  • The error key provides the message returned from Workday. In this case, the error key indicates that mapping the value 'aaa' to the 'type' field is invalid.

  • The envelope key contains information related to the SOAP envelope that was populated by applying the variables from the input view into the generated SOAP envelope.

  • The stripped envelope key carries the information of the SOAP envelope that will be sent to Workday.

  • The original key carries the document that came in on the input view. 

Displaying Records For Values Provided Upstream

This example demonstrates how you can use upstream Snaps to control the data returned by the Workday Read Snap.

 Workday Read Snap displaying all the records pertaining to the values provided upstream

The Workday Read Snap doesn't necessarily need upstream Snaps. However, it can be used to leverage fields in the upstream data to retrieve and make available specific data from Workday to downstream Snaps.

Example Overview

In this example, we shall retrieve Workday data related to specific workers and upload the received data to a SQL server.

Understanding the Pipeline

Review the table below to understand:

  • The tasks that must be performed to identify and transition data from Workday to SQL Server, based on specific criteria.

  • The Snaps that are used in the pipeline that effects this transition.

  • The task that each Snap performs.

Task

Snap

Description / Comments

Read worker-related JSON data from an SLDB file.

Read Data from SLDB (File Reader Snap)

Reads the Staff.JSON file from a shared folder in the SLDB.

Retrieve a list of all worker IDs that are greater than 21040.

Parse Data as JSON (JSON Parser)

Converts the received file into a valid JSON format, so it can be managed properly.

Filter User Data (Filter Snap)

Runs through the JSON data, seeking out all user IDs that are greater than 21040.

Retrieve Workday data related to the filtered list of worker IDs.

Map Data Fields (Mapper Snap)

Maps data keys pertaining to the Worker ID type and value in the input JSON file to the corresponding column headers in the Workday DB table.

Get Worker Data (Workday Read Snap)

Retrieves worker data associated with the identified worker IDs from the Workday DB.

Upload the returned data to SQL

Map to SQL (Mapper Snap)

Maps the keys present in the data received from Workday to column headers in the target SQL DB table.


SQL Server BulkUpload

(SQL Server - Bulk Load Snap)

Uploads the mapped data into the identified SQL Server DB table.

For details on the contents of each Snap, download and import the sample pipeline into SnapLogic.

Download the sample pipeline here.

Retrieving Data Modifications

Retrieving data modifications in a date range becomes much more effective if you use the Transaction Logs service. This way, instead of querying all data for the specified date range, Workday can use the transaction logs for the same date range and only compare records modified within the date range. This example demonstrates how this can be done.

Download this Pipeline.

 Understanding the Pipeline

This Pipeline is structured as follows:

  • Mapper Snap: Passes the Transaction Log criteria to the Workday Read Snap.
  • Workday Read Snap: Retrieves data matching the criteria.

To use the Transaction Logs service in the Workday Read Snap, you must first pass the following Transaction Log criteria into the Workday Read Snap:

  • Date range
  • Modified entity's name
  • Modified entity's value

The above criteria is passed through the Mapper Snap which is configured as shown below:

The output from the Mapper Snap is as shown below:

To use a Workday service, the Workday Read Snap's Output field must be configured to set the service to True:

The output from the Workday Read Snap is as shown below:

Below is a screenshot of the Workday Read Snap without using the Transaction Log service:

Comparing both outputs, you can see that using the Transaction Logs service is much more efficient.


Download this Pipeline.

Downloads

  File Modified

ZIP Archive WD - Read - Example_2014_09_30_slp.zip

Apr 10, 2017 by Aparna Tayi

ZIP Archive WD - Read Error_2014_09_30_slp.zip

Apr 10, 2017 by Aparna Tayi

File Workday Read for Advance Case_2017_08_21.slp

Aug 21, 2017 by Aparna Tayi

File Example_1_WDR_PageNumber_PageSize.slp

Jul 20, 2018 by Rakesh Chaudhary

File Example_2_WDR_Simplified_Output.slp

Jul 20, 2018 by Rakesh Chaudhary

File Example_3_Data_Inclusion_Exclusion.slp

Jul 20, 2018 by Rakesh Chaudhary

File Example_4_WDR_Displaying_Upstream_Records.slp

Jul 20, 2018 by Rakesh Chaudhary

File Example_5_Error_Handling.slp

Jul 20, 2018 by Rakesh Chaudhary

File Workday_Read_Transaction_Log_Service.slp

Apr 20, 2019 by Mohammed Iqbal
 

Snap Pack History

 Click to view/expand
Release Snap Pack VersionDateType  Updates
4.27main12833StableEnhanced the Workday Read Snap with the new field Pool Size that controls the maximum number of threads in the pool. This field is available only when you select the Multi-threaded checkbox.
4.26426patches11525 LatestEnhanced the Workday Read Snap with the new field Pool Size that controls the maximum number of threads in the pool. This field is available only when you select the Multi-threaded checkbox.
4.26main11181 StableUpgraded with the latest SnapLogic Platform release.
4.25main9554
 
StableUpgraded with the latest SnapLogic Platform release.
4.24main8556
StableUpgraded with the latest SnapLogic Platform release.
4.23main7430
 
StableUpgraded with the latest SnapLogic Platform release.
4.22main6403
 
Stable

Removes support for Workday WSDL Account. Pipelines and Snaps using this account type must switch to either Workday Account or Workday Dynamic Account.

4.21snapsmrc542

 

StableUpgraded with the latest SnapLogic Platform release.
4.20 Patch workday8817 Latest

Fixes the Workday Write Snap that ignores the Import Synchronized check box selection while importing object data. The Snap now:

  • Waits for the current import request to complete, whether successfully or with error, before initiating the next import request.
  • Provides accurate real-time status of the request to downstream Snaps.   

Existing Pipelines using this Snap may experience longer execution times due to the synchronous behavior. However, you no longer need to use an additional Snap to capture and pass on the request status to downstream Snaps.

4.20 Patch workday8761 Latest

Fixes the Workday Read Snap that fails to validate when configured in the New Form UI.  

4.20snapsmrc535
 
StableUpgraded with the latest SnapLogic Platform release.
4.19snaprsmrc528
 
Stable

The Workday Write Snap includes a Validate Only Load check box, which enables users to upload–and then manually validate–data before importing it into Workday.

4.18 Patch workday7837 Latest

Fixed an issue with the Workday Read Snap wherein the Snap is unable to log SOAP calls.

4.18snapsmrc523
 
StableUpgraded with the latest SnapLogic Platform release.
4.17ALL7402
 
Latest

Pushed automatic rebuild of the latest version of each Snap Pack to SnapLogic UAT and Elastic servers.

4.17snapsmrc515
 
Latest

Added the Snap Execution field to all Standard-mode Snaps. In some Snaps, this field replaces the existing Execute during preview check box.

4.16 Patch workday6973 Latest

Fixed an issue with paging variable toggle in Workday Read Snap to produce correct preview data.

4.16 Patch workday6862

 

LatestFixed an issue with the Workday Read Snap not logging SOAP calls.
4.16snapsmrc508
 
StableUpgraded with the latest SnapLogic Platform release.
4.15 Patchworkday6727 Latest

Fixed an issue with the Soap Execute Snap failing for Workday when the Trust All certificate is enabled while using SSL authentication.

4.15 Patchworkday6292 Latest

Fixed an issue with the Workday Read Snap giving inconsistent results. Reverting the multithreading update resolved the issue. 

4.15snapsmrc500
 
StableUpgraded with the latest SnapLogic Platform release.
4.14snapsmrc490
 
StableUpgraded with the latest SnapLogic Platform release.
4.13 Patch workday5247

 


Latest

Fixed the Workday Read Snap that took an extended time to read from the Workday application. 

4.13

snapsmrc486

 
StableUpgraded with the latest SnapLogic Platform release.
4.12

snapsmrc480

 
StableUpgraded with the latest SnapLogic Platform release.
4.11snapsmrc465
 
StableUpgraded with the latest SnapLogic Platform release.
4.10

snapsmrc414

 
StableUpgraded with the latest SnapLogic Platform release.
4.9snapsmrc405
 
Stable
  • Updated the Snap with Import Synchronized, Import Batch Size and Import Batch Node to enhance the performance for Import objects supporting bulk operations. 
  • Updated the Workday Read Snap with the Page Number and the Page Size properties.
4.8

snapsmrc398

 
Stable
  • Updated the Read Snap with the Simplified output property.
  • Info tab added to accounts.
4.7

snapsmrc382

 
StableUpgraded with the latest SnapLogic Platform release.
4.6snapsmrc362
 
Stable
  • Resolved an issue in Workday Read Snap that caused errors when the timeout field was set.
  • Resolved an issue in Snaps with Workday Dynamic account that caused an error when a pipeline parameter provided an empty value to the password field.
4.5.1

snapsmrc344

 
Stable

Resolved issues in Workday Snaps to ensure appropriate errors are routed to the error views.

4.4.1
 StableUpgraded with the latest SnapLogic Platform release.
4.4
 Stable

Resolved an exception in Workday Read.

4.3.2
 Stable
  • Addressed the following issues:
    • Defect: Workday Read Input Using As Of Date/Time in Response_Filter
    • Defect: Workday Snap Does Not Show All Services