Data sources

Data sources are used to specify where the source of information retrieved by report definitions and also include the necessary connection details for that source. ForgeRock Identity Reporting supports database and Application Programming Interface (API) data source types.

Creating new data sources

Navigate to the Data Sources tab of the main dashboard.
Click Create Data Source.

On the Create Data Sources page, fill in each of the required fields.

Additional details on the available fields are given below:

Name. (Required) Name of the data source that appears in the table and in the list of available data sources on Report Definition forms.
Description. Provides additional information about the data source and the connection being made.

Type. (Required) Specifies the type of data source, which determines the available connection parameters.

Data source types in the "Create New Source" page

Options are:

Local. The default data source type that uses IDM’s local database repository. If Local is selected, no additional parameters are required as the connection details are pulled directly from IDM.
MySQL, PostgreSQL, Oracle, SQL Server, DB2. Data sources that use database-specific jdbc drivers to connect to a remote database.

When one of these types is selected, the following parameters become available for user input on the form:
- Host. (Required) The IP or hostname of the server where the remote database is hosted.
- Port. (Required) The port on which the remote database is listening on for incoming connections.
- Database name. (Required) The name of the database instance that is being connected with.
- Username. (Required) The username of the account with which the connection is being made. It is highly recommended to use a service account with read-only access.
- Password. (Required) The password of the account with which the connection is being made.

API. This data source connects to an available API service, which must be reachable by the IDM deployment on which IDR is installed. Queries can be executed against the specified API to retrieve the desired data.

API fields in the "Create New Source" when type "API" is selected

When the API data source type is selected, the following parameters become available for user input on the form:

Base URL. The root path of the API service that the data source connects to. Any report definitions created for this data source extends this path for the desired call.

Authentication Type. There are three API data source authentication types supported by IDR:

None. No specific authentication method is required in the hyper text transfer protocol (HTTP) call to the service. This applies to unauthentication services as well as those that are header-based, for exaxmple, API keys, as those methods can be handled using the headers information (described below).
Basic. Basic username and password credentials, base64 encoded, and sent as an Authentication header.
- Authentication Username. The username to authenticate with.
- Authentication Password. The password to authenticate with.

Bearer. Authentication through a bearer token, which is retrieved through a separate endpoint call, and is included with each API call that is executed.

Authentication URL. The full path to the authentication endpoint that must be called to retrieve the bearer token.

Authentication Body. The full payload that must be sent to the authentication endpoint to retrieve the bearer token.

When the Authentication Type is set to Bearer, the field must contain a payload to authenticate in JSON format as follows:

{
   "username": "john.doe@forgerock.com",
   "password": "Welcome123"
}

Headers. A list of key/value pairs sent as headers with each representation state transfer (REST) call. These headers are included, by default, in every report definition that uses this data source. It can be used for alternate authentication methods, or to define globally used headers in a single place, as opposed to defining headers on every report definition.

For example, if you are connecting to IDM from IDR, use the native IDM headers to authenticate.
Query Parameters. A list of key/value pairs sent as query parameters with each REST call. By default, these parameters are included in every report definition that uses this data source. It can be used to define globally used parameters in a single place, as opposed to defining headers on every report definition.
Enable POST. When selected, report definitions for this data source are allowed to be created with the HTTP method POST. If disabled, only the HTTP method GET will be allowed.
Enable openidm. The IDR report definitions use a transformation script to take the results of an API call and transforms them into a payload that IDR expects. Since these transformation scripts run within the IDM script engine, the openidm object can be made available to the report definition. This allows for complex transformations and enrichment of the report data to take place. When this is not selected, transformation scripts that reference the openidm object are not accepted and its use is disabled. It is recommended that his option be turned off and exposed only in data sources that are available with the proper authorization to use it.

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

At any point during or after this process, use “Test Connection” and a connection is made using any supplied information on the form. It is recommended to test the connection after completing the form prior to before saving the details.
For API data sources, a field marked API Endpoint Test Connection is available in order to provide a complete test endpoint (appended to the Base URL) that IDR can attempt to call to. This field will not persist on the data source.

Modifying data sources

Navigate to the Data Sources tab of the main dashboard.
In the table, select the data source to be modified.
Update the fields as necessary. You are unable to edit a Data Source’s type.
Click Save to complete the update.

A created data source cannot modify its type once it is created. A new data source must be created to do this.

Deleting data sources

Delete individual data sources:

Navigate to the Data Sources tab of the main dashboard.
In the table, click the ellipses to the right of the data source you wish to delete.
Click Delete.
Select Delete Data Source to confirm the deletion.

A data source that currently has existing report definitions cannot be deleted. The administrator of the data source owner must first delete all existing report definitions for the specified data source, before the data source itself can be deleted.