Use Ad Hoc Reports to Query for Data

Dayforce SOAP Web Services Developer Guide

Version
R2024.1.0
Use Ad Hoc Reports to Query for Data

Ad hoc reports are defined in Dayforce, and you can any number or types of reports that you need. The Dayforce web services API allows you to execute those reports and retrieve the data.

Report XRef Codes

Reports in Dayforce can be labeled with XRef codes. Only users who have the Web Services feature enabled for their role can set the XRef code for a report.

Important: The XRef code should be unique and shouldn't be changed once set because it's what you’ll use from your source code to run a report. Only reports with an XRef code are accessible via Dayforce Web Services.

Retrieve a List of Reports

To retrieve a list of reports that are available for you to execute via the web service, submit the following object:

GetReportDefinitionsRequest

Properties of the GetReportDefinitionsRequest

The following table contains the properties you can use to filter and control output of the GetReportDefinitionsRequest object:

Properties to filter and control output of the GetReportDefinitionsRequest object
Object Description
XRefCode

If specified, only one report definition will be returned if one is found that matches the case sensitive XRef code. If this parameter is blank, then all report definitions are returned.

You will receive back an array of ReportDefinition objects that define the reports that you can execute.

Sample Code - Query for Report Definitions

Figure 4: Query for Report Definitions.

Report Parameters

Report parameters allow you to change the results of the report by specifying values for the parameters. The report definition contains an array of zero or more report parameter definitions. The report parameter definitions define all of the parameters used by the report. The parameter definitions include the name, data type, operator (if required), and default value. The operator of a parameter indicates how the parameter is used, such as if it’s compared as equal to, or greater than/less than, as well as In and Not In list.

Some report parameters represent an enumerated type. In such cases, the ReportParameterDefinition will include an array of ListValue types. The ListValue defines an ID and Name. The ID value is the value that should be returned in a report parameter, the Name is for display purposes.

Set Report Parameters

Reports might contain many parameters, some required, some optional, and some with default values. You are only required to pass in parameter values for parameters that are required and don't have a default value. Optional parameters and required parameters with default values don't need to be passed in when executing a report.

Report parameters are provided on the request as an array of ReportParameter objects. The ReportParameter allows you to set a UniqueId and a Value. The UniqueId must match one of the parameters as defined in the ReportDefinition, and the Value is any string value that adheres to the datatype specified in the ReportDefinition.

Sample Code – Setting report parameters

Sample code for setting report parameters.

The sample code above is prompting the user for values to use for required parameters. All parameter values are passed as string values regardless of the parameter data type. The value will be validated prior to executing the report to ensure it can be coerced into the proper type.

The data type of the parameter is defined as a .NET data type (for example, Int32, String, Date). When setting values, ensure the values adhere to the rules of the .NET data type to prevent errors.

If the Operator indicates that multiple values are permitted, such as when it’s In or Not In, then the Value can be set to a comma delimited list of values.

The report will not be executed and an error will be returned if:

  • A required parameter has no value.
  • A parameter is passed in with a UniqueId that doesn't match a parameter on the report.
  • A parameter value cannot be coerced into the correct data type.

Retrieve Data for a Report

When you have an XRefCode for a report, you can request the data from that report. There are two processes that can be used to retrieve the data. If the set of report data is smaller, such as fewer than 1,000 rows, then you can retrieve all of the data with a single request by submitting a GetReportRequest object. On the other hand, if the set of report data is larger, then you’ll want to make use of pagination to break the report up into more manageable data sets.

Request All Report Data for a Smaller Report

For reports with smaller data sets, such as fewer than 1,000 rows, you can retrieve all of the data with a single request. To do this:

  1. Instantiate a GetReportRequest object and set the XRefCode property with the xref code of the report.
  2. Pass this GetReportRequest object to the Execute method.

The response will contain a Report object which will contain the column and row data.

Sample Code - Request All Report Data for a Smaller Report Without Pagination

Figure 5: Retrieving the data for a Report for a small report.

Request Report Data of Larger Reports Using Pagination

Retrieving report data via pagination requires the following three step process:

  1. Open the report which will also set the page size, you’ll do this by submitting a OpenReportPagesRequest object. Opening the report will result in a unique ReportId for that instance of the report and you’ll also be given the total number of rows and pages within the report. 
  2. Retrieve each page of the report by submitting a GetReportPageRequest object and specify in the ReportId and a PageNumber.
  3. Close the report with CloseReportPagesRequest. This will clean up the data.

Sample Code - Retrieve Report Data Using Pagination

Figure 6: Retrieving report data via pagination.