Skip to main content

Subscriptions

By using Subscriptions it is possible to subscribe to changes in the underlying data, using either static (CDK based) or dynamic (API based) rules.

Static subscriptions​

To define a static subscription, use the following CDK configuration at dataset level:

subscriptions:
  enabled: true
  topicArn: #sns topic arn
  roleArn: #role arn (see below)
  subscriptions:
      - schemas:
          - SchemaName1
          - SchemaName2
      - filter: #filter expression
      - operations:
          - CREATE
          - UPDATE
          - DELETE
          - REFRESH
      - context: #any

The configured role must provide at least the following permissions:

 {
  "Statement": [
    {
      "Action": [
        "SNS:Publish"
      ],
      "Effect": "Allow",
      "Resource": "<your topic arn>",
      "Principal": {
        "AWS": "<backing account id>"
      }
    }
  ]
}

When changes occur, providing they match the configured rule, they will appear as follows:

{
  "schema": "Schema1"
  "operation": "CREATE"
  "id": "etc",
  "before": <object before>
  "after": <object after>,
  "context": <as specified in rule>
}

Dynamic subscriptions​

To define dynamic subscriptions, the CDK configuration is as follows:

subscriptions:
  enabled: true
  topicArn: #as above
  roleArn:  #as above
  subscriptionsSchema: #schema name
  # may also define static subscriptions here

You must also define a subscription object-type schema in your dataset, this schema may have the following optional properties:

properties:
  schemas:
      type:
          array: string
  operations:
      type:
          array: #string or enum type
  filter:
      type: string
  context:
      type: any

Note: the schema name Subscription (any casing) is reserved/cannot be used in GraphQL basestar.

Any object written to this schema will establish a subscription equivalent to the same subscription if it were defined in CDK statically, the format of messages sent is the same as for static subscriptions.

WebSocket Subscriptions​

WebSocket Subscriptions allow you to subscribe to data changes in your Datasets. When data operations succeed with an active subscription in place, the result of a query can be sent to any subscribed clients.

Demonstrating WebSocket Subscriptions​

Install wscat. For example:

npm install -g wscat
  • Ensure your Depot environment has a WebSocket Gateway.
  • Connect to your WS endpoint with wscat: wscat --connect wss://{datasetid}.ws.{environmentId}.{awsaccountid}.{host.tld} -s graphql-ws
  • Take note of the schema name in your target Dataset and create a subscription with a query.

For example, to subscribe to the case of a sourceFile object being created (where schema is named source.File) you would subscribe with a GraphQL query string in a connected wscat session like so:

{"id": "mysub1", "type": "start", "payload": {"query": "subscription { subscribeSourceFile(id:\"13\") { assetId } }"}}

The above requests an operation specified in the message payload. This message provides a unique ID field to connect published messages to the operation requested by this message. In this case, the operation is a graphql query to locate data to be returned.

The subscription is created. Now you can test the subscription by creating some data that will match the subscription’s GraphQL query.

You can use the Depot CLI to create an object:

depot create source.File --datasetId {datasetId} --data '{"id":"13", "sourceId": "sample13", "originalFileName": "abc13.txt", "assetCreated": "1632215986", "assetObjectId": "id13", "assetId": "assetId13", "fileType": "TXT"}'

When the data is created the API will publish a message back to any subscriptions with queries that match. E.g.