Query Audit Trail

  • Can return system wide audit trail records.

  • Can return audit trail records in the context of objects.

  • Returns by default the last 1000 system wide audit trail records or the last 1000 records per object.

  • Returns the audit trail records in descending order. Based on the timestamp field (ts) of the records.

  • Accepts a start time and end time to define a time period to query audit data for.

  • Supports MongoDB options limit and skip.

  • Requires System-wide Reviewer audit trail role or Limited Reviewer audit trail role and READ permission for the object(s) provided in the request.

  • Requires System-wide Reviewer audit trail role in case no objects are provided in the request.

  • HTTP methods supported: GET, POST.

Description

This endpoint allows to query audit trail records for one single or multiple objects or system wide audit trail records.

Parameters

Name Type Optional Description

items / identifier

object

yes

An array of objects which contain a path or ID of the object to be queried for audit trail records.

start_time

string

yes

The start time (UTC) of the interval to retrieve audit trail records for. By default not set.

end_time

string

yes

The end time (UTC) of the interval to retrieve audit trail records for. By default not set.

limit

integer

yes

The maximum number of audit trail records per item (if provided) or query to return. By default 1000. A limit of 0 means no limit.

skip

integer

yes

The number of audit trail records per item (if provided) or query to skip from the result. By default not set.

insights

boolean

yes

Indicates application insights should be included in the response. By default false.

In a HTTP POST request the parameters start_time, end_time, limit and skip can be provided as an URL query parameter and as a field in an audit trail query in the request body. In case a parameter is defined in a query in the request body, the corresponding URL query parameter will be ignored for that specific audit trail query.

Examples

Single query to fetch all audit trail records of one object

Example to query audit trail records of one object. By default this endpoint returns all audit trail records stored in the system for the provided object.

HTTP GET

Request URL

  • /api/v2/queryaudittrail?identifier=/System/Core/Examples/Demo Data/Process Data/DC4711

HTTP POST

Request URL

  • /api/v2/queryaudittrail

Request body

The following example contains a read file query, which contains one single item.

{
    "items": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
        }
    ]
}
Response body
{
    "data": {
        "audit_trail_data": {
            "query_data": [
                {
                    "items": [
                        {
                            "audit_trail_records": [
                                {
                                    "_id": "5ed799d4b04500004f070ed9",
                                    "change": {
                                        "changer": "$sci(so)",
                                        "changerid": 281474978545664,
                                        "channelid": 363,
                                        "cur": "{\n\"path\" : \"/System/Core/Examples/Demo Data/Process Data/DC4711\",\n\"objid\" : 281475022258176,\n\"parentid\" : 281475021996032,\n\"class\" : 125,\n\"GenLuaScript.AdvancedLuaScript\" : \"local libHelpers = require\"inmation.SampleHelpers\"\r\nlocal path = syslib.getself():path()\r\nlocal min = syslib.getvalue(path .. \".Limits.OpcRangeLow\")\r\nlocal max = syslib.getvalue(path .. \".Limits.OpcRangeHigh\")\r\nlocal curr = syslib.getvalue(path)\r\nreturn libHelpers.GetNextRandomValue(min, max, curr, nil)\",\n\"ObjectName\" : \"DC4711\",\n\"ObjectDescription\" : \"Simulated_Density\",\n\"OpcEngUnit\" : \"g/cm³\",\n\"Limits.OpcRangeHigh\" : 20.000000,\n\"Limits.OpcLimitLow\" : 1.000000,\n\"Limits.OpcLimitHigh\" : 10.000000,\n\"GenerationPeriod\" : 30000,\n\"GenerationType\" : 5,\n\"ArchiveOptions.ArchiveSelector\" : 2,\n\"ArchiveOptions.StorageStrategy\" : 1,\n\"Location.LocationStrategy\" : 2,\n\"Location.Longitude\" : 6.936125,\n\"Location.Latitude\" : 50.906476\n}",
                                        "op": 3,
                                        "prev": "{\n\"path\" : \"/System/Core/Examples/Demo Data/Process Data/DC4711\",\n\"objid\" : 281475022258176,\n\"parentid\" : 281475021996032,\n\"class\" : 125,\n\"GenLuaScript.AdvancedLuaScript\" : \"local libHelpers = require\"inmation.SampleHelpers\"\r\nlocal path = syslib.getself():path()\r\nlocal min = syslib.getvalue(path .. \".Limits.OpcRangeLow\")\r\nlocal max = syslib.getvalue(path .. \".Limits.OpcRangeHigh\")\r\nlocal curr = syslib.getvalue(path)\r\nreturn libHelpers.GetNextRandomValue(min, max, curr, nil)\",\n\"ObjectName\" : \"DC4711\",\n\"ObjectDescription\" : \"Simulated Density\",\n\"OpcEngUnit\" : \"g/cm³\",\n\"Limits.OpcRangeHigh\" : 20.000000,\n\"Limits.OpcLimitLow\" : 1.000000,\n\"Limits.OpcLimitHigh\" : 10.000000,\n\"GenerationPeriod\" : 30000,\n\"GenerationType\" : 5,\n\"ArchiveOptions.ArchiveSelector\" : 2,\n\"ArchiveOptions.StorageStrategy\" : 1,\n\"Location.LocationStrategy\" : 2,\n\"Location.Longitude\" : 6.936125,\n\"Location.Latitude\" : 50.906476\n}"
                                    },
                                    "comment": "Changed object description",
                                    "obj": {
                                        "classver": 566562020917248,
                                        "configver": 4,
                                        "level": 6,
                                        "objid": 281475022258176
                                    },
                                    "ts": 1591187924456,
                                    "type": 1
                                }
                            ],
                            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
                        }
                    ],
                    "query_index": "1"
                }
            ]
        }
    }
}

Single query to fetch audit trail records in a specific time period of multiple objects

Example to query audit trail records of multiple object in a specific interval.

HTTP GET

Request URL

  • /api/v2/queryaudittrail?identifier=/System/Core/Examples/Demo Data/Process Data/DC4711&identifier=/System/Core/Examples/Demo Data/Process Data/DC666&start_time=2020-06-01T00:00:00.000Z&end_time=2020-06-04T00:00:00.000Z

HTTP POST

Request URL

  • /api/v2/queryaudittrail

Request body

The following example contains one query to fetch audit trail records for multiple objects.

{
    "items": [
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
        },
        {
            "p": "/System/Core/Examples/Demo Data/Process Data/DC666"
        }
    ],
    "start_time": "2020-06-01T00:00:00.000Z",
    "end_time": "2020-06-04T00:00:00.000Z"
}
Response body

The response structure is the same as in the first example.

Query the last changes for multiple objects in one single request

Example for retrieving the audit trail records corresponding to the last changes for multiple objects in a specific time period.

HTTP POST

Request URL

  • /api/v2/queryaudittrail

Request body

The following example contains two queries.

{
    "queries": [
        {
            "items": [
                {
                    "p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
                }
            ],
            "start_time": "2020-06-01T00:00:00.000Z",
            "end_time": "2020-06-04T00:00:00.000Z",
            "limit": 1
        },
        {
            "items": [
                {
                    "p": "/System/Core/Examples/Demo Data/Process Data/DC666"
                }
            ],
            "start_time": "2020-06-01T00:00:00.000Z",
            "end_time": "2020-06-04T00:00:00.000Z",
            "limit": 1
        }
    ]
}
Response body

The response structure is the same as in the first example except the fact that the query_data field contains two elements.

{
    "data": {
        "audit_trail_data": {
            "query_data": [
                {
                    "items": [
                        {
                            "audit_trail_records": [],
                            "p": "/System/Core/Examples/Demo Data/Process Data/DC4711"
                        }
                    ],
                    "query_index": "1"
                },
                {
                    "items": [
                        {
                            "audit_trail_records": [],
                            "p": "/System/Core/Examples/Demo Data/Process Data/DC666"
                        }
                    ],
                    "query_index": "2"
                }
            ]
        }
    }
}

Query system wide audit trail records in a specific time period.

Example for retrieving the last 2 system wide audit trail records in a specific time period.

HTTP GET

Request URL

  • /api/v2/queryaudittrail?start_time=2020-06-01T00:00:00.000Z&end_time=2020-06-04T00:00:00.000Z&limit=2

HTTP POST

Request URL

  • /api/v2/queryaudittrail

Request body

The following example contains the options start_time, end_time and limit to return maximum 2 audit trail records instead of the default of 1000 records.

{
    "start_time": "2020-06-01T00:00:00.000Z",
    "end_time": "2020-06-04T00:00:00.000Z",
    "limit" : 2
}
Response body

System-wide audit trail records are returned as an array in the 'audit_trail_records' field on root level of a query data item.

{
    "data": {
        "audit_trail_data": {
            "query_data": [
                {
                    "audit_trail_records": [
                        {
                            "_id": "5ee1e33d600100008901a0fa",
                            "channelid": 194,
                            "comptype": 5,
                            "env": {
                                "inmuser": "<n/a>",
                                "remoteaddr": "127.0.0.1:212",
                                "remotehost": "inmbnx-vm01"
                            },
                            "obj": {
                                "objid": 281474977497088
                            },
                            "subtype": 2,
                            "ts": 1591862077138,
                            "type": 21
                        },
                        {
                            "_id": "5ee1e33d600100008901a0f4",
                            "channelid": 193,
                            "comptype": 5,
                            "env": {
                                "inmuser": "<n/a>",
                                "remoteaddr": "127.0.0.1:65491",
                                "remotehost": "inmbnx-vm01"
                            },
                            "obj": {
                                "objid": 281474977497088
                            },
                            "subtype": 2,
                            "ts": 1591862077034,
                            "type": 21
                        }
                    ],
                    "query_index": "1"
                }
            ]
        }
    }
}