Commands for analysts - snowplow-archive/sauna GitHub Wiki

HOME > GUIDE FOR ANALYSTS > COMMANDS

Commands are one of Sauna's core concepts. A command is an order or instruction for a specific action to be performed in the future – each command, when executed by a Sauna responder, produces an action.

Here are some example commands:

• Cancel order #234
• Send an email to Jackie
• Wake up our sysadmin

Commands are represented by a self-describing JSON, which itself contains two self-describing JSONs:

{
  "schema": "iglu:com.snowplowanalytics.sauna.commands/command/jsonschema/1-0-0",
  "data": {
    "envelope": {
      "schema": "iglu:com.snowplowanalytics.sauna.commands/envelope/jsonschema/1-0-0",
      "data": {
        "commandId": "9dadfc92-9311-43c7-9cee-61ab590a6e81",
        "whenCreated": "2017-01-02T19:14:42Z",
        "execution": {
          "semantics": "AT_LEAST_ONCE",
          "timeToLive": 1200000 // null
        },
        "tags": {
          // ...
        }
      }
    },
    "command": {
      "schema": "iglu:com.acme.sauna.commands/send_email/jsonschema/1-0-0",
      "data": {
        // ...
      }
    }
  }
}

The schema for the overall command is:

com.snowplowanalytics.sauna.commands/command/jsonschema/1-0-0

This is a very straightforward JSON Schema which simply indicates that a Sauna command must contain a self-describing envelope and a self-describing command, and no other properties.

In the command declared above:

• The envelope identifies the command and provides instructions on how to execute it
• The command specifies the exact action to execute. There has to be a Sauna responder configured to action this command

Let's look at each of these in detail:

The relevant schema is:com.snowplowanalytics.sauna.commands/envelope/jsonschema/1-0-0

The properties within the envelope are as follows:

A Type-4 UUID uniquely identifying this command. This is used to track and report on execution of the command

The ISO 8601 timestamp tracking when the command was created. This can be used with the timeToLive (see below) to control whether the command is executed.

Controls how the command should be executed. Currently the only option here is AT_LEAST_ONCE, meaning that the command will be actioned at least one time (but possible more)

A way of giving the command a lifetime; if the time at which Sauna processes the command is greater than the whenCreated timestamp plus the timeToLive in milliseconds, then the command is disregarded. This prevents time-sensitive commands (for example, abandoned shopping cart emails) from being wrongly sent late in the case of Sauna command processing delays. Set timeToLive to null if the command can be processed at any time (i.e. does not get stale)

A way of attaching additional freeform metadata to a given command. In future versions of Sauna, you will be able to use command tags to fine-tune the execution of Sauna commands.

The self-describing JSON under the command property could be any valid self-describing JSON which describes a Sauna command; these are typically of the form:

<<command-vendor>>.sauna.commands/<<do_action>>/jsonschema/<<version>>

The command is a single instruction to perform a specific action in the command vendor's system.

Commands are typically fed into Sauna using a message queue or event stream, with each message or record containing a single command. You will need to configure one or more compatible Sauna observers to process each message queue or event stream.

Observers that support commands are:

• Amazon Kinesis Observer (WIP)