20.2. Reporting¶

Starting with LinOTP 2.9 a new reporting API was introduced. It can be used to query information about the number of tokens. This can be useful for accounting in multitenancy environments or statistical purpose.

The comprehensive API documentation can be found here:

https://www.linotp.org/doc/api/linotp.controllers.reporting.html

The basic API call is:

https://<LINOTP>/reporting/<ReportingController>?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]

The available controllers are:

show: displays historical count data
maximum: displays highest values counted
delete_all: clean the counter database
delete_before: delete all values in the counter database recorded before a defined date

Tip

Detailed information about the handling of the session cookie can be found at System Controller

20.2.1. Prerequisites¶

The reporting API can be accessed by the token managers. The available queries have to be configured before via policies as described in Reporting Policies.

Tip

After adding new states to be recorded in the policies the next count will be performed after an event was triggered potentially changing the counted value. So for example if a new token is enrolled the counters are recalculated and can be queried.

20.2.2. Perform Queries¶

20.2.2.1. show¶

Displays the token counters recorded over time. The output can be filtered regarding the token states and the realms.

https://<LINOTP>/reporting/show?session=SESSIONCOOKIE[&PARAM1][&PARAM2][..]

Available parameters:

realms [optional]: Limit the counter output to the given realms.
status [optional]: Limit the counter output to tokens with of certain states.

Explanation of the available token states:

active: counts only active tokens
inactive: counts only deactivated tokens
assigned: counts only tokens assigned to users
unassigned: counts only tokens which are not assigned to any user
active&assigned: counts tokens which are activ and assigned to an user
active&unassigned: counts active tokens which are not assigned to any user
inactive&assigned: counts disabled tokens assigned to users
inactive&unassigned: counts disabled tokens which are not assigned to any user

Tip

Please make sure to use exactly the same token states for the queries as defined in the reporting policies (Reporting Policies)

Displays all available historical numbers of all tokens of all states

https://<LINOTP>/reporting/show?session=SESSIONCOOKIE

Example

https://linotp.example.net/reporting/show?session=45e939b02[...]

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 30,
           "report_rows": 30
        },
        "data": [
           {
              "count": 132,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "active",
              "event": "token_tokenrealm"
           },
           {
              "count": 150,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "total",
              "event": "token_tokenrealm"
           },
[...]

Display token counts for certain realms

https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&realms=REALMA,REALMB

Example

Show token count numbers for ‘realm1’ and ‘realm2’:

https://linotp.example.net/reporting/show?session=45e939b02[...]&realms=realm1,realm2


{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 30,
           "report_rows": 30
        },
        "data": [
           {
              "count": 132,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "active",
              "event": "token_tokenrealm"
           },
           {
              "count": 150,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-25 13:27:47",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "total",
              "event": "token_tokenrealm"
           },
[...]

           {
              "count": 300,
              "realm": "realm2",
              "description": "",
              "timestamp": "2016-07-25 13:27:54",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "active",
              "event": "token_tokenrealm"
          },
[...]
}

Display token count numbers for certain states

https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]

Example

Show count numbers for unassigned active tokens:

https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 6,
           "report_rows": 6
        },
        "data": [
           {
              "count": 11,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 11:37:58",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&active",
              "event": "token_enable"
           },
           {
              "count": 12,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 13:00:10",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&active",
              "event": "token_init"
           },
[..]
}

Display count numbers for tokens of a certain states from particular realms

https://<LINOTP>/reporting/show?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]

Example

Show count numbers for unassigned+active and unassigned+inactive tokens from ‘realm1’:

https://linotp.example.net/reporting/show?session=45e939b02[...]&status=unassigned%26active,unassigned%26inactive&realms=realm1

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "resultset": {
           "page": 1,
           "pages": 1,
           "pagesize": 12,
           "report_rows": 12
        },
        "data": [
           {
              "count": 0,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 11:37:58",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&inactive",
              "event": "token_enable"
           },
           {
              "count": 8,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 11:37:58",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&active",
              "event": "token_enable"
           },
           {
              "count": 0,
              "realm": "realm1",
              "description": "",
              "timestamp": "2016-07-26 13:00:10",
              "detail": "",
              "value": "",
              "session": "",
              "parameter": "unassigned&inactive",
              "event": "token_init"
           },
[..]
}

20.2.2.2. maximum¶

Display the highest number counter for token of a certain state in realms.

https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE[&realms=REALMA,REALMB,...][&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]

Available parameters:

status [optional]

realms [optional]

Show total number of tokens

https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE

Example

Show highest numbers of total tokens counted for all realms:

https://linotp.example.net/reporting/maximum?session=45e939b02[...]

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "realm1": {
           "total": 270
        },
        "realm2": {
           "total": 178
        }
     }
  },
  "id": 1
}

Show number of tokens of certain states

https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE&status=STATEA[%26STATEB][,STATEC[%26STATED]]

Example

Show highest numbers counted of inactive tokens for all realms:

https://linotp.example.net/reporting/maximum?session=45e939b02[...]&status=inactive

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "realm1": {
           "inactive": 25
        },
        "realm2": {
           "inactive": 13
        }
     }
  },
  "id": 1
}

Show number of tokens of certain states from specific realms

https://<LINOTP>/reporting/maximum?session=SESSIONCOOKIE&realms=REALMA[,REALMB][..]status=STATEA[%26STATEB][,STATEC[%26STATED]][..]

Example

Show highest numbers counted of unassigned or inactive tokens for ‘realm1’:

https://linotp.example.net/reporting/maximum?session=45e939b02[...]&status=inactive,unassigned&realms=realm1

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": {
        "realm1": {
           "unassigned": 15,
           "inactive": 25
        }
     }
  },
  "id": 1
}

20.2.2.3. delete_all¶

Delete all counters from database.

https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all[&realms=REALMA[,REALMB][..]]
[&status=STATEA[%26STATEB][,STATEC[%26STATED]][..]]

Available parameters:

status [optional]

realms [optional]

Delete all count data

https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all

Example

https://linotp.example.net/reporting/delete_all?session=45e939b02[...]

{
  "version": "LinOTP 2.9rc2",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 586
  },
  "id": 1
}

Delete token counter of selected realms

https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all&realms=REALMA[,REALMB][..]

Example

Delete all tokens counter from realm1:

https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&realms=realm1

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 432
  },
  "id": 1
}

Delete token counter for selected states

https://<LINOTP>/reporting/delete_all?session=SESSIONCOOKIE&delete_all&status=STATEA[%26STATEB][,STATEC[%26STATED][..]

Example

Delete all tokens counter of the state inactive or disabled:

https://linotp.example.net/reporting/delete_all?session=45e939b02[...]&status=inactive,disable

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 18
  },
  "id": 1
}

20.2.2.4. delete_before¶

Delete entries from the database before a given date. The removal can be optionally selective regarding the realm and the token states.

https://<LINOTP>/reporting/delete_before?session=SESSIONCOOKIE&date=YYYY-MM-DD[&realms=REALMA,REALMB,...]
[&status=STATEA[%26STATEB][,STATEC[%26STATED]][,[..]]]

Available parameters:

date: the date before counters are deleted in format YYYY-MM-DD

status [optional]

realms [optional]

Example

Remove all count data recorded before 2016-07-22:

https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&date=2016-07-22

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 157
  },
  "id": 1
}

Example

Remove count data for all active token from realm1 recorded before 2016-07-26:

https://linotp.example.net/reporting/delete_before?session=45e939b02[...]&status=active&realms=realm1&date=2016-07-26

{
  "version": "LinOTP 2.9",
  "jsonrpc": "2.0802",
  "result": {
     "status": true,
     "value": 68
  },
  "id": 1
}

20.2. Reporting¶

20.2.1. Prerequisites¶

20.2.2. Perform Queries¶

20.2.2.1. show¶

20.2.2.2. maximum¶

20.2.2.3. delete_all¶

20.2.2.4. delete_before¶

Table of Contents

Search