Get Report Requests are designed to return the raw report data from reports that are based on Reporting and Analytics > Reporting > Reports. If a consumer uses Get Report requests, then additional configuration, as described in the following process flow, is required:
- Create Specific Topic Designed for Web Services.
- Create Specific Report Definitions for each Consumer’s Role
- Add the Report Definitions to Each Consumer’s Role
- Add the Access Authorizations Based on the Allowed Report Definitions
- Verify the Report Configuration Using Web Services Explorer
1. Create Specific Topics Designed for Web Services
To keep your web service calls operating, it can be helpful to create specific topics for web service calls. These topics should only contain the tables and parameters that are needed for the calls.
2. Create Specific Report Definitions for Each Consumer’s Role
Important: The field-level data security layer used by Get Employees requests doesn't apply to Get Report requests.
Report security, along with the configuration of data elements in the report definition, controls the information that is ultimately available to the consumer. As such, only the required data elements should be included in the report definitions used by web services.
Moreover, given that the data elements allowed from one consumer to another varies, it's best practice to keep the report definitions separate, allowing for ongoing changes for one consumer without affecting others.
Report data filtering is controlled in the report definition, and this is another important reason for creating separate report definitions for each consumer. Reports with parameters and some user defined fields can be included in reports used by web services in version 7.47 and later; however, report definitions containing advanced formatting will not be usable by web services.
One of the most important aspects of designing reports for use with web services is ensuring the report returns an optimized set of data. Instead of returning large result sets, such as a full list of employees, the report definition should include only changed details since the previous successful Get Report request. The best way to accomplish this is to use a datetime report parameter that will be populated by the Get Report request and compared to the last modified time or start date of the records included in the report. Additional information for report parameters can be found in the Ad Hoc Reporting Guide.
2.1 Add an XRefCode to the Report Definitions Created for Each Consumer
The XRefCode field is available in the Report Properties UI only when a user has (temporary) Web Services feature access attached to their role.
Important: Get Report requests use XRefCode as request parameter that identifies the report definition to run, and only report definitions that have an XRefCode value, defined in the Report Integration Name field, will be available to this web services feature.
Additionally, report definitions that include advanced formatting aren't available for use with web services requests. The Advanced Formatting flag (ReportDefinition.AdvancedFormatting = 1) will be set if there is any column total or summary total setup in the Totals window.
3. Add the Report Definitions to Each Consumer’s Role
Update the role for each consumer (using Get Report requests) to include the report definitions that were configured in the previous step.
4. Add the Access Authorizations Based on the Allowed Report Definitions
When Get Report requests are processed, the reporting engine assembles and secures the data based on access authorization settings. The Role of the requesting web services User Account must have Read access to the data elements in order for the values to be populated and sent downstream. The process for configuring access authorizations for Get Report requests is the same as the process used for configuring access to the data when reports are generated through the Reporting feature.
5. Verify the Report Configuration Using Web Services Explorer
To ensure that configured report definitions are accessible via web services, it's strongly recommended that you use the web services explorer. In addition to the other functionality available on the web services explorer, you can use the Get Report Definitions button to retrieve all available reports.
Go to HCM Anywhere > Web Services > Explorer.
For the purposes of using the GetReportDefinitions request for this topic, it's important to note that reports are comprised of two basic elements: a report topic and a report definition.
Reports will be included in the results if ALL of the following conditions apply:
- The report topic can be found in, or built using, Reporting > Report Designer > Dataset Builder. Not all report topics available to the application are necessarily available to web services.
- The report definition is defined in Reporting and Analytics > Reporting > Reports using one of the report topics available in Reporting > Report Designer > Dataset Builder. These reports are marked as V2 in the Topic Type column.
- The report has an XRefCode, which you can set in the Report Integration Name field in the Properties dialog box when you create or edit a report definition in Reporting and Analytics > Reporting > Reports.
- The report definition doesn't have any column total nor summary total set up in the Totals dialog box when you create or edit a report definition in Reporting and Analytics > Reporting > Reports.
- The report definition is available to the web services user's primary role, which you can specify in the Properties dialog box when you create or edit a report definition in Reporting and Analytics > Reporting > Reports.
After you configure the report definition, you can go to HCM Anywhere > Web Services > Explorer and use the Web Services Explorer and search for any available report definitions by entering the user name and password for the web services user with access to the report definitions and clicking Get Report Definitions. If you include an XRefCode, only the report definition with that specific Report Integration Name will be returned. If no report definitions are returned, verify that all of the prerequisites listed above have been fulfilled.
Note: For each report definition parameter, the explorer limits the number of available values to 250. For Get Report, the Explorer limits the results to 1,000. These limitations only apply to the Explorer and don't apply when the call is performed outside of this tool.