Use the Query Method to Retrieve Data

Dayforce SOAP Web Services Developer Guide

Version
R2024.1.0
Use the Query Method to Retrieve Data

This section covers the following topics:

  • Query Method.
  • Using GetEmployees.
  • Using GetEmployeesByXRefCodeRequest for large sets of employees.
  • Query for Data using the XRef Codes of ad hoc reports.

Query Method

While the SOAP service is capable of processing many variations of queries, there is only one method that you will call to perform a query:

Query(string sessionTicket, DFRequest request)

Seen in the above, the first parameter of the Query method is the Session Ticket. The second parameter is the request for data and will have a base type of DFRequest, but the actual type will be specific to the type of query that you want to perform.

Use the GetEmployeesRequest Object

For this sample to display the employee name properties, the default role of the authenticating user account must have the Employee Personal Information access authorization enabled for reading the data. In addition, the field level filtering configuration must be set up. See Authorization and Filtering Data.

To perform a query for one or more employees, populate a GetEmployeesRequest object and submit it to the Query method. The class is defined with the properties in the table below, which can be used to filter and control the output.

Properties of the GetEmployeesRequest and GetEmployeeXRrefCodes

The following table contains the properties you can use to filter and control output of the GetEmployeesRequest and the GetEmployeeXRefCodes objects:

Properties to filter and control output of the GetEmployeesRequest and GetEmployeeXRefCodes objects
Name Description
ContextDate The Context Date specifies which version of the employee data should be returned. Employees change over time, and this property is used to retrieve employee data as of a particular date. This value defaults to the current date if not specified.
EmployeeNumber Specifying an Employee Number should limit the result to one employee.
EmployeeXRefCode Specifying an Employee XRef Code will limit the result to one employee.
EmploymentStatus Filter by employment status groups of Active, Inactive, or Terminated.
FilterHireEndDate If specified, all returned employees will have been hired on or before the date provided.
FilterHireStartDate If specified, all returned employees will have been hired on or after the date provided.
FilterTerminationEndDate If specified, all returned employees will have been terminated on or before the date provided.
FilterTerminationStartDate If specified, all returned employees will have been terminated on or after the date provided.
IncludeSubordinateObjects Use this to control the amount of data returned. A value of True will return all employee data, where as a value of False will return just the top level employee data.
OrgUnitXRefCode Filter by Organization Unit XRefCode
UpdatedAfter DEPRECATED - Use UpdatedStartDate and UpdatedEndDate.
UpdatedEndDate If specified, all returned employees will have been updated on or before the date provided.
UpdatedStartDate If specified, all returned employees will have been updated on or after the date provided.

Sample Code - Query for Employee Data

This figure shows sample code to query for employees that started after a given date:

Sample code to query for employee data.

Manage the Number of Employees Returned

Using the properties for the GetEmployeesRequest object, you can query for employees in various ways. Depending on the properties you set, your request can return a single employee or all of the employees in the database. To prevent overloading the systems or network with large data sets, a governor is in place to limit the number of employees that can be returned with a single request. That number is set in the authentication response in MaximumQueryResults.

The maximum number of employees that will be returned in a single response is 1,000. This value is returned in the Authentication response and can be verified there in case it changes in future releases.

If your query exceeds the maximum number of records as set by the governor, you will receive an error message indicating this, and no employee data will be returned.

An alternative mechanism is offered for retrieving a large number of employees, which is described in the next section.

Use the GetEmployeesByXRefCodeRequest for Large Sets of Employees

As mentioned in the previous section, there is a governor in place to restrict the number of Employee objects that can be returned on a single request. This number can be verified in the Authentication response in the MaximumQueryResults setting.

If your query is returning too many results, you can use the GetEmployeesByXRefCodesRequest to retrieve all of the employees that match your query criteria in batches by using groups of employee xref codes.

This alternative process involves determining the MaximumQueryResults limit enforced by the query governor. Next, you can run the GetEmployeeXRefCodesRequest to retrieve an unbounded number of employee xref codes. When you have the complete list of the xref codes of those employees that match your query, you can submit additional requests to retrieve the actual employee data using xref codes in groups (batches) no larger than the MaximumQueryResult limit.

Steps to query for a large group of employees

To query for a large group of employees:

  1. Verify the value of MaximumQueryResults in the authentication response.
  2. Execute a query with a populated GetEmployeeXRefCodesRequest object.
  3. Note: This object is very similar to the GetEmployeesRequest object (described in Use the GetEmployeesRequest Object.
  4. Take the GetEmployeesRequest object and group the xref codes into groups no larger than the maximum value obtained in step 1.
  5. Instantiate a GetEmployeesByXrefCodeRequest object for each group of xref codes, and submit those objects one at a time to the Query method.