Audit Logging API

Overview

Audit logging is a service that captures all user or system actions in the ABB Ability™ Platform. This service is currently available at the instance level of the Platform, with global and regional levels planned as upcoming features. Capturing actions is done by consuming events that are produced by the services within the Platform.

For an overview of the event types that can be emitted by the Platform, see the detailed reference material and examples on the audit logging reference page.

QEL support

The API supports Query Expression Language.

GET Query Logs

/audit

Description

Search for platform events in audit logging storage.

Filterable Properties

Filter	Description	Example
correlationid	ID assigned to all related Platform Events	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
event	Type of Platform Event	Granted
principal.id	ID the principal used in the associated action	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
principal.type	Principal type used in the associated action	device
resource.id.appid	Application ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.contractid	Contract ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.cpid	Connectivity Provider ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.deviceid	Device ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.grantid	Grant ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.groupid	Group ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.idpid	Identity Provider ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.method	Method invoked by the associated resource	myMethodName
resource.id.model	Model of the associated resource	abb.ability.sampleDevice
resource.id.objectid	Object ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.operationid	Name of the performed operation	queryGraph
resource.id.parentid	Parent ID of the resource, in the case of child resources	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.path	Path to a file, for File Platform Events	path/to/file.txt
resource.id.principalid	ID of the principal of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.principaltype	Principal type of the associated resource	user
resource.id.reference	Reference type of the associated resource. Full reference information information will be returned in the data.to node	device
resource.id.roleid	Role ID of the resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.scope	Scope of the action	instance
resource.id.solutionid	Solution ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.tenantid	Tenant ID of the associated resource	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
resource.id.type	Type definition name of the associated resource	abb.ability.sample.device
resource.id.version	Version of the type definition of the associated resource	1.0.0
resource.type	Namespace of the generated Platform Event	Abb.Ability.Access
tenantid	ID of the tenant where the Platform Event was generated	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (GUID)
timestamp	Timestamp of the Platform Event	2020-01-01T12:00:00.0000Z

Parameters

Parameter	Mandatory	Description	Data Type
filter	Yes	QEL expression to filter audit log entries	String
limit	No	Limit the number of returned values. Default is 100.	Integer

QEL operators

Currently, our querying API supports all QEL operators except for HAS and ENDS_WITH.

Date Time format

In order to filter using the dateTime field, a specific format must be followed. Arguments should be supplied as a string prefixed with dt, and contain a millisecond scale between 2 and 6 decimal values. For example, timestamp > dt'2020-01-01T12:00:00.000Z'

Responses

Code	Description	Schema
200	Success	AuditLogQueryResponse
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
401	Not Authorized. Either the Access token is missing or the access token validation failed
403	Access Forbidden. Requesting entity does not have enough permissions to access the resource
429	Too many requests - indicates the user has sent too many requests in a given amount of time	ServiceErrors
500	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

API Output Example:

{
  "hasMore": false,
  "data": [
    {
      "correlationId": "a2e63d9e-83aa-4ec7-bd9d-7c4edaf45ee4",
      "event": "Abb.Ability.ModelDefinition.Created",
      "identityProvider": {
        "id": null,
        "type": null
      },
      "principal": {
        "id": "test-audit-logging-principalId-6bd16d98-b913-487e-a4d9-9ad3fee09875",
        "type": "user"
      },
      "resource": {
        "id": {
          "model": "Test model"
        },
        "type": "Abb.Ability.ModelDefinition"
      },
      "timestamp": "2019-08-07T10:52:19.271Z",
      "data": {}
    },
    {
      "correlationId": "a2e63d9e-83aa-4ec7-bd9d-7c4edaf45ee4",
      "event": "Abb.Ability.Access.Granted",
      "identityProvider": {
        "id": null,
        "type": null
      },
      "principal": {
        "id": "test-audit-logging-principalId-6bd16d98-b913-487e-a4d9-9ad3fee09875",
        "type": "user"
      },
      "resource": {
        "id": {
          "tenantId": "dec09db3-b8d2-41c3-a1c2-77546b808df7",
          "principalId": "test-audit-logging-principalId-6bd16d98-b913-487e-a4d9-9ad3fee09875",
          "scope": "TestScope",
          "operationId": "test-audit-logging-operationId-1d9fce28-3846-48f8-a483-6feddddfa366",
          "principalType": "user"
        },
        "type": "Abb.Ability.Access"
      },
      "timestamp": "2019-08-07T10:52:18.722Z",
      "data": {}
    }
  ]
}