Report definitions

Report Definitions contain the specific details of the report to be generated, including any parameters needed and which data source to run the report against. The Report Definitions tab of the dashboard is used for managing these definitions, as well as generating on-demand reports. There must be at least one data source before a report definition can be created.

Report definition authorization

There are three levels of authorization for the report definitions tab:

Reporting Administrator. Users with the reporting_administrator internal authorization role have full access to the report definitions tab, and all the definitions within the system. They can create, run, update, or delete any report for any data source.
Data Source Owner. Users that have an authorization role granted that is also defined on the data source as the owner of that data source have the same create, run, update, or delete privileges as the reporting administrator only for the data sources which they own. These users will not be able to see report definitions for other data sources, nor are they able to create a new definition for a source they do not own.
Report Viewer. Users that have an authorization role granted that is also defined on a report definition as the viewer of that data source have the ability to run or view the generated reports for which they are assigned Viewer. These users are able to run report definitions for other sources, have no create, update, delete privileges, nor are they able to view the contents of the report definition object itself. The only privilege they have is to view the report contents.

Any IDM user with the openidm-authorized authorization role has access to the reporting interface and definitions tab. No data will be available to them if they are not granted an authorization role explicitly defined on the IDR object.

Creating new report definitions

Navigate to the Report Definitions tab of the main dashboard.
Select Create Definition.
On the Create Report Definitions page, fill in each of the required fields. Additional details on the available fields are given below:

Name. (Required) Name of the report definition that appears in the table and in the list of available report definitions on Report Schedule forms.
Description. Provides additional information about the report definition and its purpose.
Data Source. (Required) Name of the data source to run the report against. After a data source has been successfully created, it displays in this list for selection.
Report Viewer. The IDM authorization role that grants a user the ability to run/view the contents of the generated report, including the ability to provide any run time parameters that the report requires. No other privileges are granted from this field. For more information on the report viewer, see Report Definition Authorization.

For reports where SQL is selected under Data Source:

SQL Report Source. (Required) SQL Query used to generate the report data. Multiple parameter values can be included by enclosing the parameter names in square brackets; for example [role_name], within the query. Any parameters that are designated in such a way are replaced by user-specified values at the time the report is generated or at the time a schedule is created using this report definition.

For reports where API is selected under Data Source:

Create report definition for API data source

API Endpoint. The specific API endpoint that is called by this report. This value is appended to the Base URL defined in the report’s data source (which is visible within the form field).
Method. HTTP method of API call, either GET or POST. For data sources that disable POST calls, GET is the only option available.
Query Parameters. Key/value pairs that are used as query parameters when making the API call. Each pair has the ability to be listed as dynamic, meaning the entire value of the key/value pair can be user provided at the report run time. If marked as dynamic, the key/value pair can alse be marked as required, which means that the value must be provided in order to generate the report.
Pagination Parameters. For report viewing within the IDR interface, this option allows you to define which specific query parameters among the ones defined in the Query Parameters section are used to control pagination. When enabled, the user running the report is not prompted to enter those parameters in the user interface, but instead be inferred upon based on the user interface controls for the page number and page size.

The options selected here only apply to the out-of-the-box (OOTB) ForgeRock Identity Reporting interface, and does not affect direct API calls or downloaded PDF/CSV reports.
- Select Pagination Type. The type of pagination that the endpoint uses. IDR currently supports page number or page offset pagination types.
- Page Size Parameter. The query parameter that controls the results returned per page.
- Page Offset Parameter. The query parameter that controls the offset value used (when page offset pagination type is selected).
- Page Number Parameter. The query parameter that controls the page number of results to return (when page number pagination type is selected).
- 0-based. Page number parameter 0-based. Select True if the first page number is 0 as opposed to 1 (when page number pagination type is selected).
Request Body. For definitions with the method POST, a request body must be defined to be sent with the request. The field is used to define the request body content.
For example, the request body could contain the below content:

{ "ownerId": "{{ownerId}}" }
Transformation Script. The transformation script is the snipped of code that takes the results retrieved from the API call defined, and converts the results into the expected data format that IDR can consume. For more information, see Transformation Scripts.

Once all the necessary fields have been filled in, click Save to finish creating the report definition.

Transformation scripts

Use the transformation script to convert the API report definition’s API call results into the expected IDR report format. IDR uses JavaScript for the scripts.

The script has reference to the following variables:

response. The response contents.
type. The type of report being generated, either html, csv, or pdf.
parameterValues. The dynamic values provided by the call to generate the report, if any.

The script has the ability to execute the necessary logic to manipulate the returned data. However, on completion of the script, it must return an object that contains the following two properties (at a minimum) in the expected format"

columns. An array of column name strings.
data. An array of objects, each of which contains the key/value pairs for the columns defined above.

An example transformation script of attributes from IDM, for example, could be the following:

 var result = {
   data: [],
   columns: ["Requestee", "Requester", "Items", "Start Date" ]
}

response.result.forEach( function(entry) {
   var row = {};
   row["Requestee"] = entry.requestee.displayName
   row["Requester"] = entry.requester.displayName
   row["Start Date"] = entry.startDate
   row["Items"] = _.map(entry.items, 'displayName').join(', ');
   result.data.push(row);
})

return result;

Dynamic report parameters

Both SQL and API report types support dynamic parameters that the user generating the report can submit at run time. You can also define these parameters when you create a schedule using the report definition.

SQL definitions

Parameter values can be defined within the SQL Source field, by enclosing the parameter names in square brackets; for example [role_name]. All SQL parameters are required.

API definitions

Parameter values can be defined by using double curly brace syntax; for example {{userId}}, in different places within the report definition.

The various places are:

API Endpoint.
Request Body.
Query Parameters.
- When a parameter is defined as dynamic, no curly brace syntax is required, the value entered when prompted is the entire value.
- When a parameter is not defined as dynamic, the curly brace syntax is used to replace a section of a static value.
  - For example, a _queryFilter parameter can have a value of accountStatus eq '{{accountStatus}}' and only the marked section are dynamically populated.

Modifying report definitions

Navigate to the Report Definitions tab of the main dashboard.
In the table, click the ellipses next to the desired report to be modified, and select Edit.
Update the fields as necessary.
Click Save to complete the update.

Deleting report definitions

Navigate to the Report Definitions tab of the main dashboard.
In the table, click the ellipses next to the desired report to be modified, and select Delete.
Click Delete Definition.

Deleting a report definition that currently has existing schedules causes those schedules to be removed from IDR.

Duplicating report definitions

Navigate to Report Definitions tab of the main dashboard.
In the table, click the ellipses next to the desired report to be duplicated.
Select Duplicate.

Once the report definition has been duplicated, the new duplicated report has the text copy appended as a suffix.

Ad-hoc report generation

After Report Definitions have been created, they can immediately be used to generate reports directly from the Report Definitions table using the following steps:

Navigate to the Report Definitions tab of the main dashboard.
In the table, locate the report definition to generate the report from and select the “action” to bring up a menu containing one of the following options:
1. View Report. Generates the report for viewing directly in ForgeRock Identity Reporting within the browser. The output of the report will be displayed in a table, which the user can sort by individual columns and navigate through multiple pages. After reviewing the output of the report, the user may also download and save a copy of the report in one of the other two formats using the buttons in the top right of the report view.
2. Download as PDF. Generates the report in the form of a PDF file to be downloaded to the client machine.
3. Download as CSV. Generates the report in the form of a CSV file to be downloaded to the client machine. This file can then be used for flat-file operations or loaded into spreadsheet software, such as Excel.
After selecting the format of the report, an additional prompt may appear if the report definition contains parameters. This allows the user who is running the report to enter specific values only for the current execution of the report, without affecting any other users that wish to make use of the same report definition. The generate button is enabled only when all the required values are provided.