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