Event Library

Use Case

The Event Library provides the ability to perform audits to meet compliance requirements in heavily-regulated industries, such as healthcare or financial services.

How It Works

The Event Library opens a separate "event" realm on the user's device. This realm has access to any user realm that the developer chooses to monitor with the Event Library.

When developers implement the Event Library, they designate the types of events they want to record, as well as any custom metadata they want to append to the event recordings. When the client application runs, it records the designated user interactions to the "event" realm as read events, write events, or custom events.

While the client device has a network connection, Atlas Device Sync synchronizes this event realm data to an AuditEvent collection in the linked Atlas data source.

Event Library Schema

Your AuditEvent collection must have a schema containing the following fields:

Additionally, the schema must contain an optional string field for each metadata key you use. For example:

{
  "<Metadata Key>": {
    "bsonType": "string"
  }
}

{
  "title": "AuditEvent",
  "bsonType": "object",
  "required": [
    "_id",
    "_partition",
    "timestamp",
    "activity"
  ],
  "properties": {
    "_id": {
      "bsonType": "objectId"
    },
    "_partition": {
      "bsonType": "string"
    },
    "timestamp": {
      "bsonType": "date"
    },
    "activity": {
      "bsonType": "string"
    },
    "event": {
      "bsonType": "string"
    },
    "data": {
      "bsonType": "string"
    }
  }
}

Read Events

The Event Library records data returned as the result of a query as read events. Read events also record any time a Realm object is instantiated, such as when following a link or looking an object up by primary key.

The Event Library records read events as a JSON object with two fields:

• type: stores the class name

• value: stores an array of serialized objects

Read events store values as follows:

• Single-object read events: the value is an array that has a single element

• Objects matching a query: the value is an array of all objects matching a query, even if the objects are never used

• Reads that occur during a write transaction: the value is the data that the object has before the write transaction began; it does not reflect any changes that occur during the write event.

• Objects that do not exist when a write transaction begins: objects that are created in a write transaction do not produce a read event at all.

{
  "_id": "62b396f4ebe94d2b871889bb",
  "_partition":"events-62b396f4ebe94d2b871889ba",
  "activity":"read object",
  "data": "{
      "type":"Person",
      "value": [{
        "_id": "62b396f4ebe94d2b871889b9",
        "_partition":"",
        "employeeId":1,
        "name":"Anthony"
      }]
  }",
  "event":"read",
  "timestamp": 2022-06-23T14:54:37.756+00:00
}

{
  "type": "Person",
  "value": [{
    "_id": "62b47624265ff7b58e9b204e",
    "_partition": "",
    "employeeId": 1,
    "name": "Michael Scott",
    "office": "62b47624265ff7b58e9b204f"
  }]
}

{
  "type":"Person",
  "value": [{
    "_id": "62b47975a33224558bdf8b4d",
    "_partition": "",
    "employeeId": 1,
    "name": "Michael Scott",
    "office": {
      "_id": "62b47975a33224558bdf8b4e",
      "_partition": "",
      "city": "Scranton",
      "locationNumber": 123,
      "name": "Dunder Mifflin"
    }
  }]
}
{
  "type": "Office",
  "value": [{
    "_id": "62b47975a33224558bdf8b4e",
    "_partition": "",
    "city": "Scranton",
    "locationNumber": 123,
    "name": "Dunder Mifflin"
  }]
}

Write Events

The Event Library records write events when:

• New objects are created

• Existing objects are modified

• Objects are deleted

The write event records both the before and after state of the object. For new objects created, the before state is null. For deletes, the after state of the object is null.

For each write transaction the client commits during an event recording scope, the Event Library records a single write event. This write event records all of the changes made during the write transaction.

The payload is an object keyed on class names. Each object type which had any objects created, modified, or deleted has an entry.

The Event Library records changes to an object type as an object with three arrays:

• insertions: contain the serialized objects which were inserted, using the same serialization scheme as reads

• modifications: report both the old and new values of each property

• deletions: contain the serialized objects which were deleted, using the same serialization scheme as reads

In a modification, the newValue object only includes properties which are different from the oldValue object. If a write transaction assigns to an object but does not actually change the value of any properties,

{
  "Person": {
    "insertions": [{
      "_id": "62b47ead6a178a314ae0eb52",
      "_partition": "",
      "employeeId": 1,
      "name": "Anthony"
    }]
  }
}

{
  "Person":{
    "modifications": [{
      "newValue": {
        "name": "Tony"
      },
      "oldValue": {
        "_id": "62b47d83cdac49f904c5737b",
        "_partition": "",
        "employeeId": 1,
        "name": "Anthony"
      }
    }]
  }
}

{
  "Person":{
    "deletions":[{
      "_id":"62b47ead6a178a314ae0eb52",
      "_partition":"",
      "employeeId":1,
      "name":"Tony",
      "userId":"tony.stark@starkindustries.com"
    }]
  }
}

Custom Events

Custom events can record types of events that do not read or write to the database, such as:

• When a specific screen displays

• When the user clicks a button

You can use custom events to give context to read and write events, such as recording a custom event when the client application displays a given screen. Then, you can infer that read and write events after the custom event recording the app screen loading all occurred on that app screen.

Custom events can store whatever data a developer desires, or no data at all.

{
  "_id": "62b4804c15659310991e5e0a",
  "_partition": "events-62b4804b15659310991e5e09",
  "activity": "login",
  "event": "custom event",
  "timestamp": 2022-06-23T15:01:31.941+00:00
}