Events, Streams, and Tags

Medium One accepts JSON data, and each JSON object is referred to as an "event". Each event contains one or more "tags", which are the event's keys. In order to keep the data organized, events must be sent to a specified data "stream", where they are stored. This article explains each of these components in depth.

 

Events

Medium One accepts data in JSON format. Each JSON object is referred to as an "event". Below are some examples of the correct JSON data format:

  • Example 1: An event with one tag

    {"observed_at": "2016-02-16T15:14:08-08:00","event_data": {"tag_name":"string_data"}}
  • Example 2: An event with two tags

    {"observed_at": "2016-02-16T15:14:08-08:00","event_data": {"tag_name1":"string_data", "tag_name2":100}}
  • Example 3: Including add_client_ip in an event
    {"observed_at": "2016-02-16T15:14:08-08:00", "event_data": {"tag_name1":"string_data"}, "add_client_ip":true}

 

The fields are:

  • observed_at (optional) : This field is the time that the data is observed. It is an ISO8601-formatted text string. If this field is not sent in the JSON, the time the event was received will be used.
    • Example: "2014-07-25T12:12:56.2345-08:00"
  • add_client_ip (optional) : If add_client_ip = true is in the JSON, the client IP address is pushed into the event's event_data as the tag ip_address
  • event_data (required) : This field with the data that is being written. It can be multi-item and multi-level.

Note: The size limit is 64k (65536 characters) per event from opening brace to closing brace

 

Events are stored within streams.

 

Streams

Streams are a logical grouping of events that help the user categorize their data. Each event is stored within the stream it is sent to. There are two main kinds of streams: raw and processed. 

 

Raw vs. processed streams

The raw stream consists of all the data generated by an API Basic User. Whenever a user sends JSON data into Medium One’s platform, it is automatically placed in the raw stream. This data is untouched and not modified in any way. There is only one raw stream and a new one cannot be created.

Processed streams come from the data generated through Medium One’s workflows. There is already a default processed stream in which all workflow events are grouped, but you can create another processed stream if needed. If this is the case, you would need to set the workflow output to go to this processed stream in the Workflow Studio. Data can also be sent from the API Basic User to processed streams, if desired.

 

View, create, edit, and delete streams

To view data in the streams, click on Data Viewer > Data Streams. To configure stream settings, click on Config > Data Streams. By default, every project has a "raw" stream and "processed" stream.

To be able to create, edit, or delete streams, the user must be a Web Administrator. 

On this page, only a new processed data stream can be created. However, both raw and processed streams may be edited. In the edit page, the Web Administrator can change the name of the stream, modify its data's lifetime, and make a tag active or inactive. More information on tags can be found in the next section.

Similarly to creating streams, only processed streams may be deleted.

Note: A stream cannot be deleted if a workflow is sending data to it.

 

Data lifetime

By default, when a stream is created, its events are set to be deleted after 30 days.

You can modify this during stream creation, or you can go to Config > Data Streams and select a stream to edit. From there, you can change the number of days to store events in that stream or select "Never Expire".

 

Note: Events are deleted on a weekly basis, so your data may not be deleted exactly X days after it was created. Events will be stored for at least X days and at most X + 6 days.

 

Tags

Tags are also known as “keys” and are sent with a corresponding “value” within each event. Tags represent the actual data being sent and processed within the IoT platform. Here are some examples of tags:

  • age
  • height
  • battery_level
  • BPM

Note: Medium One accepts alphanumeric characters, underscores, and dashes for tag names.  

Every time a new tag is sent to Medium One within an event, it is auto-detected and will appear in its respective stream. The values that are sent with the tags can vary in each event. (i.e. battery_level can be 100 in one event and 75 in the next).

Data types for each new tag are also auto-detected and will be further explained in the following data types section.

How to activate tags

By default, every new tag is set as an inactive tag. To be able to visualize this data on Medium One and use the tag in workflows, it must be set as active. This can be done by editing its data stream in Config > Data Streams.

Note: If there is a mismatch between the tag and its data type, the data may not be displayed correctly in the widgets.