Streams are a collection of Events, each of which describes something that occurred from some source (e.g., a command value that was sent to an Octave edge device, a value that was read from an asset etc.).

There are several different sources that can create Events in Streams. One source is an Octave edge device with an Observations or Edge Action set to route data to Cloud Immediately or Store and Forward. Events can also be created directly in Streams from a Cloud Action, the Octave user interface, via a REST API call, or from within a periodic Task.

In the case of an Observation, the Stream will be created automatically as soon as the Observation is created.

Event JSON Structure

When new Events arrive in the cloud from the device, Octave stores them in a Stream as JSON documents and adds additional metadata. The elems field contains the data related to the Event, while metadata consists of extra fields that describe the Event including both the time at the edge, as well as the time received in the cloud are stored. Having both of these times available for each event is important for more sophisticated data orchestration strategies.

📘

Note

The fields of the Event that you can write data to from the edge or the cloud are the elems and hash fields. All the other fields of the Event are generated by the system and cannot be written to. For more information about Event fields see Event in the Octave API documentation.

The following is an example of the JSON document for an Event:

{
  "creationDate": 1587387677625,
  "creatorId": "i5d8...",
  "elems": {
    "redSensor": {
      "accel": {
        "enable": true,
        "period": 10
      },
      "light": {
        "enable": true,
        "period": 60
      }
    }
  },
  "generatedDate": null,
  "hash": null,
  "id": "e5e9d9d...",
  "lastEditDate": 1587387677625,
  "lastEditorId": "i5d873b...",
  "location": null,
  "metadata": null,
  "path": "/iot_solutions/devices/d_reg_test/:command",
  "streamId": "s5daf2...",
  "tags": {
  }
}

Viewing Events

You can view Events on the following screens within the Octave UI:

• Device > Details screen, *Recent events** region.
• Device > Streams listing screen - click on a Stream path (e.g., :command) to display Events on that stream.
• Cloud > Streams listing screen - click on a Stream path to display Events on that stream.

Depending on the type of Stream, the following columns of information may be displayed to the Stream's Events:

• createdDate: the date/time when the Event was created. For cloud Streams, this is the date/time when the Event reached the cloud.
• generatedDate (applicable to Sensor Events): the date/time when the Input or Sensor on an Octave edge device provided a reading/measurement.
• delta: the difference, in milliseconds, between the createdDate and generatedDate.
• elems: the information stored in the Event (i.e., the Event's JSON message).
• location: if your device has reported it's "location" information to a Stream, through direct Observation of the location resource, the Octave Cloud will automatically add the last know device location to all other Events reported by this device. This location may be old, it is therefore important to check the timestamp of this location field.

Listing Streams Programmatically

You can programmatically get a list of Streams for your company by invoking the GET /<company_name>/stream endpoint in Octave's Cloud REST API.

Listing all Streams

The following example returns all Streams in a company called my_company:

Request

GET /my_company/stream
     -H 'X-Auth-Token: BjBW...' \
     -H 'X-Auth-User: dmarkus'

Response

{
  "head": {
    "status": 200,
    "ok": true,
    "messages": [],
    "errors": [],
    "references": {}
  },
  "body": [
    {
      "id": "s5b2...",
      "capacity": 1000,
      "companyId": "c5b2...",
      "creationDate": 1529422078395,
      "creatorId": "i5b1...",
      "path": "/my_company/devices/mangoh_first/:report"
    },
    {
      "id": "s5b2...",
      "capacity": 1000,
      "companyId": "c5b2...",
      "creationDate": 1529422078391,
      "creatorId": "i5b1...",
      "path": "/my_company/devices/mangoh_second/:default"
    }
  ]
}

Filtering the List of Streams

You can optionally pass in a filter query parameter to the endpoint to return all Streams which contains a given Tag value. This filter is in the following format:

tagList CONTAINS ["@owner=user_name"]

📘

Note:

Non-ascii characters in the query parameter must be escape encoded.

The following example shows how to find all Streams containing the Tag: owner with the value jsmith:

curl "https://octave-api.sierrawireless.io/v5.0/my_company/stream?filter=tagList%20CONTAINS%20%5B%22%40owner%3Djsmith%22%5D" \
     -H 'X-Auth-Token: BjB...' \
     -H 'X-Auth-User: dmarkus'

The following example shows how to find all Streams containing the Tag: IotHub with the value IotDevice:

curl "https://octave-api.sierrawireless.io/v5.0/my_company/stream?filter=tagList%20CONTAINS%20%5B%22%40IotHub%3DIotDevice%22%5D" \
     -H 'X-Auth-Token: BjB...' \
     -H 'X-Auth-User: dmarkus'

Stream Hierarchy

Streams are organized in a hierarchy like a file system. Not only do devices have their own space, but users and companies do as well. This hierarchy plays an important role in controlling access to the data contained in events.

The hierarchy is as follows:

• <company>: The company is the root namespace under which all Cloud Streams exist.
• :inbox: Contains all company-wide streams showing every event that has happened on the system. For example /company/:inbox/cloud-actions shows events generated from the respective source of actions.
• :summary-inbox: Contains redacted versions of all events under the :inbox node, with minimal information.
• devices: Lists all devices registered on Octave. Each device can then be expanded to show its streams.
• users: Lists all users registered on Octave. Each user can then be expanded to show its streams.

📘

Note

The ":" prefix, indicates that the Stream was generated by Octave and cannot be modified.