# Using the Audit Logging API

The Audit Logging API is provided as a method for clients to retrieve information about events that have occurred within a system. By default, the ABB Ability™ Platform tracks and stores events that may be associated with authorization attempts, API calls, actions taken, or other interactions with the platform.

This tutorial will show how you interact with the Audit Logging API, and how to filter and retrieve specific information.

# Before You Start

Familiarize yourself with HTTP GET requests.
Install your favorite API testing tool.
It is suggested, but not required, to be familiar with Type Definitions and their life cycle before proceeding. More information can be found in the Type Definitions section of the Developer Portal.
You must have permission to access the /audit endpoint of your Instance API, and the appropriate authorization token containing this access level.
You should be familiar with principal types in the context of multitenancy. More information can be found in the multitenancy terminology documentation.

Sample Results

All result sets presented in this document are sample information, and will not match the information that you might see retrieved in your system. This is normal, as the platform events generated in each system will be different.

# Retrieving Events

# Input Arguments

As shown in the Instance API documentation for the /audit endpoint, a client interacts with the Audit Logging API via a GET request. One parameter is required, filter, and an additional limit parameter can optionally be supplied.

The filter parameter is a collection of boolean statements used to filter the retrieved result set. Using the information from the linked API documentation page above, we can construct filters such as:

resource.type STARTS_WITH 'Abb.Ability.ObjectModel'
principal.type = 'device'
resource.type STARTS_WITH 'Abb.Ability.ObjectModel' AND principal.type = 'device'

It is possible to join filters together in order to create specific filters, in turn retrieving specific information.

The limit parameter is an optional parameter that limits the returned data to a specific number. If this value is not supplied, the limit is set to 100 by default.

# Making the API Call

In this example, we will tracing the events that occurred when a new Type Definition was created within a system. Within the list of Platform Events, we can see that there are specific namespaces for Type Definitions. There are a few important pieces of information to take from this documentation.

The namespace of type definition events is Abb.Ability.TypeDefinition.
There are individual event types for Created, Updated, and Deleted events.
All type definition events return information containing resource.id, resource.id.version, resource.id.model, and resource.id.name, in addition to the normal information returned by the audit logging API.

Using this information, a filter can be constructed to retrieve information about type definition events. Specifically, we are going to retrieve Created events from the Abb.Ability.TypeDefinition namespace.

According to the API documentation, we are able to filter on the event property, which maps to the platform event type, and resource.type, which maps to the namespace of the platform event. Combining these, our filter would be resource.type = 'Abb.Ability.TypeDefinition' AND event = 'Created'. This information can be submitted to the /audit endpoint via a cURL command, or your favorite API testing tool.

Limit

In addition to the filter created above, you may add the limit parameter to your request if desired. As it is an optional parameter, it is not shown here. The proper format would be filter=filterValue&limit=#.

curl -X GET "https://abiapiapmxxxxxxxxxxx.abilityplatform.abb/v1/audit?filter=resource.type%20%3D%20%27Abb.Ability.TypeDefinition%27%20and%20event%20%3D%20%27Created%27"
    -H "accept: application/json"
    -H "Authorization: Bearer <TOKEN>"

Sample Values

In the code example above, the URL and Bearer token are shown as example values. To make a proper API call, you will need to replace these values with the values appropriate for your environment.

# Reading Returned Data

On a successful submission, a 200 response code will be returned. The data returned will vary by environment. If a corresponding event exists in your environment, you should see data similar to the following.

{
  "hasMore": true,
  "data": [
    {
      "correlationId": "d8ae13b7-eb92-4a76-be34-a965a2c482b0",
      "event": "Created",
      "principal": {
        "id": null,
        "type": null
      },
      "resource": {
        "id": {
          "model": "abb.ability.cst.demo.device",
          "version": "1.0.0",
          "type": "abb.ability.cst.demo.sample.device"
        },
        "type": "Abb.Ability.TypeDefinition"
      },
      "timestamp": "2020-01-31T12:00:00.000Z",
      "data": {
        // The type definition schema will be returned here. This has been removed for brevity.
      }
    }
  ]
}

# Platform Event Data

Every platform event logged contains standard information that is not unique by event type. The purpose of that information, and an explanation of the values shown in the example data, can be found in the following table.

Node	Purpose	Sample Value Explanation
hasMore	Indicates if additional data exists beyond the specified `limit` input parameter	A value of `true` indicates more data exists
data.correlationId	ID used to tie together events that occurred as a result of the same action	GUID representation of the correlation ID
data.event	The event type of the platform event	Since `Created` was specified in the filter, this is what was retrieved
data.principal.id	The principal ID of the associated event	Type Definitions exist outside of principal management, so there is no ID
data.principal.type	The principal type of the associated event	Type Definitions exist outside of principal management, so there is no type
resource.type	The event namespace in which the event occurred	Since `Abb.Ability.TypeDefinition` was specified in the filter, this is what was retrieved
timestamp	The date and time the event occurred	This event occurred on January 31st, 2020 at 12:00:00
data	The data node holds the payload information specified by the event type	Payload is specified by the `Abb.Ability.TypeDefinition.Created` definition

# Event Type Data

Each event contains information that is included based on the type of the event. The purpose of that information, and an explanation of the values shown in the example data, can be found in the following table, and in the associated event namespace documentation. For this example, we are examining the Abb.Ability.TypeDefinition.Created event.

Node	Purpose	Sample Value Explanation
resource.id.model	Model definition of the object	The model used for this type definition is `abb.ability.cst.demo.device`
resource.id.version	The version of the type definition	The version of the type definition tied to this event is `1.0.0`
resource.id.type	Identifier of the type definition	The name of the type definition created by this event is `abb.ability.cst.demo.sample.device`

Additionally, the data node contains information that is specific to the Created event type. As specified in the documentation for this event type, the full type definition is returned in JSON format as part of the payload. This has been removed for brevity.

# Finding Associated Events

Since the event retrieved has a correlation ID, we are able to quickly find any other events that may have been logged as part of creating a type definition. By replacing the filter value with correlationId='d8ae13b7-eb92-4a76-be34-a965a2c482b0', and submitting another call to the /audit endpoint, we can find this information. Note that the resource.type and event filters have been removed. If these were left as part of the filter string, we would only retrieve the event we have already retrieved because any other event type and namespace would be filtered out.

curl -X GET "https://api-xxxxx.abilityplatform.abb/v1/audit?filter=correlationId%3D%27d8ae13b7-eb92-4a76-be34-a965a2c482b0%27&limit=10"
    -H "accept: application/json"
    -H "Authorization: Bearer <TOKEN>"

Issuing the above command will return data that varies based on the environment where it was executed. Typically, you should expect at minimum an additional event showing that access was either granted or rejected, such as the following.

{
  "hasMore": false,
  "data": [
    {
      "correlationId": "d8ae13b7-eb92-4a76-be34-a965a2c482b0",
      "event": "Granted",
      "principal": {
        "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "type": "app"
      },
      "resource": {
        "id": {
          "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "scope": "instance",
          "operationId": "createTypeDefinition",
          "principalType": "app"
        },
        "type": "Abb.Ability.Access"
      },
      "timestamp": "2020-01-31T09:57:50.456Z",
      "data": {
        "reason": "Required permission(s) for operation createTypeDefinition are permitted with condition: "
      }
    },
    // Additional events removed
  ]
}

As you can see, the newly retrieved Abb.Ability.Access.Granted event has an identical correlationId to the Abb.Ability.TypeDefinition.Created event that was retrieved earlier. Additionally, most of the fields under the resource.id node have changed, and the payload associated with the data node is different.

← Region API Pagination Postman setup and how to use →