Skip to main content

Notifications

To enable notifications of object change events, configure the Dataset resource as follows:

stack.ts
new Dataset(this, "MyDataset", {
    //...
    notifications: {
        enabled: true,
        topicArn: "<topic arn>",
        roleArn: "<role arn>"
    }
});

It must be possible to assume the provided role from the target account, and the role must be able to publish messages to the supplied topicArn.

Notification format​

The event type is sent as the MessageAttribute with key event.

This approach is used to make filtering on the event type easier, for example, an SQS subscription can be created that only sees interesting events, since this topic will receive all internal events, and some are of low value outside of depot internal processing, e.g:

notificationsTopic.addSubscription(
    new sub.SqsSubscription(targetQueue, {
        rawMessageDelivery: true, // recommended or messages will be put into an envelope
        filterPolicy: {
            event: sns.SubscriptionFilter.stringFilter({
                allowlist: [
                    "io.basestar.database.event.ObjectCreatedEvent",
                    "io.basestar.database.event.ObjectUpdatedEvent",
                    "io.basestar.database.event.ObjectDeletedEvent"
                ]
            })
        }
    })
);

The datasetId and schema are also sent in MessageAttributes.

Additional fields might be added to these events at any time, so receiving application should not fail on undocumented fields.

Documentation follows for the common events, events of other type could be received, these should be ignored.

ObjectCreatedEvent​

Sent when an object is updated, message contains the properties of the object as it was after it was created.

Message attributes:​
datasetId: <dataset id>
schema: <schema name>
event: io.basestar.database.event.ObjectCreatedEvent
JSON structure:​
{
  "schema": "<schema name>",
  "id": "<object id>",
  "after": <object fields after update suceeded>
}

ObjectUpdatedEvent​

Sent when an object is updated, message contains the properties of the object as it was before it was updated, and the properties as they were after it was updated.

Message attributes:​
datasetId: <dataset id>
schema: <schema name>
event: io.basestar.database.event.ObjectUpdatedEvent
Structure:​
{
  "schema": "<schema name>",
  "id": "<object id>",
  "before": <object fields before update attempted>
  "after": <object fields after update suceeded>
}

ObjectDeletedEvent​

Sent when an object is deleted, message contains the properties of the object as it was before it was deleted.

Message attributes:​
datasetId: <dataset id>
schema: <schema name>
event: io.basestar.database.event.ObjectDeletedEvent
Structure:​
{
  "schema": "<schema name>",
  "id": "<object id>",
  "before": <object fields before delete attempted>
}

Additional configuration for Snowflake transactions​

In order to receive notifications for objects altered in the course of a Snowflake transaction, it is necessary to specify enableEvents on the Snowflake location.

Without this configuration, events and notifications will still be raised for CRUD operations through the API, but for completeness you should configure the location with enableEvents if you are using Snowflake transactions.