Generate audit reports

Audit reports are intended to count similar records, usually over specified time periods. To facilitate time-based reports, audit data includes timestamps in ISO 8601 format (yyyy-MM-ddTHH:mm:ss). To aggregate the audit data for a particular time period, include these timestamps in a filtered query on the report/audit endpoint. You can use a UTC offset to specify different timezones.

The following example generates a report of recon audit events. The events are filtered to include only records with a timestamp value after (gt) October 1, 2017, and before (lt) October 31, 2017, both at midnight. In effect, this query generates a reconciliation report for the month of October, 2017.

The aggregateFields parameter determines which fields are included in the report. In the following example, the report includes the timestamp and status of each event. The timestamp shows the number of seconds since the Unix Epoch and the time in ISO 8601 format, with a utcOffset of -0700 (which corresponds to US Pacific Daylight Time).

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'http://localhost:8080/openidm/report/audit/recon?_queryFilter=timestamp+gt+"2017-10-01T00:00:00.0-0700"and+timestamp+lt"2017-10-31T00:00:00.0-0700"&aggregateFields=TIMESTAMP=/timestamp;scale:min;utcOffset:-0700,VALUE=/status'
{
  "result": [
    {
      "timestamp": {
        "epochSeconds": 1509361500,
        "iso8601": "2017-10-30T11:05:00.000Z"
      },
      "status": null,
      "count": 1
    },
    {
      "timestamp": {
        "epochSeconds": 1509361440,
        "iso8601": "2017-10-30T11:04:00.000Z"
      },
      "status": null,
      "count": 1
    },
    {
      "timestamp": {
        "epochSeconds": 1509361440,
        "iso8601": "2017-10-30T11:04:00.000Z"
      },
      "status": "SUCCESS",
      "count": 4
    },
    {
      "timestamp": {
        "epochSeconds": 1509361320,
        "iso8601": "2017-10-30T11:02:00.000Z"
      },
      "status": null,
      "count": 1
    },
    {
      "timestamp": {
        "epochSeconds": 1509361320,
        "iso8601": "2017-10-30T11:02:00.000Z"
      },
      "status": "SUCCESS",
      "count": 3
    },
    {
      "timestamp": {
        "epochSeconds": 1509361500,
        "iso8601": "2017-10-30T11:05:00.000Z"
      },
      "status": "SUCCESS",
      "count": 4
    }
  ],
  "resultCount": 6,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

You can further refine the audit report using an additional filter parameter, postAggregationFilter, to filter the aggregated audit results according to additional criteria. The postAggregationFilter parameter works in the same way as the queryFilter parameter.

The following example returns the same audit report generated previously, but filters the aggregated results to display only those records whose count parameter is more than 2:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'http://localhost:8080/openidm/report/audit/recon?_queryFilter=timestamp+gt+"2017-10-01T00:00:00.0-0700"and+timestamp+lt"2017-10-31T00:00:00.0-0700"&aggregateFields=TIMESTAMP=/timestamp;scale:min;utcOffset:-0700,VALUE=/status&postAggregationFilter=count+gt+2'
{
  "result": [
    {
      "timestamp": {
        "epochSeconds": 1509361440,
        "iso8601": "2017-10-30T11:04:00.000Z"
      },
      "status": "SUCCESS",
      "count": 4
    },
    {
      "timestamp": {
        "epochSeconds": 1509361320,
        "iso8601": "2017-10-30T11:02:00.000Z"
      },
      "status": "SUCCESS",
      "count": 3
    },
    {
      "timestamp": {
        "epochSeconds": 1509361500,
        "iso8601": "2017-10-30T11:05:00.000Z"
      },
      "status": "SUCCESS",
      "count": 4
    }
  ],
  "resultCount": 3,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

You can sort the audit report using the sortKeys property. The following example runs the same query as the previous example, but sorts the output according to the value of the iso8601 field (the precise date and time of the entry):

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
'http://localhost:8080/openidm/report/audit/recon?_queryFilter=timestamp+gt+"2017-10-01T00:00:00.0-0700"and+timestamp+lt"2017-10-31T00:00:00.0-0700"&aggregateFields=TIMESTAMP=/timestamp;scale:min;utcOffset:-0700,VALUE=/status&postAggregationFilter=count+gt+2&_sortKeys=timestamp/iso8601'
{
  "result": [
    {
      "timestamp": {
        "epochSeconds": 1509361320,
        "iso8601": "2017-10-30T11:02:00.000Z"
      },
      "status": "SUCCESS",
      "count": 3
    },
    {
      "timestamp": {
        "epochSeconds": 1509361440,
        "iso8601": "2017-10-30T11:04:00.000Z"
      },
      "status": "SUCCESS",
      "count": 4
    },
    {
      "timestamp": {
        "epochSeconds": 1509361500,
        "iso8601": "2017-10-30T11:05:00.000Z"
      },
      "status": "SUCCESS",
      "count": 4
    }
  ],
  "resultCount": 3,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The admin UI includes an Audit Events widget that generates basic time-based reports on audit data. For more information, see View Audit Events in the admin UI.

IDM 7.2.1

Generate audit reports