API Key Concepts

Jetstream facilitates communication:

  1. Between your remotely deployed Terso RFID device and your in-house developed application that consumes Jetstream messages.
  2. Between your Jetstream application and your in-house developed application that consumes Jetstream messages.

Let’s take a look at each communication path in more detail.

A remotely deployed Terso RFID device initiates communications on its own as well as responds to communications from API requests.

Independently, a Terso RFID device will send a periodic HeartbeatEvent event to Jetstream. Jetstream will, then, publish the event to the events queue of your Jetstream application. Your in-house developed application can, then, retrieve the HeartbeatEvent event, along with any other queued events, via a Get Events API request. How your application uses the events is up to the business logic you’ve coded in. For example, the information extracted from a HeartbeatEvent event could be used to update when a device last communicated and, thus, could serve as an indication that the device has internet connectivity. This information would be useful on some sort of devices dashboard.

command

Your in-house application can communicate with a Terso RFID device via command API requests. For example, to query for a device’s current network configuration, a Get a Device's Configuration Parameters command API request can be made. When a command request is made, Jetstream determines if the device is online. If the device:

  • Is online, the command is executed immediately.
  • Is offline, the command is queued in Jetstream for the device to pick up and execute the next time it establishes communications or polls for queueable commands.

Once a command is executed, if the command:

  • Is synchronous, results are returned immediately and can be viewed in the Response Body (also known as Command Response). If there:
    • Is no issue executing the command, the Output Parameter List will be populated with data, if applicable to the command. For the Get a Device's Configuration Parameters command, which is synchronous, the device’s network configuration information (DNS, gateway, IP, subnet) can be gathered here, among other settings.
    • Is an issue executing the command, exceptions will appear in the Exception List.
  • Is not synchronous, results are published and can be viewed in a CommandCompletionEvent event, via Get Events. The CommandCompletionEvent event is published to the events queue of your Jetstream application after the command executes. If there:
    • Is no issue executing the command, the Output Parameter List will be populated with data, if applicable to the command.
    • Is an issue executing the command, exceptions will appear in the Exception List.

In the end, your in-house application will work with a combination of Command Responses and CommandCompletionEvent events to complete communications with a Terso RFID device.

command

Whereas command API requests are meant to communicate with your Terso RFID devices, configuration API requests are meant to communicate with your Jetstream application.

Configuration API requests allow you to manage and maintain the resources (e.g., devices, device definitions, policies, events) pertaining to your Jetstream application. Within your Jetstream application, you can Create a Device, Create a Policy, Add a Policy to a Device, Get All Devices, and more. Get Events, which has already been mentioned above, is also a configuration API request.

When making a configuration API request, results are returned immediately and can be viewed in the Response Body.

command
Agent
A device’s component that communicates with Jetstream.
Application

An application created within Jetstream, representing a logical boundary containing devices and users. Security is setup and configured at the application level for users. The users within an application can only communicate and interact with the devices within that application.

This should not be confused with your in-house developed application that consumes Jetstream messages.

Command

A request or query assigned to a Terso RFID device. A command is executed on a device. A command will be one of three types, described below, and will behave differently depending on whether the device is online or offline.

Command Type Device is Online Device is Offline
Synchronous, Queueable Immediate execution Queued execution
Synchronous, Not Queueable Immediate execution Failure to execute
Not Synchronous, Queueable Immediate execution Queued execution
Command Id

A 36-character GUID tying the following pieces of a command request together: Command Response, CommandQueuedEvent, and CommandCompletionEvent. Each of these components will have the same value in their "CommandId" property. Depending on which command type is being handled in a command request, these three parts will be created at different times and may end up buried with many other responses and events.

Using their common "CommandId" property enables you to gather all three pieces to determine if execution of a command on a device was successful or not.

Command Response

A reply received within the Response Body from a command request being executed. Depending on the command type that was executed, described below, results are returned in the Response Body or not.

Command Type Results Returned in the Response Body?
Synchronous Yes – see the Output Parameter List or Exception List.
Not Synchronous No – see the Output Parameter List or Exception List of the related CommandCompletionEvent event.
Configuration

A setup, change, or request performed on a Jetstream application. Configuration actions are performed for the maintenance and management of Jetstream resources (e.g., devices, device definitions, policies, events).

Device

A Terso RFID device. Our intelligent devices come in the form factors of enclosures, mobile cases, kiosks, and hand-helds.

WebSockets capable devices are able to process eligible commands right away, providing near real-time interaction. Currently, devices that are WebSockets capable include enclosures with firmware v4+ and mobile cases. Devices that are not WebSockets capable will poll for and execute queueable commands at a set time interval. At the moment, devices that aren’t WebSockets capable include enclosures with firmware v3 and kiosks.

Device Definition

A unique collection of settings establishing the identity of a specific Terso RFID device. The settings are a combination of identifiers (e.g., name, firmware version, configuration parameters) for the device and capabilities (e.g., restart, update firmware, scan for RFID tags) the device supports.

Device Specific Command

A command applicable to a specific Terso RFID device. This command is supported by some, but not all, Terso RFID devices. For example, the Unlock a Device’s Door command applies to enclosures with firmware version 4, but not to enclosures with firmware version 3, mobile cases, nor kiosks. See Devices Documentation for the device specific commands supported by each device type.

Event

A message capturing information pertaining to the single occurrence of a process. An event pertains to a device process and/or a Jetstream process. The table below summarizes the available event types and the process they relate to.

Event Type Device Process Jetstream Process
AggregateEvent X
ObjectEvent X
CommandQueuedEvent X
CommandCompletionEvent X X
LogicalDeviceAddedEvent X
LogicalDeviceRemovedEvent X
HeartbeatEvent X
LogEntryEvent X
SensorReadingEvent X
Events provide a window into all that is occurring in your Jetstream application. Below is some, but not all of the questions events can answer:
  • What RFID tags were added/removed from a device during the last door open/close?
  • What RFID tags are currently in a device?
  • What commands have been queued for a device to process?
  • What commands have been completed on/processed by a device?
  • What devices have been added to a Jetstream application?
  • What devices have been removed from a Jetstream application?
  • What devices have/don’t have internet connectivity?
  • What devices have a low battery?
  • What are the temperature readings of a device?
Exception List

A listing of exceptions while executing a command on a device or any issues in queuing/dequeuing the command.

Immediate Results

Results associated with the execution of a command on a device. These results are returned to the calling system immediately. In these circumstances, the calling system will receive a Command Response as well as a CommandCompletionEvent.

Offline

A connection status of a device indicating that it is not connected to Jetstream. Either the device is not WebSockets enabled/capable or has lost power/internet connectivity.

Online

A connection status of a device indicating that it is connected to Jetstream. The device is WebSockets enabled and/or has power and internet connectivity.

Output Parameter List

A listing of key-value/parameter-value settings resulting from the execution of a command on a device.

Policy

A unique collection of settings to manage a device’s configuration values (the configuration parameters are defined by the device’s definition). A policy may be added to a device to apply its configuration settings. Conversely, a policy may be removed from a device to revoke its configuration settings.

Published Results

Results associated with the execution of a command on a device. These results are published to Get Events for retrieval. In these circumstances, the calling system will receive a Command Response but the results will only be made available in CommandCompletionEvent which, along with CommandQueuedEvent, can be retrieved via Get Events.

Region
A geographic region where a device is being placed. This is used to create the most reliable and lowest latency connection to the device. Possible locations include the following:
  • US (United States)
  • EU (Europe)
  • AP (Asia Pacific)
  • USGOV (United States - to meet U.S. government compliance requirements)
Standard Command

A typical command that can be, but doesn’t have to be, supported by any Terso RFID device. This is a stock command that is well defined with variables required to support the command. See Devices Documentation for the standard commands supported by each device type.

Unique
An indicator that the value of a property is distinct and there cannot be another instance of the property with the same value.
User

A person using the Jetstream API. During user account sign up, a user is provided a unique access key and is associated to a Jetstream application. Multiple users may be associated to one Jetstream application. A user must use their access key to make Jetstream API requests and these requests pertain to the user’s Jetstream application.