IAM

How to Create Custom Reports in WSO2 Identity Server Analytics | Tutorial

This article aims to provide the information required to create custom reports using the WSO2 Identity Server Analytics tool. 

For this purpose, details on  WSO2 Identity Server Analytics initialization are provided, as well as information on how to create an external data source for WSO2 IS Analytics.

Prerequisites for  Initializing WSO2 IS Analytics and Creating Custom Reports

To correctly initialize the analytics tool, the following steps must be taken:

1. Enable Analytics in WSO2 IS

The first step in this process is the editing of the dentity.xml file found in the <WSO2IS_HOME>/repository/conf/identity/ path. The following listeners are activated here:

Listener org.wso2.carbon.identity.data.publisher.application.authentication.AuthnDataPublisherProxy
Purpose This listener is necessary to enable both session and login analytics.
Setting <EventListener type=”org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler”

name=”org.wso2.carbon.identity.data.publisher.application.authentication.AuthnDataPublisherProxy”

orderId=”11″ enable=”true”/>

 

Listener org.wso2.carbon.identity.data.publisher.application.authentication.impl.DASLoginDataPublisherImpl
Purpose This listener should only be enabled if you wish to analyze statistics relating to attempted logins via WSO2 IS.
Setting <EventListener type=”org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler”

name=”org.wso2.carbon.identity.data.publisher.application.authentication.impl.DASLoginDataPublisherImpl”

orderId=”10″ enable=”true”/>

 

Listener org.wso2.carbon.identity.data.publisher.application.authentication.impl.DASSessionDataPublisherImpl
Purpose This listener should only be enabled if you wish to analyze session-specific statistics for WSO2 IS Analytics.
Setting

<EventListener type=”org.wso2.carbon.identity.core.handler.AbstractIdentityMessageHandler”

name=”org.wso2.carbon.identity.data.publisher.application.authentication.impl.DASSessionDataPublisherImpl”

orderId=”11″ enable=”true”/>

2. Initialize the Worker Node

To initialize the Worker Node, go to the <WSO2IS-ANALYTICS_HOME>/bin/ path.

Run the following command:

On Windows:  worker.bat

On Linux: ./worker.sh

3. Initialize the Dashboard Node

To run the Dashboard Node, go to the <WSO2IS-ANALYTICS_HOME>/bin/ path.

Run the following command:

On Windows:  dashboard.bat

On Linux: ./dashboard.sh

4. Creating an External Data Source

The new data source should be added to the so2.datasources fragment. This is located in the deployment.yaml file, which can be found in the <ISA_HOME>/conf/dashboard/ path. It must include the following information:

Parameter Description
name Data source name.  Example: WSO2EVENTUSER
description  Brief comment on the data source.
JndiConfig
name  Name by which the jndi is identified. Example: jdbc/WSO2EVENTUSER
definition
type  Type of database. Example: RDBMS
configuration
jdbcUrl URL where the database is hosted. Example: jdbc:mysql:/{/LOCALHOST}:{PORT}/WSO2EVENTUSER?useSSL=false
username  Database username. Example: root
Password  Database user password. Example: root
driverClassName Driver class used for connecting to the database. Example: com.mysql.jdbc.Driver
maxPoolSize  Maximum number of connections permitted. Example: 50
idleTimeout  Wait time for inactive sessions in milliseconds. Example: 60000
validationTimeout  Wait time for resource validation in milliseconds. Example: 30000
isAutoCommit Each and every statement through the connection will be run via a separate and implicit transaction. Example: false
    description: "The data source used for WSO2 IS Analytics statistics"
    jndiConfig:
      name: jdbc/WSO2EVENTUSER
    definition:
      type: RDBMS
      configuration:
        jdbcUrl: 'jdbc:mysql://{LOCALHOST}:{PORT}/WSO2EVENTUSER?useSSL=false'
        username: root
        password: root
        driverClassName: com.mysql.jdbc.Driver
        maxPoolSize: 50
        idleTimeout: 60000
        validationTimeout: 30000
        isAutoCommit: false</code data-language="yaml">

The Dashboard Node service must be restarted to complete the process.

Go to the  https://localhost:9643/portal/ URL to log in to the Analytics portal.

Enter the user credentials, which by default are:

User name: admin

Password: admin

Once  inside the portal, the configured dashboards and the options for creating widgets and dashboards will be shown.

5. Creating a Widget

Click on Create Widget to create a new widget. You will be asked to assign a name to it.

A list of options that WSO2 IS Analytics manages by default will then appear, in this case RDBMS Batch Data Provider is used as an example.

Continuing with this step, you will be asked for the following data:

Parameter Value
Data source name, found in the deployment.yaml file, in the <ISA_HOME>/conf/dashboard/ path. WSO2EVENTUSER
The query through which information for the report will be obtained. SELECT * FROM EVENT_USER

As additional data, you can  create a query with parameters. In order to do so, you must define the default values the parameters will have, as shown in the previous image.

Next, you will be asked for information regarding the table to which the query relates, such as:

Parameters Description
Table Name The name of the table.Example: EVENT_USER
Incremental Column Column with incremental data.Example: ID
Time Columns Column that includes the date in long format.

Once this step is completed,  click  NEXT.

 A list of the various custom reports that can be created on the tool will then be shown. By way of example, the TABLE CHART option will be selected.

Here the columns used in the query that was input in previous steps will be shown. You can configure the following actions in these columns:

Parameter Description
Select Column If you wish to see the column in the report.
Enable Color Based Categorization If you want to group cells together in the same color.
Title of the Column Column title you wish to include on the custom report.
Time formatting regex if the column contains time series data Regex that defines the column date format Example: %d/%m/%Y %H:%M:%S
Color of Text in Cell Define the color desired for  cell text.
Color set to use in the charts Define the color desired for a group of cells.
If certain categories are required to be grouped in a certain color Define the group of cells you wish to apply a previously defined color to.

Next, a series of options will appear regarding the table generated for the report, which define the following aspects in order:

  • Maximum number of rows you can handle in a table.
  • If you wish to handle table paging.
  • If you wish for the table to filter its information.
  • If you wish for the table to cover the rows defined in the previous step. Not recommended.

In order to confirm that the settings are correct, click the PREVIEW button.

Once the settings are ready, click CREATE to generate the report.

6. Creating a Dashboard

Once you have a new Widget, you can create a new Dashboard. Just as when creating a new Widget, click on the CREATE DASHBOARD option on the portal home page.

You will see a form that asks for the following information:

Parameter Description
Name of your Dashboard Name of the new Dashboard.
URL Name of the Dashboard in lower case and without spaces.
Description Brief comment on the functionality or the area the report covers.

Once  the form is complete,  click on the ADD button to create a new Dashboard.

You will then be redirected to the portal home page, where you will select the new Dashboard in the Design form.

It will show the workspace where the reports are stored. There are 2 options in the menu:

  • The first is to set up the Dashboard site.

  • The second is to add  widgets.

If you choose the widgets option, the components can simply be dragged into  place  on the workspace.

You can link them if the widget has entry parameters. For example, with DATE TIME in Analytics.

Steps to implement WSO2 in your company

Discover all you need to know to integrate your business' systems with WSO2 with our guide. Include cases studies!

Written By

Pablo Ramos

ICT consultant