Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Audit Logging in the Instance and Region API

Audit logging is a service that captures all of the actions of users or systems in the ABB Ability™ Platform. Interacting with the platform causes events to be raised, consumed by the appropriate services and architecture, and logged for later retrieval.

Multitenancy Terminology

If you are unfamiliar with principals, tenants, or solutions, it may be helpful to review the multitenancy terminology before reading this document.

API Authorization

In order to properly authenticate and utilize an API endpoint, you must provide an Authorization Bearer token for your environment. Failure to do this in a secure environment will result in denial of access.

Additionally, all API URLs in this document are given as examples, and should be changed to the proper URL representing for your environment.

Correlation of Events in the Platform

Each consumed event has an optional property - ID - which is used in the audit logging service internally to correlate events that are parts of one action in the Ability Platform. The Platform propagates information regarding the principal ID, the principal type, and the tenant ID between all events that share the same ID based on events defined below.

# Regional API Event

# Abb.Ability.Access.Granted​​​

This event contains principalType, principalId and tenantId, as follows:

{
    "tenantId":"dec09db3-b8d2-41c3-a1c2-77546b808df7", 
    "scope":"TestScope",
    "operationId":"test-audit-logging-operationId-1d9fce28-3846-48f8-a483-6feddddfa366",
    "principalType":"user",
    "principalId":"test-audit-logging-principalId-6bd16d98-b913-487e-a4d9-9ad3fee09875",
    "ability-messagetype":"platformEvent",
    "eventType":"Abb.Ability.Access.Granted",
    "eventTime":"2019-08-07T10:52:18.7220157Z",
    "id":"a2e63d9e-83aa-4ec7-bd9d-7c4edaf45ee4"
}

# Instance API Event

# Abb.Ability.ModelDefinition.Created​

This event does not contain principalType, principalId and tenantId, as follows:

{
    "model":"Test model",
    "ability-messagetype":"platformEvent",
    "eventType":"Abb.Ability.ModelDefinition.Created",
    "eventTime":"2019-08-07T10:52:19.2714876Z",
    "id":"a2e63d9e-83aa-4ec7-bd9d-7c4edaf45ee4"
}

Note that both of the events above share the same ID, so that principalType, principalId and tenantId will propagate.

# Making an Audit Logging API call​

In the following API call, propagation of the fields in the above example, i.e. principalType, principalId, and tenantId, makes it easier to find event information in the logs. For example, searching for all events caused by a specified device can be performed with one query, as seen below.

Without this propagation, only those Region API events that have these fields already filled would appear.

In the case where these fields are not propagated, using the correlationId from the Region API events allows searching for other events from different parts of the Platform.

curl -X GET "http://abiapiapmxxxxxxxxxxx/api/v1/audit?filter=correlationId='a2e63d9e-83aa-4ec7-bd9d-7c4edaf45ee4'" 
    -H "Ability-Condition: tenantId = 'dec09db3-b8d2-41c3-a1c2-77546b808df7'"
    -H "Content-Type: application/json"

For this request, the response would be:

{
    "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": {}
        }
    ]
}

# Platform Event Namespaces

The ABB Ability™ Platform contains a number of pre-built events that can be emitted during regular use to assist with logging and tracing access through the platform.

Each consumed event has an optional property - ID - which is used in the audit logging service to correlate events that are parts of one action in the Ability Platform.

The Platform propagates information regarding the principal ID, the principal type, and the tenant ID between all events that share the same ID based on events defined in the Device API pages.

The information that is returned by the Audit Logging API varies based on the Platform Event Namespace of the associated event. The specific namespaces are called out in the tables below, each event namespace is detailed further lower on this page.

# Instance API Event Namespaces

Namespace Description Emitted Events
Abb.Ability.ModelDefinition Emitted upon creation and deletion of model definitions Created, Deleted
Abb.Ability.TypeDefinition Emitted for all actions regarding type definitions in a solution Created, Updated, Deleted
Abb.Ability.ObjectModel Emitted for all actions regarding object models in a solution Created, Updated, Deleted
Abb.Ability.ObjectModel.Reference Emitted for all actions regarding references between object models following the information model reference structure Created, Updated, Deleted
Abb.Ability.ObjectModel.Method Emitted after a method is invoked from an object model Invoked
Abb.Ability.ObjectModel.File Emitted for file events originating from object models only Uploaded, Deleted
Abb.Ability.File Emitted for file events originating from global storage Uploaded, Deleted
Abb.Ability.ObjectModel.Extension Emitted for all actions regarding extending an object model Created, Updated, Deleted
Abb.Ability.FunctionDefinition Emitted for all actions regarding Ability Functions in a solution Created, Updated, Deleted
Abb.Ability.EventDefinition Emitted for all actions regarding custom, device events designed by users in an Ability solution Created, Updated, Deleted
Abb.Ability.AlarmDefinition Emitted for all actions regarding custom, device alarms designed by users in an Ability solution Created, Updated, Deleted
Abb.Ability.Device Emitted when a device is connected or disconnected to the connectivity provider, the IoT Hub. Connected, Disconnected

# Region API Event Namespaces

Namespace Description Emitted Events
Abb.Ability.App Emitted for all actions regarding entire Ability applications created in the platform Created, Updated, Deleted
Abb.Ability.ConnectivityProvider Emitted for all actions regarding the entire connectivity provider, IoT Hub. Created, Updated, Deleted
Abb.Ability.Contract Emitted for all actions regarding whole contracts tied to solutions and tenants Created, Updated, Deleted
Abb.Ability.Device Emitted for all actions regarding entire devices tied to solutions and tenants Created, Updated, Deleted
Abb.Ability.Grant Emitted for all actions regarding the whole object of a grant in a solution Created, Updated, Deleted
Abb.Ability.Group emitted for all actions regarding an entire group tied to the tenant Created, Updated, Deleted
Abb.Ability.IdentityProvider Emitted for all actions regarding the type of identity provider for your solution Created, Updated, Deleted
Abb.Ability.Operation Emitted for all actions regarding the entire operation tied to a specific solution Created, Updated, Deleted
Abb.Ability.Permission Emitted for all actions regarding the entire permission object tied to a specific solution Created, Updated, Deleted
Abb.Ability.Resource Emitted for all actions regarding the entire resource object tied to a specific solution Created, Updated, Deleted
Abb.Ability.Role Emitted for all actions regarding the entire role object associated with a specific solution Created, Updated, Deleted
Abb.Ability.Solution Emitted for all actions regarding the entire solution object Created, Updated, Deleted
Abb.Ability.Tenant Emitted for all actions regarding the entire tenant object Created, Updated, Deleted
Abb.Ability.User Emitted for all actions regarding the entire user object tied to a specific tenant Created, Updated, Deleted
Abb.Ability.Access Emitted after successful or failed authorization to the application Granted, Rejected

# Instance API Namespace Details

# Abb.Ability.ModelDefinition

The Abb.Ability.ModelDefinition namespace contains all of the events related to a model definition being created, updated, or deleted.

Headers Description Mandatory
model Identifier of the model definition, i.e. abb.robotics.sla Yes

# Abb.Ability.TypeDefinition

The Abb.Ability.TypeDefinition namespace contains all of the events related to a type definition being created, updated, or deleted. All of the following events are emitted within the context of a particular model.

Headers Description Mandatory
type Identifier of the object, i.e. abb.sst.SSTRevisionD Yes
version The version of the type definition, i.e. 1.0.0 Yes
model Model definition, i.e. abb.ability.device Yes

# Abb.Ability.ObjectModel

The Abb.Ability.ObjectModel namespace contains three sub-events that are emitted when a model is created, updated, or deleted.

Headers Description Mandatory
objectId Identifier of the object Yes
model Model definition, i.e. abb.ability.device Yes
type Type of the model, i.e. abb.sst.SSTRevisionD@1 Yes
name Name of the model No
tenantId Tenant of the object model No

# Abb.Ability.ObjectModel.Reference

The Abb.Ability.ObjectModel.Reference events are similar to the Abb.Ability.ObjectModel events, except that they are emitted specifically when references to an object model are modified.

Headers Description Mandatory
objectId Identifier of the object Yes
model Model definition, i.e. abb.ability.device Yes
type Type of the model, i.e. abb.sst.SSTRevisionD@1 Yes
reference Reference type of the associated resource Yes
tenantId Tenant of the object model No

# Abb.Ability.ObjectModel.Method

The Abb.Ability.ObjectModel.Method events are emitted when a command is issued to a device.

Headers Description Mandatory
objectId Identifier of the object Yes
model Model definition, i.e. abb.ability.device Yes
method Name of the method Yes
tenantId Tenant of the object model No

# Abb.Ability.ObjectModel.File

Headers Description Mandatory
tenantId Identifier of a tenant that owns the object model Yes
objectId object identifier Yes
model Identifier of a model definition, i.e. 'abb.ability.device' Yes
path Fully qualified file path Yes

# Abb.Ability.File

The Abb.Ability.File namespace contains two sub-events that are emitted when a file is uploaded or deleted in global storage.

Headers Description Mandatory
model Model definition, i.e. abb.ability.device No / Only for global storage
path Fully qualified file path Yes

# Abb.Ability.ObjectModel.Extension

Headers Description Mandatory
tenantId Identifier of a tenant that owns the object model Yes
objectId Object identifier of the source object model Yes
model Identifier of a model definition of the object model, i.e. 'abb.ability.device' Yes

# Abb.Ability.FunctionDefinition

Headers Description Mandatory
functionDefinitionId Identifier of a function definition, i.e. abb.ability.function.windfarm Yes
version Version of the type, i.e. '1.0.0' Yes

# Abb.Ability.EventDefinition

Headers Description Mandatory
eventDefinitionId Identifier of a event definition, i.e. abb.ability.event.motorStarted Yes
version Version of the type, i.e. '1.0.0' Yes

# Abb.Ability.AlarmDefinition

Headers Description Mandatory
alarmDefinitionId Identifier of a alarm definition, i.e. abb.ability.alarm.motorAlarm Yes
version Version of the type, i.e. '1.0.0' Yes

# Abb.Ability.Device

The Abb.Ability.Device namespace contains events emitted when a device is connected or disconnected to the connectivity provider (i.e., IoTHub)

An event status snapshot is taken once every minute, allowing status monitoring of connect/disconnect states that occur from one snapshot to the next.

The events in this namespace can be used for determining the online/offline status of devices in fleet monitoring environments. If a device is offline, this alerts the user that the device requires support/maintenance.

Headers Description Mandatory
deviceId Identifier of a device Yes
path path to identify an indirectly connected device as defined in the principal manager. No

# Functionality

  • Provides the status of the device/Edge connection and any connection state change.
  • Connect/Disconnect event is available to be subscribed by the application via the Data Access API.
  • Device status reporting is applicable only to directly connected devices.

# Limitations

  • If the device connection is flickering, which means the device connects and disconnects frequently, the feature will not send every single connection state, but will publish the connection state present when a snapshot is taken. In case of an IoT Hub outage, the feature will publish the device connection state as soon as the outage is over. If the device disconnects during the outage, a device disconnected event will be published within 10 minutes.

  • According to Microsoft, the one minute snapshot is hard coded and cannot be changed.

  • This feature does not guarantee sequential ordering of events; however, due to the one minute interval, it is unlikely for messages to be sent out of sequence.

NOTE

Sequential transport of events cannot be guaranteed by the IoT hub (nor therefore by this solution). The user can sequence event messages using eventTime (see Common Headers, above).

# Region API Namespace Details

# Abb.Ability.App

The Abb.Ability.App namespace contains events related to application registrations, and actions associated with them.

Headers Description Mandatory
appId Identifier of the app Yes
solutionId Identifier of a solution that this app belongs to Yes

# Abb.Ability.ConnectivityProvider

The Abb.Ability.ConnectivityProvider contains events related to creation, deletion, or updating a connectivity provider

Headers Description Mandatory
cpId Identifier of a connectivity provider Yes
type Type of a connectivity provider. Currently only iotHub is supported Yes

# Abb.Ability.Contract

The Abb.Ability.Contract namespace contains all events related to creating, deleting, or updating a contract.

Headers Description Mandatory
contractId Identifier of a contract Yes
solutionId Identifier of a solution Yes
tenantId Identifier of a tenant Yes

# Abb.Ability.Device

The Abb.Ability.Device namespace contains all events related to creating, deleting, or updating a device.

Headers Description Mandatory
deviceId Identifier of a device Yes
solutionId Identifier of a solution No
tenantId Identifier of a tenant No
idpId Identifier of an identity provider No
cpId Identifier of a connectivity provider No
parentId Identifier of the parent of this device No

# Abb.Ability.Grant

The Abb.Ability.Grant namespace contains all events related to creating, deleting, or updating a grant.

Headers Description Mandatory
grantId Identifier of a grant Yes
scope Scope of a grant Yes
solutionId Identifier of a solution Yes

# Abb.Ability.IdentityProvider

The Abb.Ability.IdentityProvider namespace contains all events related to creating, deleting, or updating an identity provider.

Headers Description Mandatory
idpId Identifier of an identity provider Yes
type Type of identity provider, either openIdConnect or certificateAuthority Yes

# Abb.Ability.Operation

The Abb.Ability.Operation namespace contains all events related to creating, deleting, or updating an operation.

Headers Description Mandatory
operationId Identifier of an operation Yes
scope Scope of an operation Yes
solutionId Identifier of a solution Yes

# Abb.Ability.Permission

The Abb.Ability.Permission namespace contains all events related to creating, deleting, or updating a permission.

Headers Description Mandatory
name Name of a permission Yes
scope Scope of a permission Yes
solutionId Identifier of a solution Yes

# Abb.Ability.Resource

The Abb.Ability.Resource namespace contains all events related to creating, deleting, or updating a resource.

Headers Description Mandatory
type Type of a resource Yes
scope Scope of a resource Yes
solutionId Identifier of a solution Yes

# Abb.Ability.Role

The Abb.Ability.Role namespace contains all events related to creating, deleting, or updating a role.

Headers Description Mandatory
roleId Identifier of a role Yes
scope Scope of a role Yes
solutionId Identifier of a solution Yes

# Abb.Ability.Solution

The Abb.Ability.Solution namespace contains all events related to creating, deleting, or updating a solution.

Headers Description Mandatory
solutionId Identifier of a solution Yes
scope Scope of a solution Yes

# Abb.Ability.Tenant

The Abb.Ability.Tenant namespace contains all events related to creating, deleting, or updating a tenant.

Headers Description Mandatory
tenantId Identifier of a tenant Yes

# Abb.Ability.User

The Abb.Ability.User namespace contains all events related to creating, deleting, or updating a user.

Headers Description Mandatory
userId Identifier of a user Yes
tenantId Identifier of a tenant Yes

# Abb.Ability.Access

The Abb.Ability.Access namespace contains sub-events that provide information on whether a particular request for authorization was granted (completed successfully) or rejected (completed unsuccessfully). The following headers are common to both requests.

Headers Description Mandatory
operationId Identifier of an accessed operation Yes
scope The scope of this operation Yes
tenantId Identifier of the tenant No
principalType Principal type, one of user/device/app Yes
principalId Principal identifier Yes
appId Identifier of the application that the action is being done on behalf of principal No
Last updated: 9/6/2021, 1:25:50 PM

← Device Connected/Disconnected Event →

Feedback