Skip to content

SAIL Events

Jump to bottom Edit New page
zuk edited this page Oct 27, 2011 · 12 revisions

SAIL events are XMPP messages sent to a groupchat channel. The body of the message — the event data — is a JSON-encoded object (i.e. "hash" or "associative array") with an eventType key and a number of other optional keys.

A SAIL event groupchat message might look something like this:

<message
    from='someone@example.com/foo'
    to='sail@conference.example.com'
    type='groupchat'>
  <body>{"eventType":"person_entered","payload":{"who":"jsmith","door":"A"},"origin":"mzukowski","timestamp":"2011-10-12T18:57:47.499Z"}</body>
</message>

The actual event data is transmitted in the message <body> as a JSON-encoded object. Lets take a closer look the the body in the above example:

{
  "eventType": "person_entered",
  "payload": {
    "who": "jsmith",
    "door": "A"
  },
  "origin": "mzukowski",
  "timestamp": "2011-10-12T18:57:47.499Z"
}

A SAIL event must have at least an eventType key but often also has a payload, an origin, a timestamp, and a run:

  • eventType
    • events signify that something has happened, so event types are usually past-tense verbs
    • events are not commands or requests — get_location is not an event; rather location_requested might be, but you should consider organizing your system in such a way as to avoid requesting information via events. Instead you might want to request information directly from services (e.g. via REST, or XMPP IQs) or make information available as part of less contrived events (for example in this case you might provide updated location data in the payload of a location_changed event)
    • by convention, we use underscores (rather than camelCase) to name events
    • in the future it may make sense to namespace events — currently there is no standard for this, although consider using .'s to namespace your events (e.g. occupancy.person_entered).
  • payload
    • the payload is an arbitrary piece of data associated with the event
    • this can be a string or number, an array, or a complex nested hash/object; the structure is up to you, but two events with the same eventType will generally have the same same payload structure
  • origin
    • an optional username or some other identifier referencing the user, agent, group, etc. who generated or triggered this event
    • because mapping between XMPP user accounts and actual participants in a SAIL system might not always be one-to-one, it is not always possible to figure out who actually triggered the event just from the <message>'s from attribute; therefore we sometimes need the origin attribute for such identification
    • the choice of identifier is up to you; for example if you're using Rollcall, the origin will generally correspond to a Rollcall account login string (i.e. "username")
  • timestamp
    • the time when the event was generated
    • given in ISO 8601 Extended Format; for example: 2011-10-12T18:57:47.499Z
    • time should be in UTC ("Z")
  • run
    • events generated in an S3 space are often in the context of a "run"; for example two separate classrooms running the same application (a "curnit" or "curriculum unit") might be considered two separate runs
    • runs are usually used to segregate physical spaces or groups of users who will not be sharing data in any way
    • the run key should contain an object that must have at least a name key; for example: "run":{"name":"foo"}
Add a custom footer
Add a custom sidebar

Clone this wiki locally