Events structure

The structure of MATTR VII analytic events depends on the following:

  • Event type: Different event types generate different event payloads. Refer to Event types below for more information.

  • Event sanitisation: Each event has three possible payload versions. The comprehensive version includes all event data, whereas the sanitised versions can exclude all data or just Personal Identifiable Information (PII). Refer to Sanitised events below for more information.

  • Event version: When new event versions of events are introduced (for example as a result of a change to an endpoint response payload structure), different versions of the event would have different payload structure.

Event types

MATTR VII events are usually generated in one of the following scenarios:

  • START events are generated when an operation starts.

  • SUCCESS events are generated following START events when the operation succeeds.

  • FAIL events are generated following START events when the operation fails.

For example, when making a request to sign a Mobile Credential, the following events might be generated:

  • When a sign operation starts, a MOBILE_CREDENTIAL_SIGN_START event is generated.

  • If the sign operation succeeds, a MOBILE_CREDENTIAL_SIGN_SUCCESS event is generated.

  • If the sign operation fails, a MOBILE_CREDENTIAL_SIGN_SUCCESS event is generated.

The exact structure of the payload differs by event types.

START and SUCCESS events

START and SUCCESS events return payloads of the following structure:

javascript
Copy to clipboard.
1Event {
2  id: string;
3  type: literal string;
4  category: string;
5  timestamp: Long;
6  version: string;
7  tenantId: string;
8  requestId: string;
9  data: (ServiceDtoInput | ServiceDtoOutput)
10}
  • id: Unique event identifier.

  • type: Event type. Refer to the events registry for an inclusive list.

  • category: Event category. Refer to the events registry for an inclusive list.

  • timestamp: Event start time, in ISO-8601 format.

  • version: Event version. This might affect the structure of the payload.

  • tenantId: Unique identifier of the tenant the event was generated for.

  • requestId: Unique identifier of the request the event is part of.

  • data: The request (for START events) or response (for SUCCESS events) body. The structure of this Data Transfer Object (DTO) would differ based on the endpoint which generated the event. Refer to the events registry to inspect the structure of different event types.

START and SUCCESS events exceptions

When the event is generated by a list operation, the data object would contain the cursor, limit and id (when applicable) parameters for a START event, and the number of entries in the response for SUCCESS events.

When the DTO is a large binary data object, the data object would include either derived data, extracted meaningful data, or a reference to the data source.

FAIL events

FAIL events return payloads of the following structure:

javascript
Copy to clipboard.
1Event {
2  id: string;
3  type: literal string;
4  category: string;
5  timestamp: Long;
6  version: string;
7  tenantId: string;
8  requestId?: string;
9  data: {
10    error: { 
11      type: string
12      message: string
13    }
14  }
15}
  • id: Unique event identifier.

  • type: Event type. Refer to the events registry for an inclusive list.

  • category: Event category. Refer to the events registry for an inclusive list.

  • timestamp: Event start time, in ISO-8601 format.

  • version: Event version. This might affect the structure of the payload.

  • tenantId: Unique identifier of the tenant the event was generated for.

  • requestId: Unique identifier of the request the event is part of.

  • data:

    • error:

      • type: Error type as defined by MATTR VII. Note that if the error is due to an exception, type will be unknown.

      • message: Error message as defined by MATTR VII.

Sanitised events

When events contain PII, sanitising them before they are logged or processed helps in removing or anonymising this data, thus preserving privacy.

Sanitised versions of MATTR VII analytic events can be stripped of all data, or just PII. Stripped data is configured per end-points depending on the information included in the event body.

Events registry

The Events registry is a comprehensive collection of analytic events generated by the MATTR VII platform. Events are grouped by the service that generates them, which corresponds to the event category.

For each event the following information is available:

  • Event type.

  • Event structure in the different logging levels:

    • Level 1 - Metadata.

    • Level 2 - Non-sensitive data.

    • Level 3 - Full event.

  • Event properties:

    • Properties tagged with Sanitisation Level DATA are removed from the event structure when sanitisation level is set to Level 1 - Metadata.

    • Properties tagged with Sanitisation Level PII are removed from the event structure when sanitisation level is set to Level 2 - Non-sensitive data.

What’s next?

You can now refer to Query for Events to learn how to query for events.