Introduction

ItemSense is a software platform that aggregates and transforms torrents of raw RAIN RFID data into real-time, business-driven Item Intelligence.

The platform provides REST APIs for user and system configuration, and item and reader health query; as well as an AMQP interface for item events, reader health events, and threshold transition events.

All REST API endpoints in this document are specified using a BASE_URL placeholder. To call the API, replace this placeholder with the concatenation of the hostname or IP address of the ItemSense server and the string itemsense. For example, if the ItemSense server is running at: http://itemsense.company.com, then the BASE_URL is: http://itemsense.company.com/itemsense.

System Configuration, Monitoring and Management

Users are added to the system. Users can be configured with authorization roles, which gives them access to different parts of the API.

The Health of the configured readers is monitored, either via the REST query interface, or the AMQP event queue.

Reader Software (firmware) versions can be queried and upgraded.

The Support endpoints are used to export logs and configuration, to aid troubleshooting.

RFID Configuration

RFID configuration consists of specifying Reader Definitions (one per reader) and associated Reader Configurations.

Readers (and the items that they identify, locate and track) can be associated with a Facility, a Floor and a Zone within that facility.

A Recipe specifies the association between the readers and their configurations. Many readers can share the same configuration.

A Job is used to start and stop recipes.

Item Data Query and Events

Once the readers and their configurations have been specified, and a job is running within a facility, information about the Items can be returned, either via the REST API, or by configuring and subscribing to a Message Queue.

There are REST API endpoints for the current Items, Item History and Item Threshold Transitions.

There are Item event queues for Item events and Item Threshold Transition events.

Authorization

Access to the endpoints of the APIs is restricted by the roles of the user performing the call to the API.

ItemSense users can have one or more of the following roles:

Admin: has access to all endpoints
ConfigManager: has access to all configuration endpoints
JobRunner: has access to all job endpoints
DataReader: has access to the item data endpoint

The roles of a user are configured when the user is created or updated.

In this document, specific authorizations are shown for each endpoint.

Users

ItemSense users can be created with full or limited permissions to access each API. A user's role(s) determine which permissions they do and do not have. A user can have multiple roles. A role is one of DataReader, JobRunner, ConfigManager, Admin. Only a user with the Admin role can list and manipulate users.

Create

Create a user

Authorized Roles

Admin

HTTP Request

POST http://BASE_URL/configuration/v1/users/create

Request Body

Parameter	Type	Description
name	String	Name of the user to create.
password	String	Password for the user.
roles	Array	A set of roles to assign to the user.

Response

Parameter	Type	Description
name	String	The Username
roles	Array of: String	The roles corresponding to the user

Sample Code

var user = {};
user.name = "ItemSenseUser";
user.password = "1mp1njer";
user.roles = ["DataReader"];

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/users/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(user));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    user = "ItemSense",
                    password = "1mp1nj!",
                    roles = {"DataReader"}
                });

    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response


{
  "name":"ItemSenseUser",
  "roles":["DataReader"]
}

Create or Replace

Replace an existing user, or create a new one

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/users/createOrReplace

Request Body

Parameter	Type	Description
name	String	Name of user to create.
password (optional)	String	Password for the user. Optional during updates.
roles	Array	A set of roles to assign to the user.

Response

Parameter	Type	Description
name	String	The Username
roles	Array of: String	The roles corresponding to the user

Sample Code

var user = {};
user.name = "ItemSenseUser";
user.password = "1mp1nj!";
user.roles = ["DataReader", "Admin", "JobRunner"];

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/users/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(user));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    user = "ItemSense",
                    password = "1mp1nj!",
                    roles = { "DataReader",
                              "Admin",
                              "JobRunner"
                            }
                });

    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response


{
  "name":"ItemSenseUser",
  "roles":["DataReader"]
}

Delete

Delete a specific user.

Authorized Roles

Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/users/destroy/{username}

Parameters

Parameter	Type	Description
username	String	The name of the user to delete

Response

This endpoint returns an empty response

Sample Code


var userName = "ItemSenseUser";
var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/users/destroy/" + userName, true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));
string userName = "ItemSenseUser";

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/destroy" + userName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific user.

Authorized Roles

Admin

Http Request

GET http://BASE_URL/configuration/v1/users/show/{username}

Parameters

Parameter	Type	Description
username	String	The username of the user to retrieve

Response

Parameter	Type	Description
name	String	The name of the user
roles	Array of: String	The roles corresponding to the user

Sample Code

var userName = "ItemSenseUser";
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/users/show/" + userName, true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string specificUser = "ItemSenseUser";
Uri uri = new Uri("http://BASE_URL/configuration/v1/users/show" + specificUser);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "ItemSenseUser",
    "roles": [
      "DataReader"
    ]
}

Get All

Retrieve all of the users.

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/configuration/v1/users/show

Parameters

Parameter	Type	Description
role	String	An optional role name. Only users with this role will be returned.

Response

Array of:

Parameter	Type	Description
name	String	The name of the user
roles	Array of: String	The roles corresponding to the user

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/users/v1/show", true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response


[
  {
    "name": "DataReader",
    "roles": [
      "DataReader"
    ]
  },
  {
    "name": "ItemSenseUser",
    "roles": [
      "DataReader"
    ]
  },
  {
    "name": "JobRunner",
    "roles": [
      "JobRunner"
    ]
  },
  {
    "name": "SuperAdmin",
    "roles": [
      "Admin"
    ]
  }
]

Get the Current User

Show the user corresponding to the API call

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/users/currentUser

Response

Parameter	Type	Description
name	String	The name of the user
roles	Array of: String	The roles corresponding to the user

Show the User Roles

Display the list of roles that can be assigned to users

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/configuration/v1/users/roles/show

Response

Array of:

Parameter	Type	Description
role	String	A role that the user can be assigned

Authenticate the current user

Authenticate

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/users/authenticate

Response

Parameter	Type	Description
name	String	The name of the user
roles	Array of: String	The roles corresponding to the user

Response Codes

Code	Description
200	The user was successfully authenticated
401	No user provided; or the provided user credentials were not authorized

Authentication

Itemsense users have two options for Authenticating:

HTTP Basic Authentication with the user's Itemsense Credentials
Token-based authentication, using our Authentication API.

To use token-based authentication for authorizing API calls, you must set the Authorization request header with the token value. For example:

Headers['Authorization'] = 'Token {"token": "128faacd-e4bb-4687-90e0-af2836b2c098"}'

If you do not have basic credentials, then a user with administrative privileges must generate a token for you.

Note: The AMQP interface does not support token-based authentication. You must use basic authentication for connecting to an AMQP queue.

Get a Token

In order to begin using the token-based authentication mechanism, you must first get a token. This call requires you (or an administrator) to supply Basic Auth credentials.

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/token/{username}

Parameters

Parameter	Type	Description
username	String	Name of user for which to create token

Response

Parameter	Type	Description
token	String	The value of the token in UUID format

Sample Response

{
  "token": "128faacd-e4bb-4687-90e0-af2836b2c098"
}

Get a Token for the current user

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/authentication/v1/token

Response

Parameter	Type	Description
token	String	The value of the token in UUID format

List Tokens

List all tokens for a specific user.

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/authentication/v1/listTokens/{username}

Parameters

Parameter	Type	Description
username	String	Name of user for which to list tokens

Response

An array of:

Parameter	Type	Description
authenticationToken	AuthenticationToken	The token
issued	String	Date of issue of the token in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
username	String	Username associated with token
lastUsed	String	When the token was last used in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
valid	Boolean	Whether the token is valid

Revoke Token

Revoke a specific authentication token.

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/revokeToken

Request Body

Parameter	Type	Description
token	String	The value of the token in UUID format

Response

This endpoint returns an empty response

Revoke Tokens

This method is used to revoke all tokens for a specific user

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/revokeTokens/{username}

Parameters

Parameter	Type	Description
username	String	Name of user for which to revoke tokens

Response

This endpoint returns an empty response

Validate Token

Validate the provided token

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/validate

Request Body

Parameter	Type	Description
token	String	The value of the token in UUID format

Response

Parameter	Type	Description
name	String	The name of the user
roles	Array of: String	The roles corresponding to the user

Response Codes

Code	Description
200	The token was successfully authenticated
422	No token provided
401	The provided token is invalid

AuthenticationToken

Parameters

Parameter	Type	Description
token	String	The value of the token in UUID format

Facilities

ItemSense is capable of managing multiple physical locations. Each of these physical locations is called a "Facility".

Each facility is independently able to run jobs, build zone maps, specify different reader definitions, and query items - though it is also possible to query items across all facilities.

Recipes, reader configurations, and users are shared across all facilities supported by the ItemSense installation.

ItemSense comes pre-loaded with one facility, called 'DEFAULT'.

Scenarios for facilities:

ItemSense is only using one facility

No additional configuration is necessary, and the facility name will not be required for other API endpoints.

ItemSense is using multiple facilities

The following API endpoints require a facility to be specified as part of the request body:

Jobs
- Start
Zone Maps
- Create
- Create or Replace
Reader Definitions
- Create
- Create or Replace

Create

Create a new facility (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/facilities/create

Request Body

Property	Type	Description
name (required)	String	The name associated with the facility. This name is used as the identifier for retrieving, updating, and deleting a facility. It is also used as the primary identifier for a facility in other API calls, where required.

Sample Code

var facility =  { "name": "Warehouse-123" };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/facilities/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(facility));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "Warehouse-123"

                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "Warehouse-123"
}

Create or Replace

Replace an existing facility, or create a new one.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/facilities/createOrReplace

Request Body

Property	Type	Description
name (required)	String	The name associated with the facility. This name is used as the identifier for retrieving, updating, and deleting a facility. It is also used as the primary identifier for a facility in other API calls, where required.

Sample Code

var facility =  { "name": "Warehouse-123" };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/facilities/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(facility));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/createOrReplace");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "Warehouse-123"

                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "Warehouse-123"
}

Delete

Delete a specific facility.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/facilities/destroy/{facilityName}

Parameters

Parameter	Type	Description
facilityName	String	The name of the facility to delete

Sample Code

var facilityName = "Warehouse-123";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/facilities/destroy/" + facilityName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string facilityName = "Warehouse-123";

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/destroy/" + facilityName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific facility.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/facilities/show/{facilityName}

Parameters

Parameter	Type	Description
facilityName	String	The name of the facility to retrieve

Sample Code

string facilityName = "Warehouse-123";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/facilities/show/" + facilityName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string facilityName = "Warehouse-123";

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/show/" + facilityName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "Warehouse-123"
}

Get All

Retrieve all of the facilities

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/facilities/show

Response

Array of:

Parameter	Type	Description
name	String	The name of the facility

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/facilties/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/show/");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "DEFAULT"
  },
  {
    "name": "Warehouse-123"
  }
]

Zone Maps

Zone Maps are used to divide the facility that is being monitored by ItemSense into spatial regions.

A Zone Map consists of a facility, and a set of named Zones. A Zone allocates the space within a facility in a way that is meaningful to the application (e.g. Men’s, Women’s and Shoe departments in a retail store).

Zone names do not have to be unique. If more than one zone definition has the same name as another, then the spaces of the two (or more) physical zones are combined into one logical zone (e.g. Women’s Shoes might be on the 1st floor and Women’s dresses on the 3rd floor; these could be combined into a “Women’s Clothing” zone).

It is not necessary to define zones for the entire space of a facility. ItemSense assigns tags to the zone name “FACILITY” if they are present and outside of any user-defined zones (or “ABSENT” if the tag is detected with LOW presenceConfidence).

If zones are defined, they cannot overlap in space.

When combined with a reader definition’s spatial coordinates, ItemSense provides powerful location data, such as which zone an item is in, and when an item transitions from one zone to another.

Zone Map Example

Zone Map

  {
    "name": "Contoso_Fashion",
    "facility": "DEFAULT",
    "zones": [
      {
        "name": "Womens",
        "floor": "1",
        "points": [
          {
            "x": 7.0,
            "y": 0.0,
            "z": 0.0
          },
          {
            "x": 0.0,
            "y": 6.0,
            "z": 0.0
          },
          {
            "x": 7.0,
            "y": 20.0,
            "z": 0.0
         },
         {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         },
         {
            "x": 12.0,
            "y": 11.0,
            "z": 0.0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": "1",
        "points": [
          {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
          },
          {
            "x": 28.0,
            "y": 26.0,
            "z": 0.0
          },
          {
            "x": 31.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         }
        ]
      }
    ]
  }

Zones

A Zone consists of a name, an optional floor, and a shape in space. The shape is defined by an array of points in two-dimensional* space, using the Cartesian coordinate system, measured in meters. Each point represents a vertex of the shape. They can be rectangular (requiring two points), or a more complex polygonal shape (requiring more than two points). When defining a polygon, the vertex points must be specified in an order that describes the outside of the polygon (i.e. points next to each other in the list must share an edge of the polygon).

The z-dimension of point property is currently set to 0 in all cases.

Property	Type	Description
name (required)	String	The name given to the specific zone
floor (optional)	String	The name of the floor where the zone exists
points (required)	Array of Point	An array of points that define the zone's boundaries

Points

Property	Type	Description
x	Number	The x coordinate of the zone point, in meters from the 0.0,0.0 location in the monitored space.
y	Number	The y coordinate of the zone point, in meters from the 0.0,0.0 location in the monitored space.
z	Number	The z coordinate of the zone point. Z is not currently used, and defaults to 0.0 if not specified. While the z property may be omitted, it may not be specified with a `null` value.

Non-contiguous Zone Example

      {
        "name": "Contoso_Fashion",
        "facility": "DEFAULT",
        "zones": [
          {
            "name": "Womens",
            "floor": "1",
            "points": [
              {
                "x": 7.0,
                "y": 0.0,
                "z": 0.0
              },
              {
                "x": 0.0,
                "y": 6.0,
                "z": 0.0
              },
              {
                "x": 7.0,
                "y": 20.0,
                "z": 0.0
             }
         },
          {
             "name": "Womens",
             "floor": "2",
             "points": [
               {
                 "x": 7.0,
                 "y": 0.0,
                 "z": 0.0
               },
               {
                 "x": 0.0,
                 "y": 6.0,
                 "z": 0.0
               },
               {
                 "x": 7.0,
                 "y": 20.0,
                 "z": 0.0
              }
          }

Create

Create a new zone map (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/zoneMaps/create

Request Body

Property	Type	Description
name (required)	String	The name associated with a specific zone map. This name will be used as the identifier for retrieving, updating, and deleting a zone map. It will also be used for setting the Current zone map.
facility (optional, except if using multiple facilities)	String	The name of the facility which the zone map will be associated with.
zones (required)	Array of Zone	A collection of zones that define the geographic coordinates for each zone in the monitored space. Zone definitions cannot overlap.

Response

Parameter	Type	Description
name	String	The name associated with the zone map
facility	String	The facility with which the zonemap is associated
zones	Array of: Zone	The collection of zones within the zone map

Sample Code


  var zoneMap = {
        "name": "Contoso_Fashion",
        "facility": "DEFAULT",
        "zones": [
          {
            "name": "Womens",
            "floor": "1",
            "points": [
              {
                "x": 7.0,
                "y": 0.0,
                "z": 0.0
              },
              {
                "x": 0.0,
                "y": 6.0,
                "z": 0.0
              },
              {
                "x": 7.0,
                "y": 20.0,
                "z": 0.0
             },
             {
                "x": 22.0,
                "y": 18.0,
                "z": 0.0
             },
             {
                "x": 23.0,
                "y": 10.0,
                "z": 0.0
             },
             {
                "x": 12.0,
                "y": 11.0,
                "z": 0.0
             }
            ]
          },
          {
            "name": "Mens",
            "floor": "1",
            "points": [
              {
                "x": 22.0,
                "y": 18.0,
                "z": 0.0
              },
              {
                "x": 28.0,
                "y": 26.0,
                "z": 0.0
              },
              {
                "x": 31.0,
                "y": 18.0,
                "z": 0.0
             },
             {
                "x": 23.0,
                "y": 10.0,
                "z": 0.0
             }
            ]
          }
        ]
      };
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "http://BASE_URL/configuration/v1/zoneMaps/create", true);
  xhr.requestHeaders("Content-Type", "application/json");
  xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
  xhr.send(JSON.stringify(zoneMap));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/create"");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                    {
                        name = "Contoso_Fashion",
                        facility = "DEFAULT",
                        zones =
                        {
                            new
                            {
                                name = "MENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 28.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 28.0,
                                        y = 26.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 31.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    }
                                }
                            },
                            new
                            {
                                name = "WOMENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 7.0,
                                        y = 0.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 0.0,
                                        y = 6.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 7.0,
                                        y = 20.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 22.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 12.0,
                                        y = 11.0,
                                        z = 0.0
                                    }
                                }
                            }
                        }
                    });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "Contoso_Fashion",
    "facility": "DEFAULT",
    "zones": [
      {
        "name": "Womens",
        "floor": "1",
        "points": [
          {
            "x": 7.0,
            "y": 0.0,
            "z": 0.0
          },
          {
            "x": 0.0,
            "y": 6.0,
            "z": 0.0
          },
          {
            "x": 7.0,
            "y": 20.0,
            "z": 0.0
         },
         {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         },
         {
            "x": 12.0,
            "y": 11.0,
            "z": 0.0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": "1",
        "points": [
          {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
          },
          {
            "x": 28.0,
            "y": 26.0,
            "z": 0.0
          },
          {
            "x": 31.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         }
        ]
      }
    ]
  }

Create or Replace

Replace an existing zone map, or create a new one

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/zoneMaps/createOrReplace

Request Body

The same as the Create Request Body

Response

The same as Create Response

Sample Code

  var zoneMap =  {
       "name": "Contoso_Fashion",
       "facility": "DEFAULT",
       "zones": [
         {
           "name": "Womens",
           "floor": "1",
           "points": [
             {
               "x": 7.0,
               "y": 0.0,
               "z": 0.0
             },
             {
               "x": 0.0,
               "y": 6.0,
               "z": 0.0
             },
             {
               "x": 7.0,
               "y": 20.0,
               "z": 0.0
            },
            {
               "x": 22.0,
               "y": 18.0,
               "z": 0.0
            },
            {
               "x": 23.0,
               "y": 10.0,
               "z": 0.0
            },
            {
               "x": 12.0,
               "y": 11.0,
               "z": 0.0
            }
           ]
         },
         {
           "name": "Mens",
           "floor": "1",
           "points": [
             {
               "x": 22.0,
               "y": 18.0,
               "z": 0.0
             },
             {
               "x": 28.0,
               "y": 26.0,
               "z": 0.0
             },
             {
               "x": 31.0,
               "y": 18.0,
               "z": 0.0
            },
            {
               "x": 23.0,
               "y": 10.0,
               "z": 0.0
            }
           ]
         }
       ]
     };
  var xhr = new XMLHttpRequest();
  xhr.open("PUT", "http://BASE_URL/configuration/v1/zoneMaps/createOrReplace", true);
  xhr.requestHeaders("Content-Type", "application/json");
  xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
  xhr.send(JSON.stringify(zoneMap));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/create"");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                    {
                        name = "Contoso_Fashion",
                        facility = "DEFAULT",
                        zones =
                        {
                            new
                            {
                                name = "MENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 28.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 28.0,
                                        y = 26.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 31.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    }
                                }
                            },
                            new
                            {
                                name = "WOMENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 7.0,
                                        y = 0.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 0.0,
                                        y = 6.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 7.0,
                                        y = 20.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 22.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 12.0,
                                        y = 11.0,
                                        z = 0.0
                                    }
                                }
                            }
                        }
                    });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

The same as the Create Sample Response

Delete

Delete a zone map.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/zoneMaps/destroy/{zoneMapName}

Parameters

Parameter	Type	Description
zoneMapName	String	The name of the zone map to delete

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/zoneMaps/destroy/" + zoneMapName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));
string zoneMapName = "Contoso_Fashion";

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/destroy/" + zoneMapName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific zone map.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/zoneMaps/show/{zoneMapName}

Parameters

Parameter	Type	Description
zoneMapName	String	The name of the zone map to retrieve

Response

Parameter	Type	Description
name	String	The name associated with the zone map
facility	String	The facility with which the zonemap is associated
zones	Array of: Zone	The collection of zones within the zone map

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/zoneMaps/show/" + zoneMapName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string zoneMapName = "Contoso_Fashion";

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/show/" + zoneMapName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "Contoso_Fashion",
    "facility": "DEFAULT",
    "zones": [
      {
        "name": "Womens",
        "floor": "1",
        "points": [
          {
            "x": 7.0,
            "y": 0.0,
            "z": 0.0
          },
          {
            "x": 0.0,
            "y": 6.0,
            "z": 0.0
          },
          {
            "x": 7.0,
            "y": 20.0,
            "z": 0.0
         },
         {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         },
         {
            "x": 12.0,
            "y": 11.0,
            "z": 0.0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": "1",
        "points": [
          {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
          },
          {
            "x": 28.0,
            "y": 26.0,
            "z": 0.0
          },
          {
            "x": 31.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         }
        ]
      }
    ]
  }

Get All

Show all of the configured zone maps

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/zoneMaps/show

Response

Array of:

Parameter	Type	Description
name	String	The name associated with the zone map
facility	String	The facility with which the zonemap is associated
zones	Array of: Zone	The collection of zones within the zone map

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/zoneMaps/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

 [{
     "name": "Contoso_Fashion",
     "facility": "DEFAULT",
     "zones": [
       {
         "name": "Womens",
         "floor": "1",
         "points": [
           {
             "x": 7.0,
             "y": 0.0,
             "z": 0.0
           },
           {
             "x": 0.0,
             "y": 6.0,
             "z": 0.0
           },
           {
             "x": 7.0,
             "y": 20.0,
             "z": 0.0
          },
          {
             "x": 22.0,
             "y": 18.0,
             "z": 0.0
          },
          {
             "x": 23.0,
             "y": 10.0,
             "z": 0.0
          },
          {
             "x": 12.0,
             "y": 11.0,
             "z": 0.0
          }
         ]
       },
       {
         "name": "Mens",
         "floor": "1",
         "points": [
           {
             "x": 22.0,
             "y": 18.0,
             "z": 0.0
           },
           {
             "x": 28.0,
             "y": 26.0,
             "z": 0.0
           },
           {
             "x": 31.0,
             "y": 18.0,
             "z": 0.0
          },
          {
             "x": 23.0,
             "y": 10.0,
             "z": 0.0
          }
         ]
       }
     ]
   }]

Get Current

Show the current zone map for the given facility

AuthorizedRoles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/control/v1/currentZoneMap/show/{facilityName}

Parameter	Type	Description
facilityName (optional, except if using multiple facilities)	String	The name of the facility for which to retrieve the current zone map.

Response

Parameter	Type	Description
status	One of: WAITING_FOR_ZONE_MAP, RUNNING, FAILED, COMPLETE	The status of the zone map
name	String	The name of the zone map

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/control/v1/currentZoneMap/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/currentZoneMap/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Responses

Without a value currently set:

{
  "name": null,
  "status": "WAITING_FOR_ZONE_MAP"
}

With a value currently set:

{
  "name": "Contoso_Fashion",
  "status": "COMPLETE"
}

Update Current

Select a specific zone map to apply.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/control/v1/currentZoneMap/select/{zoneMapName}

Parameter	Type	Description
zoneMapName	String	The name of the zone map to apply

Response

Parameter	Type	Description
name	String	The name associated with the zone map
facility	String	The facility with which the zonemap is associated
zones	Array of: Zone	The collection of zones within the zone map

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/currentZoneMap/select" + zoneMapName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string zoneMapName = "Contoso_Fashion";

Uri uri = new Uri("http://BASE_URL/control/v1/currentZoneMap/select" + zoneMapName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Responses


{
  "name": "Contoso_Fashion",
  "status": "COMPLETE"
}

Clear Current

Reset the current zone map for the given facility.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/control/v1/currentZoneMap/clear/{facilityName}

Parameters

Parameter	Type	Description
facilityName (optional, except if using multiple facilities)	String	The name of the facility for which to clear the current zone map.

Sample Code



var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/control/v1/currentZoneMap/clear", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/currentZoneMap/clear");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Reader Definitions

Reader Definitions are used to define a reader for use with ItemSense. Each reader definition specifies a single reader.

Note that in order to interact with ItemSense, a reader must be running the ItemSense Reader Agent in its Customer Application Partition (CAP) space. It is not possible to configure the agent via the API; this must be done via the ItemSense Management Console (IMC). During its provisionig workflow, the IMC creates the reader definition, installs the reader agent software, and pairs the reader with ItemSense. Therefore the POST /configuration/v1/readerDefinition/create endpoint is for IMC use only. It is documented here for completeness.

Create

Create a new reader definition (but do not replace an existing one)

This endpoint is for ItemSense Management Console use only. See additional information in the introduction of this section.

Note that groups are created implicitly as a property of the reader definition. So if, for example, you specify the name "storeroom" as a group on three readers, those three readers are now part of one "storeroom" group.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/readerDefinitions/create

Request Body

Parameter	Type	Description
name	String	The name associated with the reader definition. If not provided, will default to the address.
address	String	The IP address or the hostname of the reader
groups	Array of: String	The groups with which this reader is associated
type	One of: XARRAY, XSPAN, XPORTAL, SPEEDWAY, UNKNOWN	The type of reader
readerZone	String	The spot zone with which to associate this reader
antennaZones	Map[int,string]	A map of antenna-to-spot-zone associations. If not specified, antenna is allocated to the readers spot zone
facility	String	The facility with which the reader is associated
placement	PlacementConfig	The placement of the reader
labels	Array of: String	A list of configurable strings associated with the reader
agentIdentifier	String	Internal use only. This value is set by the ItemSense Management Console, during reader provisioning.

Response

Parameter	Type	Description
name	String	The name that identifies the reader definition
serialNumber	String	The serial number of the reader
address	String	The IP address or the hostname of the reader
groups	Array of: String	The groups with which this reader is associated
type	One of: XARRAY, XSPAN, XPORTAL, SPEEDWAY, UNKNOWN	The type of reader
readerZone	String	The spot zone with which to associated this reader
antennaZones	Map[int,string]	A list of antenna-to-spot-zone associations. If not specified, antenna is allocated to the readers spot zone
facility	String	The facility with which the reader is associated
placement	PlacementConfig	The placement of the reader
labels	Array of: String	A list of string tags associated with the reader
features	Map[Feature, ReaderFeatureStatus]	See Configure Feature
agentIdentifier	String	Internal use only

Sample Code

var readerDefinition =  {
                           name: "xarray-11-30-0D",
                           address: "xarray-11-30-0D.impinj.com",
                           groups: [ "ceiling", "closet" ],
                           type: "XARRAY",
                           placement: {
                             x: 4.3,
                             y: 6.65,
                             z: 2.68,
                             yaw: 30,
                             pitch: 0,
                             roll: 90,
                             floor: 1
                         }
                      };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/readerDefinitions/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerDefinition));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "xarray-11-32-34",
                    address = "xarray-11-32-34.impinj.com",
                    groups = new string[] { "ceiling", "closet" },
                    type = "XARRAY",
                    placement = new
                    {
                        x = 4.3,
                        y = 6.65,
                        z = 2.68,
                        yaw = 30,
                        pitch = 0,
                        roll = 90,
                        floor = 1
                    },
                    labels = null,
                    readerZone = "xarray-11-32-34.impinj.com",
                    antennaZones = null
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "xarray-10-D9-41",
  "agentIdentifier": "xarray-10-D9-41",
  "address": "xarray-10-D9-41.impinj.com",
  "groups": [ "ceiling", "closet" ],
  "type": "XARRAY",
  "placement": {
    "x": 4.3,
    "y": 6.65,
    "z": 2.68,
    "yaw": 30,
    "pitch": 0,
    "roll": 90,
    "floor": 1
  },
  "features": {},
  "labels": null,
  "readerZone": "xarray-10-D9-41",
  "antennaZones": null
}

Create or Replace

Replace an existing reader definition, or create a new one.

When creating reader definitions, this endpoint is for ItemSense Management Console use only. See additional information in the introduction of this section. Existing reader definitions created by the IMC may be updated using this endpoint.

Note: When changing the reader's facility as part of a reader definition update, an internal consistency issue within ItemSense requires the name of the readerZone to change, as well as the names of any antennaZones.

Similarly, when changing the reader's placement's floor as part of a reader definition update, the names of the readerZone and antennaZones must change. Furthermore, once a reader has a floor assigned to it, it is prohibited to remove the floor (which occurs when the floor property is set to null, or the placement itself is set to null). It is permissible to change the floor to a different, non-null value.

Calls to this API endpoint fail if the facility or floor is changed and the names of the zones are not modified.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/readerDefinitions/createOrReplace

Request Body

The same as the Create Request Body

Response

The same as the Create Response

Sample Code

var readerDefinition =  {
                           name: "xarray-11-30-0D",
                           address: "xarray-11-30-0D.impinj.com",
                           groups: [ "ceiling", "closet" ],
                           type: "XARRAY",
                           placement: {
                             x: 4.1,
                             y: 3.65,
                             z: 1.68,
                             yaw: 30,
                             pitch: 0,
                             roll: 90,
                             floor: 1
                         }
                       };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/readerDefinitions/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerDefinition));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "xarray-11-32-34",
                    address = "xarray-11-32-34.impinj.com",
                    groups = new string[] { "ceiling", "closet" },
                    type = "XARRAY",
                    placement = new
                    {
                         x = 4.1,
                         y = 3.65,
                         z = 1.68,
                         yaw = 30,
                         pitch = 0,
                         roll = 90,
                         floor = 1
                    },
                    labels = null,
                    readerZone = "xarray-11-32-34.impinj.com",
                    antennaZones = null
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

The same as the Create Sample Response

Delete

Delete a specific reader definition

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/readerDefinitions/destroy/{readerDefinitionName}

Parameters

Parameter	Type	Description
readerDefinitionName	String	Name of the reader definition to be deleted

Response

The same as the Create Response

Parameter | Type | Description

Sample Code

var readerName = "xarray-11-30-0D";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/readerDefinitions/destroy/" + readerName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/destroy/" + readerName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Get a specific reader definition

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/show/{readerDefinitionName}

Parameters

Parameter	Type	Description
readerDefinitionName	String	The name of the reader definition to retrieve

Response

The parameters returned in the response are the same as those specified in the Create Request Body

Sample Code

var readerName = "xarray-11-30-0D";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/show/" + readerName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/show/" + readerName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

The same as the Create Sample Response

Get All

This method is used to retrieve all of the reader definitions

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/show

Response

Array of objects whose properties are defined by the Create Request Body

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));



Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "xarray-10-D9-41",
    "agentIdentifier": "xarray-10-D9-41",
    "address": "xarray-10-D9-41.impinj.com",
    "groups": [ "ceiling", "closet" ],
    "type": "XARRAY",
    "placement": {
      "x": 4.3,
      "y": 6.65,
      "z": 2.2,
      "yaw": 30,
      "pitch": 0,
      "roll": 90,
      "floor": 1
    },
    "labels": null,
    "features": null,
    "readerZone": "xarray-10-D9-41",
    "antennaZones": null
  },
  {
    "name": "xarray-11-30-0D",
    "agentIdentifier": "xarray-11-30-0D",
    "address": "xarray-11-30-0D.impinj.com",
    "groups": [ "ceiling", "closet" ],
    "type": "XARRAY",
    "placement": {
      "x": 8.1,
      "y": 5.65,
      "z": 2.68,
      "yaw": 30,
      "pitch": 0,
      "roll": 90,
      "floor": 1
    },
    "labels": null,
    "features": {},
    "readerZone": "xarray-11-30-0D",
    "antennaZones": null
  }
]

Groups

Retrieve the superset of elements (group names) assigned to any reader definition groups property. For example, given these readers with these defined groups:

readerDefinition1.groups = ['storeroom', 'dressingroom']
readerDefinition2.groups = ['storeroom', 'ceiling']
readerDefinition3.groups = ['ceiling']

A call to this endpoint would return:

['storeroom', 'dressingroom', 'ceiling']

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/groups

Response

Array of strings

Sample Code

var xhr = new XMLHttpRequest();

xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/groups", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/groups");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  "ceiling",
  "closet"
]

Configure Feature

Some readers support features that can be configured for specific uses, e.g. to enable an Antenna Hub on a Speedway reader.

A call to this endpoint produces a status of ACCEPTED(202) and a response HTTP header for "Location", which is a URL used to get the status of the new configuration request.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/readerDefinitions/{readerDefinitionName}/featureChanges

Parameters

Parameter	Type	Description
readerDefinitionName	String	The name of the reader on which to configure the feature.

Request Body

Parameter	Type	Description
feature	One of: ANTENNA_HUB	The name of the feature to configure.
action	One of: ENABLE, DISABLE	The configuration action to perform.

Sample Code

var readerName = "xarray-11-dd-ef";
var featureRequest =  {
                           feature: "ANTENNA_HUB",
                           action: "ENABLE"
                      };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(featureRequest));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));
string readerName = "xarray-11-dd-ef";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                   feature: "ANTENNA_HUB",
                   action: "ENABLE"
                });
    sw.Write(data);
}

Sample Response

202 Accepted

Get Feature Status

Get the status of a specific feature on a reader.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/{readerDefinitionName}/featureChanges/{feature}

Parameters

Parameter	Type	Description
readerDefinitionName	String	The name of the reader whose feature information is to be returned.
feature	One of: ANTENNA_HUB	The feature whose status on that reader is to be returned.

Response

Parameter	Type	Description
status	One of: ENABLED, DISABLED	The last known status of the feature reported by this reader. If the `requestStatus` is CONFIGURING or ERROR, this field should not be trusted to reflect the current state of the feature.
statusLastUpdated	String	The last time the reader reported the status of the feature to ItemSense in ISO-8601 format, e.g. "2017-05-02T15:35:01.560Z".
requestStatus	One of: IDLE, INITIALIZING, CONFIGURING, ERROR	The status of the most recent request to change the status of the feature. IDLE means that there is no current request, and the last request, if there was one, completed successfully. INITIALIZING indicates that there is a request preparing to configure. CONFIGURING means there is an active request in progress, and ERROR means the last request failed.
requestStatusLastUpdated	String	The last time a request to change the status of this feature updated the requestStatus or null if there has never been one, in ISO-8601 format, e.g. "2017-05-02T15:35:01.560Z".
requestTargetStatus	One of: null, ENABLED, DISABLED	The target status of the current request to change the status of the feature, if the request is CONFIGURING or in ERROR (null if there is no active request)
message (optional)	String	A message with more details on the status of the current or most recent request to change the status of the feature.

Sample Code

var readerName = "xarray-11-30-0D";
var feature = "ANTENNA_HUB";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges/" + feature, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";
string feature = "ANTENNA_HUB";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges/" + feature);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "status": "DISABLED",
  "statusLastUpdated": "2017-05-02T15:35:01.560Z",
  "requestStatus": "IDLE",
  "requestStatusLastUpdated": null
}

Get Active Feature Request Status

Get the status of active feature requests on a reader. Active requests are those where the feature status is CONFIGURING or ERROR.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/{readerDefinitionName}/featureChanges

Parameters

Parameter	Type	Description
readerDefinitionName	String	The name of the reader definition whose feature information is to be returned.

Response

A map of feature names to feature status objects, represented as an object where the field names correspond to valid feature names and the value is the same as the response from the feature status request.

Sample Code

var readerName = "xarray-11-30-0D";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "ANTENNA_HUB": {
    "status": "DISABLED",
    "statusLastUpdated": "2017-05-01T10:13:14Z",
    "requestStatus": "ERROR",
    "requestStatusLastUpdated": "2017-05-05T16:33:42Z",
    "message": "Reader failed to execute the configuration request"
  }
}

Data Definitions

Placement Configuration

A Placement Configuration provides ItemSense with the information that it needs to position a reader relative to the space that is being monitored, and to ensure that the tag locations reported by the reader are relative to the same space. It is not required to specify the placement of any reader; if a placement is specified, then certain fields are required, depending on the reader type, as specified in the table below. Specifying a placement for an XARRAY will allow it to fulfill LOCATION use-cases, and for all reader types can be used to enhance output data.

For an XARRAY gateway, the placement includes a precise location in three-dimensional space. For all readers, the placement may include a floor, which will be applied to all tag reads from the reader.

Placement Configurations are an important component of the reader definition. They allow ItemSense to accurately position inventoried RFID tags within the space monitored by the xArray reader(s). There are three sets of parameters: the floor; the x, y, and z parameters that define where an xArray reader center point is located within the monitored space; and the yaw, pitch, and roll parameters that define the orientation of the xArray reader around its center point, as defined in the diagram below:

Parameter	Type	Allowed For Reader Types	Required for Reader Types	Description	Notes
x	Number	XARRAY, XSPAN, XPORTAL	XARRAY, XSPAN, XPORTAL	The x-axis offset, in meters, of the reader from the (0,0) location in the monitored space
y	Number	XARRAY, XSPAN, XPORTAL	XARRAY, XSPAN, XPORTAL	The y-axis offset, in meters, of the reader from the (0,0) location in the monitored space
z	Number	XARRAY, XSPAN, XPORTAL	XARRAY, XSPAN, XPORTAL	The average distance between the height of the xArray and the height of the tags
yaw	Number	XARRAY, XSPAN, XPORTAL	XARRAY, XSPAN, XPORTAL	The angle, in degrees, that the xArray is rotated about its Z axis
pitch	Number	XARRAY, XSPAN, XPORTAL	None	The angle, in degrees, that the xArray is tilted about its X axis	This parameter is ignored and is not used by ItemSense
roll	Number	XARRAY, XSPAN, XPORTAL	None	The angle, in degrees, that the xArray is tilted about its Y axis	This parameter is ignored and is not used by ItemSense
floor	String	All Readers	SPEEDWAY	The number or name of the floor on which the reader is installed	Once this is set on a reader, it cannot be set to `null`, nor can the `placement` itself be set to `null`.

Reader Configurations

A Reader Configuration defines how a RAIN™ RFID reader will be utilized when a job is running. This configuration includes properties that control what Reader Mode is being executed, and what Session it is using. For a full list and description of configuration properties, please view the section Reader Configuration Details .

Create Reader Configuration

Create a new reader configuration (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/readerConfigurations/create

Request Body

Property	Type	Description
name (required)	String	The name identifying the reader configuration
operation (required)	One of: INVENTORY, LOCATION, THRESHOLD, DO_NOTHING	The operation that the reader performs. Reader is disabled if set to DO_NOTHING.
configuration	ReaderConfigDetails	The details of the reader configuration

Sample Code

var readerConfiguration = {
                              name: "LOCATION_WITH_FILTER",
                              operation: "LOCATION",
                              configuration: {
                                readerMode: "MODE_1002",
                                session: 2,
                                filter: {
                                  tagMask: 3034
                                }
                              }
                            };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/readerConfigurations/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerConfiguration));

// Encode credentials
string encodedCredentials = ...
var readerConfiguration = new
            {
                name = "LOCATION_WITH_FILTER",
                operation = "LOCATION",
                configuration = new
                {
                    readerMode = "MODE_1002",
                    session = 2,
                    filter:
                    {
                        tagMask: 3034
                    }

                }
            };
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "LOCATION_WITH_FILTER",
  "configuration": {
    "readerMode": "MODE_1002",
    "session": 2,
    "filter": {
      "memoryBank": 1,
      "pointer": 32,
      "tagMask": "3034"
    }
  },
  "operation": "LOCATION"
}

Update Reader Configuration

Update an existing configuration, or create a new one if it does not already exist

Authorization Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/readerConfigurations/createOrReplace

Request Body

The same as the Create Request Body.

Sample Response

var readerConfiguration = {
                              name: "IMPINJ_InventoryConfig",
                              operation: "INVENTORY",
                              configuration: {
                                readerMode: "MODE_1002",
                                searchMode: "DUAL_TARGET",
                                session: 1,
                                tagPopulationEstimate: 500,
                                antennas: [
                                  45,
                                  16,
                                  35,
                                  14,
                                  49,
                                  36,
                                  2,
                                  31,
                                  18,
                                  29,
                                  48,
                                  19,
                                  46,
                                  3,
                                  33,
                                  52,
                                  15,
                                  50,
                                  13,
                                  32,
                                  1,
                                  51,
                                  30,
                                  17,
                                  47,
                                  20,
                                  34,
                                  4
                                ]
                              }
                            };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/readerConfigurations/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerConfiguration));

// Encode credentials
string encodedCredentials = ...
var readerConfiguration = new
            {
                name = "IMPINJ_InventoryConfig",
                operation = "INVENTORY",
                configuration = new
                {
                    readerMode = "MODE_1002",
                    searchMode = "DUAL_TARGET",
                    session = 1,
                    tagPopulationEstimate = 500,
                    antennas = {
                        45,
                        16,
                        35,
                        14,
                        49,
                        36,
                        2,
                        31,
                        18,
                        29,
                        48,
                        19,
                        46,
                        3,
                        33,
                        52,
                        15,
                        50,
                        13,
                        32,
                        1,
                        51,
                        30,
                        17,
                        47,
                        20,
                        34,
                        4
                    }
                }
            };


Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "IMPINJ_InventoryConfig",
  "operation": "INVENTORY",
  "configuration": {
    "readerMode": "MODE_1002",
    "searchMode": "DUAL_TARGET",
    "session": 1,
    "tagPopulationEstimate": 500,
    "transmitPowerInDbm": null,
    "antennas": [
      45,
      16,
      35,
      14,
      49,
      36,
      2,
      31,
      18,
      29,
      48,
      19,
      46,
      3,
      33,
      52,
      15,
      50,
      13,
      32,
      1,
      51,
      30,
      17,
      47,
      20,
      34,
      4
    ],
    "filter": null,
    "channelConfig": null
  }
}

Delete Reader Configuration

Delete a reader configuration

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/readerConfigurations/destroy/{readerConfigurationName}

Parameters

Parameter	Type	Description
readerConfigurationName	String	The name of the reader configuration to be deleted

Sample Code

var readerConfigurationName = "IMPINJ_LocationConfig";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/readerConfiguration/destroy/" + readerConfigurationName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
string readerConfigurationName = "IMPINJ_LocationConfig";
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerConfigurations/destroy/" + readerConfigurationName);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get Reader Configuration

Retrieve a specific reader configuration

AuthorizedRoles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerConfigurations/show/{readerConfigurationName}

Parameters

Parameter	Type	Description
readerConfigurationName	String	The name of the reader configuration to be retrieved

Response

The same as the Create Request Body.

Sample Code

var readerConfigurationName = "IMPINJ_LocationConfig";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerConfiguration/show/" + readerConfigurationName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
string readerConfigurationName = "IMPINJ_LocationConfig";
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerConfigurations/show/" + readerConfigurationName);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "MY_LOCATION",
  "configuration": {
    "readerMode": "MODE_1002",
    "session": 2,
    "filter": null
  },
  "operation": "LOCATION"
}

Get All Reader Configurations

Retrieve all of the reader configurations

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerConfigurations/show

Response

Array of Create Reader Configuration Request Body.

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerConfiguration/show, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerConfigurations/show");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "IMPINJ_LocationConfig",
    "configuration": {
      "readerMode": "MODE_1002",
      "session": 2,
      "filter": null
    },
    "operation": "LOCATION"
  },
  {
    "name": "IMPINJ_GatewayConfig",
    "configuration": {
      "readerMode": "MODE_1002",
      "session": 2,
      "searchMode": "DUAL_TARGET",
      "tagPopulationEstimate": null,
      "transmitPowerInDbm": null,
      "polarization": null,
      "antennas": [
        1,
        2,
        3,
        4
      ],
      "filter": null,
      "channelConfig": null
    },
    "operation": "INVENTORY"
  },
  {
    "name": "IMPINJ_InventoryConfig",
    "configuration": {
      "readerMode": "MODE_1002",
      "session": 2,
      "searchMode": "SINGLE_TARGET",
      "tagPopulationEstimate": null,
      "transmitPowerInDbm": null,
      "polarization": null,
      "antennas": [
        45,
        16,
        35,
        14,
        49,
        36,
        2,
        31,
        18,
        29,
        48,
        19,
        46,
        3,
        33,
        52,
        15,
        50,
        13,
        32,
        1,
        51,
        30,
        17,
        47,
        20,
        34,
        4
      ],
      "filter": null,
      "channelConfig": null
    },
    "operation": "INVENTORY"
  }
]

Data Definitions

Reader Configuration Details

Property	Type	Description
readerMode (required)	One of: MAX_THROUGHPUT HYBRID DENSE_READER_M4 DENSE_READER_M8 MAX_MILLER DENSE_READER_M4_TWO AUTOSET_DENSE_READER MODE_1002 MODE_1003 MODE_1004	The RFID reader mode For more information on reader modes, please see this article
session (required)	One of: 0, 1, 2, 3	The RFID session When operation=LOCATION, must be 2 or 3
searchMode (required)	One of: READER_SELECTED SINGLE_TARGET DUAL_TARGET TAG_FOCUS SINGLE_TARGET_BTOA DUAL_TARGET_WITH_BTOASELECT	The RFID search mode Only available when the reader operation=INVENTORY For more information on sessions and search modes, please see this article
filter (optional)	Filter Configuration	Tag filter definition
tagPopulationEstimate (optional)	Integer	An estimate of the number of tags in the field of view of the readers. This value will be used to set the starting ‘Q’ value in the UHF Gen2 RFID inventory protocol Only available when the reader operation=INVENTORY
transmitPowerInDbm (optional)	Number	The transmit power, in dBm to use for each of the selected antenna ports.
polarization * (optional)	Boolean	This flag tells the reader to use an antenna's ID in polarized format. These IDs will show up in the antennaId field of the tag report data. By default xArrays support antenna numbers 1-52. Both horizontal and vertical polarizations of a beam map to the same antenna ID. * With polarization enabled, then tag reads on the horizontal polarization will have an offset of 1000 applied (1001-1052). Tag reads on the vertical polarization will have an offset of 2000 applied (2001-2052). Only available when the reader operation=INVENTORY
antennas (optional)	Array of Integers	Array of integers defining which antenna ports that readers will use Only available when the reader operation=INVENTORY
disabledAntennas (optional)	Array of Integers	Array of integers defining which antennas that the readers will not use. This is helpful in situations when the reader is located very close to an obstruction and location accuracy could be improved by disabling the antenna(s) facing that obstruction. Only available when the reader operation=LOCATION)
channelConfig (optional)	Channel Configuration	Defines any fixed frequency channel configurations that the readers will use. This option is used only by readers certified for use in a regulatory region that supports the use of fixed frequencies. ItemSense will not block the user from entering an invalid channel configuration for a region, nor will it alert the user that the configuration is invalid until the job runs and reports a failure, as follows: "message": "xArray-11-30-0D reported a failure: [FailedToStartError] ChannelConfig cannot be specified for this reader since it is in a hopping region" Only available when the reader operation=INVENTORY

Filter Configuration

Property

Type

Description

tagMask
(required)

String

A hexadecimal value on which to filter tags

memoryBank
(optional)

Integer

The RFID tag memory region to base a tag filter on, based on the following:

Memory Bank #	Tag Memory Region
0	Reserved
1	EPC
2	TID
3	User

Defaults to 1

pointer
(optional)

Integer

A pointer to the bit in memory from which to start the filter. For example, bits 0-31 of EPC memory are used to store the tag CRC and PC Word. To filter on the EPC value of a specific tag, it would therefore be necessary to start the filter on bit 32.

Defaults to 32

Channel Configuration

Property

Type

Description

channelIndex
(optional)

Integer

For RFID readers operating in regions with fixed frequency regulatory requirements, channelIndex is used to define a single frequency for the reader to operate in. This is a one-based integer value into the Low Level Reader Protocol (LLRP) frequency table that points to the position of a frequency in the list of available frequencies. You must already know the channels that are available for your region. For example, RAIN RFID readers for the ETSI region have the following list of available channels:

LLRP Channel Number	Center Frequency (MHz)
1	865.70 MHz
2	866.30 MHz
3	866.90 MHz
4	867.50 Mhz

txFrequenciesInMhz
(optional)

Array of Numbers

For RAIN RFID readers operating in regions with frequency-hopping regulatory requirements, txFrequenciesInMhz is used to define a custom frequency hop table. The table can only include frequencies that are allowed by the reader’s region, but frequencies can be defined in any order including repeating and/or omitting frequencies. For example, based on the ETSI frequencies above, an ETSI frequency hop table might be defined as [865.7, 866.3, 866.9, 867.5], which will prompt the reader to hop only in these frequencies, in this order.

Threshold

A Threshold defines how a collection of readers will be utilized when a threshold job is running.

Note that threshold tuning is required to insure the highest accuracy possible. Once the basic threshold configuration has been provisioned via this API, Impinj's Threshold Tuning Tool can be used to refine the configuration to suit an environment. Impinj also offers a training class for partners to develop their skills.

Create

Create a new threshold configuration (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/thresholds

Request Body

Property	Type	Description
name (required)	string	The name of the threshold
facility (required)	string	The facility that contains the threshold
readerArrangement (required)	One of: SIDE_BY_SIDE, OVERHEAD, OVERHEAD_OFFSET, CUSTOM	The arrangement of readers around the threshold
readers (optional)	Key Value List	A map of reader definiton names and an object with a single property

of antennaConfigurationId for specifiying what antenna configuration to use

Sample Code

var threshold = {
                  "name": "THRESHOLD",
                  "facility": "DEFAULT",
                  "readerArrangement": "SIDE_BY_SIDE",
                  "readers": {
                    "reader_name_one": {
                      "antennaConfigurationId": 1
                    },
                    "reader_name_two": {
                      "antennaConfigurationId": 2
                    }
                  }
               };
;
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/thresholds", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(threshold));

// Encode credentials
string encodedCredentials = ...
var threshold = {
                  "name": "THRESHOLD",
                  "facility": "DEFAULT",
                  "readerArrangement": "SIDE_BY_SIDE",
                  "readers": {
                    "reader_name_one": {
                      "antennaConfigurationId": 1
                    },
                    "reader_name_two": {
                      "antennaConfigurationId": 2
                    }
                  }
               };

Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1
    },
    "reader_name_two": {
      "antennaConfigurationId": 2
    }
  }
}

Replace

Update an existing threshold

Authorization Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/thresholds/{thresholdID}

Request Body

The same as the Create Request Body. But with an additional ID property

Sample Response

var readerConfiguration = {
                            "id": 1,
                            "name": "THRESHOLD",
                            "facility": "DEFAULT",
                            "readerArrangement": "SIDE_BY_SIDE",
                            "readers": {
                              "reader_name_one": {
                                "antennaConfigurationId": 1
                              },
                              "reader_name_two": {
                                "antennaConfigurationId": 2
                              }
                            }
                          };

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/thresholds/1", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerConfiguration));

// Encode credentials
string encodedCredentials = ...
var readerConfiguration = {
                            "id": 1,
                            "name": "THRESHOLD",
                            "facility": "DEFAULT",
                            "readerArrangement": "SIDE_BY_SIDE",
                            "readers": {
                              "reader_name_one": {
                                "antennaConfigurationId": 1
                              },
                              "reader_name_two": {
                                "antennaConfigurationId": 2
                              }
                            }
                          };


Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/1");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1
    },
    "reader_name_two": {
      "antennaConfigurationId": 2
    }
  }
}

Delete

Delete a threshold configuration

Note: When deleting a threshold, any existing transition data stored about the threshold will also be removed

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/threshold/{thresholdID}

Parameters

Parameter	Type	Description
thresholdID	Integer	The id of the threshold to be deleted

Sample Code

var thresholdID = 1;

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/thresholds/" + thresholdID, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int thresholdID = 1;
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/" + thresholdID);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific threshold configuration

AuthorizedRoles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds/{thresholdID}

Parameters

Parameter	Type	Description
thresholdID	Integer	The ID of the threshold configuration to be retrieved
embed (optional)	The string `antennaConfiguration`	Entity or entities to embed as whole objects within the response, in addition to just the ID that could be used to reference the object. This functions identically in the Get All and Get APIs. Currently, only one legal value exists for this parameter. For more details, see the Response and Sample Response sections.

Response

The same as the Create Request Body, but with an additional ID property. If embed entities were requested, those will be embedded in the response.

`antennaConfiguration` embed

When the antennaConfiguration embed is requested using the embed query parameter, the response object will contain the entire antennaConfiguration object adjacent to the antennaConfigurationId. See Sample Response.

Sample Code

var thresholdID = 1;

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/" + thresholdID, true);
// To request the antennaConfiguration embed, add the query parameter:
// xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/" + thresholdID + "?embed=antennaConfiguration", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int thresholdID = 1;
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/" + thresholdID);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1
    },
    "reader_name_two": {
      "antennaConfigurationId": 2
    }
  }
}

With `antennaConfiguration` embed

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1,
      "antennaConfiguration": {
        "id": 1,
        "name": "left_configuration_name",
        "side": "LEFT",
        "in": [
          {"antennaId": 1},
          {"antennaId": 3}],
        "out": [
          {"antennaId": 2},
          {"antennaId": 4}]
      }
    },
    "reader_name_two": {
      "antennaConfigurationId": 2,
      "antennaConfiguration": {
        "id": 2,
        "name": "right_configuration_name",
        "side": "RIGHT",
        "in": [
          {"antennaId": 5},
          {"antennaId": 7}],
        "out": [
          {"antennaId": 6},
          {"antennaId": 8}]
      }
    }
  }
}

Get All

Retrieve all of the threshold configurations

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds

Parameters

Parameter	Type	Description
embed (optional)	The string `antennaConfiguration`	Entity or entities to embed as whole objects within the response, in addition to just the ID that could be used to reference the object. This functions identically in the Get All and Get APIs. Currently, only one legal value exists for this parameter. For more details, see the Response and Sample Response sections.

Response

Array of Create Threshold request bodies with the ID property. If embed entities were requested, those will be embedded in the response.

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds", true);
// To request the antennaConfiguration embed, add the query parameter:
// xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds?embed=antennaConfiguration", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "id": 1,
    "name": "threshold_one",
    "facility": "DEFAULT",
    "readerArrangement": "SIDE_BY_SIDE",
    "readers": {
      "reader_name_one": {
        "antennaConfigurationId": 1
      },
      "reader_name_two": {
        "antennaConfigurationId": 2
      }
    }
  },
  {
    "id": 2,
    "name": "threshold_two",
    "facility": "DEFAULT",
    "readerArrangement": "SIDE_BY_SIDE",
    "readers": {
      "reader_name_one": {
        "antennaConfigurationId": 1
      },
      "reader_name_two": {
        "antennaConfigurationId": 2
      }
    }
  }
]

Threshold Antenna Configuration

An antenna configuration defines how a given reader's antennas should be utilized for a particular threshold

Create

Create a new threshold antenna configuration (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/thresholds/antennaConfigurations

Request Body

Property	Type	Description
name (required)	string	The name of the antenna configuration.
side (optional*)	One of: LEFT, RIGHT	The side of the threshold that the antenna is positioned on. *If it is on neither side (e.g. above the threshold) this property should be `null` or absent.
readerType (optional)	One of: XARRAY, XSPAN, XPORTAL	Threshold antenna configurations can be specific to reader types. If defined, this field can be helpful for assigning configurations to specific reader types. Note that while it is possible to set a readerType of SPEEDWAY, this is not a supported configuration for this feature
readerArrangement (optional)	One of: SIDE_BY_SIDE, OVERHEAD, OVERHEAD_OFFSET, CUSTOM	Threshold antenna configurations can be specific to reader arrangements. If defined, this field can be helpful for assigning configurations to specific threshold arrangements.
in (optional*)	array of objects	A collection of antenna objects that point to the inside of the threshold. *At least one of the "in" or "out" antennas must be specified.
out (optional*)	array of objects	A collection of antenna objects that point to the outside of the threshold. *At least one of the "in" or "out" antennas must be specified.
ignored (optional)	array of objects	A collection of antenna objects where the antennas are enabled on the reader, but their reads will be ignored. This is useful in order to help synchronize cycle durations across readers that may otherwise have differing enabled antenna counts. In a request, providing `null`, an empty list, or omitting the property are all equivalent ways of specifying no antennas to ignore. In a response, either the property will be absent or the value will be a nonempty list (it will never be `null` or an empty list).

Sample Code

var antennaConfiguration = {
                             "name": "configuration_name",
                             "side": "LEFT",
                             "readerType": "XARRAY",
                             "readerArrangement": "OVERHEAD",
                             "in": [
                               {
                                 "antennaId": 1
                               },
                               {
                                 "antennaId": 3
                               }
                             ],
                             "out": [
                               {
                                 "antennaId": 2
                               },
                               {
                                 "antennaId": 4
                               }
                             ]
                           };

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(antennaConfiguration));

// Encode credentials
string encodedCredentials = ...
var antennaConfiguration = {
                             "name": "configuration_name",
                             "side": "LEFT",
                             "readerType": "XARRAY",
                             "readerArrangement": "OVERHEAD",
                             "in": [
                               {
                                 "antennaId": 1
                               },
                               {
                                 "antennaId": 3
                               }
                             ],
                             "out": [
                               {
                                 "antennaId": 2
                               },
                               {
                                 "antennaId": 4
                               }
                             ]
                           };

Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(antennaConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
 "id": 1,
 "name": "configuration_name",
 "side": "LEFT",
 "readerType": "XARRAY",
 "readerArrangement": "OVERHEAD",
 "in": [
   {
     "antennaId": 1
   },
   {
     "antennaId": 3
   }
 ],
 "out": [
   {
     "antennaId": 2
   },
   {
     "antennaId": 4
   }
 ]
}

Replace

Update an existing threshold antenna configuration

Authorization Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/{antennaConfigurationID}

Request Body

The same as the Create Request Body. But with an additional ID property

Sample Response

var antennaConfiguration = {
                             "id": 1,
                             "name": "configuration_name",
                             "side": "LEFT",
                             "readerType": "XARRAY",
                             "readerArrangement": "OVERHEAD",
                             "in": [
                               {
                                 "antennaId": 1
                               },
                               {
                                 "antennaId": 3
                               }
                             ],
                             "out": [
                               {
                                 "antennaId": 2
                               },
                               {
                                 "antennaId": 4
                               }
                             ]
                          };

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/1", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(antennaConfiguration));

// Encode credentials
string encodedCredentials = ...
var antennaConfiguration = {
                                 "id": 1,
                                 "name": "configuration_name",
                                 "side": "LEFT",
                                 "readerType": "XARRAY",
                                 "readerArrangement": "OVERHEAD",
                                 "in": [
                                   {
                                     "antennaId": 1
                                   },
                                   {
                                     "antennaId": 3
                                   }
                                 ],
                                 "out": [
                                   {
                                     "antennaId": 2
                                   },
                                   {
                                     "antennaId": 4
                                   }
                                 ]
                              };


Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/1");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(antennaConfiguration);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
 "id": 1,
 "name": "configuration_name",
 "side": "LEFT",
 "readerType": "XARRAY",
 "readerArrangement": "OVERHEAD",
 "in": [
   {
     "antennaId": 1
   },
   {
     "antennaId": 3
   }
 ],
 "out": [
   {
     "antennaId": 2
   },
   {
     "antennaId": 4
   }
 ]
}

Delete

Delete a threshold antenna configuration

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/threshold/antennaConfiguration/{antennaConfigurationID}?replacementId={replacementId}

Parameters

Parameter	Type	Description
antennaConfigurationID	Integer	The id of the antenna configuration to be deleted
replacementId (optional)	Integer	The id of an antenna configuration to use as a replacement for the one being deleted, passed as a query parameter

Sample Code

var antennaConfigurationID = 1;
var replacementId = 2;

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID + "?replacementId=" + replacementId, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int antennaConfigurationID = 1;
int replacementId = 2;

Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID + "?replacementId=" + replacementId);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific threshold antenna configuration

AuthorizedRoles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/{antennaConfigurationID}

Parameters

Parameter	Type	Description
antennaConfigurationId	Integer	The ID of the antenna configuration to be retrieved

Response

The same as the Create Request Body. But with an additional ID property

Sample Code

var antennaConfigurationID = 1;

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int antennaConfigurationID = 1;
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
 "id": 1,
 "name": "configuration_name",
 "side": "LEFT",
 "readerType": "XARRAY",
 "readerArrangement": "OVERHEAD", 
 "in": [
   {
     "antennaId": 1
   },
   {
     "antennaId": 3
   }
 ],
 "out": [
   {
     "antennaId": 2
   },
   {
     "antennaId": 4
   }
 ]
}

Get All

Retrieve all of the threshold antenna configurations

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds/antennaConfigurations

Response

Array of Create Antenna configuration request bodies with the ID property.

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/antennaConfigurations", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri("http://BASE_URL/configuration/v1/antennaConfigurations");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
   "id": 1,
   "name": "configuration_name",
   "side": "LEFT",
   "readerType": "XARRAY",
   "readerArrangement": "OVERHEAD", 
   "in": [
     {
       "antennaId": 1
     },
     {
       "antennaId": 3
     }
   ],
   "out": [
     {
       "antennaId": 2
     },
     {
       "antennaId": 4
     }
   ]
  },
  {
   "id": 2,
   "name": "configuration_name_2",
   "side": "LEFT",
   "readerType": "XARRAY",
   "readerArrangement": "OVERHEAD", 
   "in": [
     {
       "antennaId": 5
     },
     {
       "antennaId": 8
     }
   ],
   "out": [
     {
       "antennaId": 6
     },
     {
       "antennaId": 9
     }
   ]
  }
]

Recipes

Recipes map reader configurations onto individual reader definitions, as well as specifying other parameters relating to the type of operation that the recipe specifies.

For a recipe to be valid, it must have its readerConfigurationName field set, and/or a list of of reader hostnames and reader configurations in the readerConfigurations field. If an entry exists in the readerConfigurationName field only, then the reader configuration identified by this field will be applied to every defined reader.

If an entry exists in both fields, then the entry in the readerConfigurations field takes precedence.

All recipes share some common properties, but other properties vary by the recipe type. These variations are specified below.

Create Recipe

Create a new recipe (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/recipes/create

Request Body

Common properties:

Property	Type	Description
name (required)	String	The name of the recipe
type (required)	One of: LOCATION INVENTORY THRESHOLD	The type of recipe
readerConfigurationName (required)	String	The name of the default reader configuration to use. The operation attribute of the referenced reader configuration must either match the type attribute of the recipe or be DO_NOTHING
readerConfigurations (optional)	Key Value List	A map of reader definition names to reader configuration names. These override the configuration given in readerConfigurationName for the specified reader definitions. The operation attribute of any referenced reader configurations must either match the type attribute of the recipe or be DO_NOTHING e.g. `{"xarray-11-22-33.impinj.com":"Example_ReaderConfiguration",` `"xarray-44-55-66.impinj.com":"Another_ReaderConfiguration"}`

Location Recipes:

Property	Type	Description
tagHeartbeatDuration (optional)	String	This is used to control how frequently the lastModifiedTime of a tag is updated when the tag is read but has not moved. Set with a string in ISO 8601 format. representing the time interval between heartbeat updates. Example = "PT10", Minimum = "PT1M", Default = "PT5M"
tagExpiryDuration (optional)	String	A string in ISO 8601 format. representing the time interval between the last time ItemSense detected a tag, and the tag being marked ABSENT. If this parameter is not set, ABSENCE detection via tag expiration is disabled. If set, this parameter must be greater than the reportingInterval. This parameter is only available for certain combinations of reader configuration parameters: those that allow ItemSense to receive sufficient data to determine whether a tag has indeed gone absent. Allowable combinations: configuration.operation=LOCATION configuration.operation=INVENTORY and configuration.searchMode=DUAL_TARGET Forbidden combinations: configuration.operation=INVENTORY and configuration.searchMode=SINGLE_TARGET
minimumMovementInMeters (optional)	Decimal	Minimum distance a tag must move for a change in location to be reported. Only valid when type is set to LOCATION. When set to 0 (the minimum value for this parameter, any location change is reported Default=1, Minimum=0, Resolution=0.5
computeWindow (optional)	Integer	Amount of time in seconds that an EPC is kept in memory for location calculations. Must be greater than or equal to reportingInterval. Greater values will reduce noise and increase location accuracy, lesser values will increase responsiveness, Default = 10
reportingInterval (optional)	Integer (0 or divisor of 60.)	Frequency in seconds with which the location calculation is performed. Greater values will reduce system load, while lesser values will report changes more quickly. Zero will effectively result in a reporting interval of 500ms. Default = 5

Inventory Recipes:

Property	Type	Description
tagHeartbeatDuration (optional)	String	This is used to control how frequently the lastModifiedTime of a tag is updated when the tag is read but has not moved. Set with a string in ISO 8601 format. representing the time interval between heartbeat updates. Example = "PT10", Minimum = "PT1M", Default = "PT5M"
tagExpiryDuration (optional)	String	A string in ISO 8601 format. representing the time interval between the last time ItemSense detected a tag, and the tag being marked ABSENT. If this parameter is not set, ABSENCE detection via tag expiration is disabled. If set, this parameter must be greater than the reportingInterval. This parameter is only available for certain combinations of reader configuration parameters: those that allow ItemSense to receive sufficient data to determine whether a tag has indeed gone absent. Allowable combinations: configuration.operation=LOCATION configuration.operation=INVENTORY and configuration.searchMode=DUAL_TARGET Forbidden combinations: configuration.operation=INVENTORY and configuration.searchMode=SINGLE_TARGET
computeWindow (optional)	Integer	Internal use only.
reportingInterval (optional)	Integer (Divisor of 60.)	Frequency in seconds with which the inventory calculation is performed. Greater values will reduce system load, while lesser values will report changes more quickly. Default = 5

Threshold Recipes:

Property	Type	Description
thresholdIds (optional)	List	The collection of threshold identifiers to use for this recipe. If omitted, empty, or `null`, when this recipe is used in a job, all thresholds in the job's facility will be used. example = [1, 4]
profile (optional)	String	Custom profile data specifying system behavior. If not specified, defaults will be used. Use only under Impinj guidance.
iterationDataLogEnabled (optional)	boolean	Enables or disables the logging of iteration data for use in tuning. Defaults to disabled (false).

Sample Code

var body = {
    "name": "MY_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "READER_CONFIGURATION",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT7M",
    "minimumMovementInMeters": "1.5",
    "computeWindow": "10",
    "reportingInterval": "5",
};

xhr.open("POST", "http://BASE_URL/configuration/v1/recipes/create", true)
// Set authorization headers
xhr.send(body)

var body = {
    name = "MY_RECIPE",
    readerConfigurationName = "READER_CONFIGURATION",
    readerConfigurations = new Dictionary<string, string>(){
        {"xarray-11-22-33.impinj.com", "Example_ReaderConfiguration"},
        {"xarray-44-55-66.impinj.com", "Another_ReaderConfiguration"}
    },
    tagHeartbeatDuration = "PT5M",
    tagExpiryDuration = "PT7M",
    minimumMovementInMeters = 1.5,
    computeWindow = 10,
    reportingInterval = 5,
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/recipes/create");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
// Encode credentials and add to request header
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(recipe);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "MY_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "READER_CONFIGURATION",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT7M",
    "minimumMovementInMeters": "1.5",
    "computeWindow": "10",
    "reportingInterval": "5",
}

Update Recipe

Replace an existing recipe, or create a new one

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/recipes/createOrReplace

Request Body

The same as the Create Recipe Request Body.

Sample Code

var body= {
    "name": "InventoryRecipe",
    "type": "INVENTORY",
    "readerConfigurationName": "INVENTORY_READER_CONFIG",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT7M",
    "computeWindow": "2",
    "reportingInterval": "1",
};

xhr.open("PUT", "http://BASE_URL/configuration/v1/recipes/createOrReplace", true)
// Set authorization headers
xhr.send(body)

// Encode credentials
string encodedCredentials = ...
var recipe = {
    name = "InventoryRecipe",
    type = "INVENTORY,
    readerConfigurationName = "INVENTORY_READER_CONFIG",
    tagHeartbeatDuration = "PT5M",
    tagExpiryDuration = "PT3M",
    computeWindow = "2",
    reportingInterval = "1"
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/recipes/createOrReplace");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response for RecipeInventory

{
    "name": "InventoryRecipe",
    "type": "INVENTORY",
    "readerConfigurationName": "INVENTORY_READER_CONFIG",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT3M",
    "computeWindow": "2",
    "reportingInterval": "1",
}

Delete Recipe

Delete a specific recipe from the store

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/recipes/destroy/{recipeName}

Path Parameters

Parameter	Type	Description
recipeName	String	The name of the recipe to delete

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("DELETE", "http://BASE_URL/configuration/v1/recipes/destroy/MY_RECIPENAME", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/recipes/destroy/MY_RECIPENAME);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "DELETE";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Show Recipe

Show a specific recipe

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/recipes/show/{recipeName}

Path Parameters

Parameter	Type	Description
recipeName	String	The name of the recipe to retrieve

Sample Code

// var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/recipes/show/MY_RECIPENAME", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/recipes/show/MY_RECIPENAME);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "NEW_RECIPE_CONFIG",
  "type": "LOCATION",
  "readerConfigurationName": "IMPINJ_LocationConfig",
  "tagHeartbeatDuration": "PT5M",
  "tagExpiryDuration": "PT20S",
  "readerConfigurations": {},
  "minimumMovementInMeters": null,
  "computeWindow": 20,
  "reportingInterval": 5
}

Show Recipes

Show all configured recipes

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/recipes/show

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/recipes/show", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/recipes/show);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "INVENTORY_RECIPE",
    "type": "INVENTORY",
    "readerConfigurationName": "IMPINJ_InventoryConfig",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": null,
    "readerConfigurations": {},
    "computeWindow": 20,
    "reportingInterval": 5
  },
  {
    "name": "LOCATION_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "IMPINJ_LocationConfig",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": null,
    "readerConfigurations": {},
    "minimumMovementInMeters": 1,
    "computeWindow": 10,
    "reportingInterval": 5
  }
]

Jobs

An ItemSense job runs a recipe to generate item data.

Start a Job

When a job is started, ItemSense will attempt to use all readers in the specified facility that have not been given a configuration of "DO_NOTHING" in the recipe. If you wish to have a job use a subset of these readers you will need to specify a reader group or groups. Reader groups are defined as part of a reader's definition. When a reader group is specified for the job, only readers that have a matching group will be used.

Authorized Roles

JobRunner, Admin

HTTP Request

POST http://BASE_URL/control/v1/jobs/start

Request Body

Property	Type	Description
name (optional)	String	The optional name of the job
recipeName (required)	String	Which recipe to run
facility (optional, except if using multiple facilities)	String	The name of the facility which the job will be run in
durationSeconds (optional)	Integer	The number of seconds for which ItemSense should execute this job. If zero, null, or absent, then the job runs indefinitely
startDelay (optional)	String	An ISO 8601 format duration for which to delay the job's start. If not specified, defaults to 3 minutes, "PT3M"
readerGroups (optional)	Array of: String	The set of reader groups on which to start the job. May not be specified when a threshold recipe is used
reportToDatabaseEnabled (optional)	Boolean	Flag for determining if the job should relay tag reads into the Items database. Note that if this value if false, then data is not available via the Items API. Defaults to true
reportToHistoryEnabled (optional)	Boolean	Flag for determining if the job should relay tag reads into the Item History database. Note that if this value if false, then data is not available via the Item History API. Defaults to true
reportToMessageQueueEnabled (optional)	Boolean	Flag for determining if the job should report configured queue events. Note that if this value is false, then data is not available via the Message Queue interface. Defaults to true
useOtherJobData (optional)	Boolean	Flag for determining if the job should consider data from previous or other active jobs when calculating item zone changes. Defaults to true
reportToFileEnabled * (obsolete)	Boolean	This flag is obsolete and setting it will have no effect

Response

Parameter	Type	Description
id	String	The ID of the job in UUID format
status	One of: WAITING, INITIALIZING, STARTING, RUNNING, RESTARTING_RDE, STOPPING, STOPPED	The status of the job
readerNames	Array of: String	The collection of readers to which the job applies
failedReaderNames	Array of: String	The collection of readers that did not acknowledge job start
creationTime	String	The time the job was created in ISO 8601 format such as "2017-05-02T15:35:01.560Z"
lastActivityTime	String	The time of last activity in ISO 8601 format such as "2017-05-02T15:35:01.560Z"
activeDuration	Integer	The duration (in seconds) for which the job has been active
errorOccurred	Boolean	True when an error has occurred
errors	Array of: JobError	A list of errors associated with the job
maxErrors	Integer	The maximum number of errors kept
stopReason	One of: JOB_COMPLETED, JOB_FAILED, USER_REQUESTED_GRACEFUL, USER_REQUESTED_ABRUPT	The reason the job was stopped
facilities	Array of: String	The facility associated with this job contained in an array of length 1.
job	Job	The configuration data associated with the job
instanceMetadata	JobInstanceMetadata	Internal data used by ItemSense
lastHeartbeatTime	String	The time of last received heartbeat in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
startAttempts	Integer	The number of times the system has attempted to start the job

JobError

Parameter	Type	Description
time	String	The time that the error occured in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
message	String	The job error message

Sample Code

var job =  {
               recipeName: "IMPINJ_BasicLocation",
               name: "Basic Location Job",
               durationSeconds: 60,
               readerGroups: [ "ceiling", "store_room" ]
             };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/jobs/start", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(job));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/start");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                recipeName = "IMPINJ_BasicLocation",
                name = "Basic Location Job",
                durationSeconds = 60,
                readerGroups = new string[] { "ceiling", "store_room" }
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": "ebc86633-599c-4de9-8aa0-b11ffcb8bdc5",
  "status": "WAITING",
  "readerNames": [
    "READER1",
    "READER2"
  ],
  "creationTime": "2016-06-28T17:27:20.106Z",
  "lastActivityTime": "2016-06-28T17:27:20.106Z",
  "activeDuration": "PT0S",
  "errorOccurred": false,
  "errors": [],
  "maxErrors": 5,
  "stopReason": null,
  "facilities": [
    {
      "name": "HOME"
    }
  ],
  "job": {
    "name": "Basic Location Job",
    "recipeName": "RECIPE1",
    "durationSeconds": 100,
    "startDelay": "PT1M",
    "readerGroups": [ "ceiling", "store_room" ],
    "reportToDatabaseEnabled": true,
    "reportToHistoryEnabled": true,
    "reportToMessageQueueEnabled": true,
    "reportToFileEnabled": false,
    "useOtherJobData": true,
    "facility": "HOME"
  },
  "instanceMetadata": null,
  "lastHeartbeatTime": null,
  "startAttempts": 0
}

Stop a Running Job

Authorized Roles

JobRunner, Admin

HTTP Request

POST http://BASE_URL/control/v1/jobs/stop/{jobId}

Parameters

Parameter	Type	Description
jobId	String	The ID of the job to stop
graceful	Boolean	Whether the job should be stopped gracefully or suddenly (defaults to true)

Sample Code


var jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/jobs/stop/" + jobId, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/stop/" + jobId);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get a specific Job

Retrieve a specific job and its status

Authorized Roles

JobRunner, Admin

HTTP Request

GET http://BASE_URL/control/v1/jobs/show/{jobId}

Parameters

Parameter	Type	Description
jobId	String	The ID of the job to retrieve

Response

The same as the Create Recipe Request Body.

Sample Code

var jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/control/v1/jobs/show/" + jobId, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/show/" + jobId);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

The same as Jobs Start Sample Response

Get All Jobs

Authorized Roles

JobRunner, Admin

HTTP Request

GET http://BASE_URL/control/v1/jobs/show

Parameters

Parameter	Type	Description
startedBefore	String	Filter to jobs that have been started before the given time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
startedAfter	String	Filter to jobs that have been started after the given time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
lastActivityBefore	String	Filter to jobs that have the last activity time before the given time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
lastActivityAfter	String	Filter to ZonedDateTimeParam that have the last activity time after the given time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
sortBy	One of: name, creationTime, lastActivityTime	The property by which to sort the returned jobs. Defaults to lastActivityTime
sortOrder	One of: asc, desc	Whether to sort the jobs in ascending or descending order. Defaults to descending
status	Array	Filter to jobs that match the given status, can be supplied multiple times
latest	Integer	Filter to latest N jobs. Defaults to 1.

Response

Array of: Jobs Start Response

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/jobs/show/", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

An array of: Jobs Start Sample Response

Items

An Item is any object fixed with an RFID tag. This API conducts item-level data queries for subsets matching supplied criteria (such as location).

The API is very simple, with just three endpoints; one to show items, another to show the history of items and the final to show when items transition through monitored thresholds.

Get Items

Query current items.

Authorized Roles

DataReader, Admin

HTTP Request

GET http://BASE_URL/data/v1/items/show

Properties

Property	Type	Description
epcPrefix (optional)	String	A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
jobId (optional)	String	A UUID job identifier, such as "ffa29f71-f0f9-426e-9ba4-45398361dc5d". This property identifies the job that last saw the item.
zoneNames (optional)	String	A comma-separated list of zone names. Only items in these zones will be returned
facility (optional)	String	A string indicating the name of a facility. Only items in this facility will be returned
presenceConfidence (optional)	One of: HIGH, LOW	(deprecated) - passing either value has no effect on the query, producing the same result as not including the property at all.
fromTime (optional)	String	Items which were last updated on or after this time in ISO-8601 format such as "2017-05-02T15:35:01.560Z".
toTime (optional)	String	Items which were updated before this time in ISO-8601 format such as "2017-05-02T15:35:01.560Z".
epcFormat (optional)	One of: PURE_ID TAG RAW UPC12 DEFAULT	Format of the EPC string. Defaults to raw hex strings if this property is not specified. All the options except DEFAULT and RAW will return only results with valid encoding. DEFAULT option gives the default format for the encoding. If the EPC is not encoded correctly, then the RAW format is used
pageMarker (optional)	String	A string indicating which page of results to return. A new marker is returned after each query and can be used to fetch subsequent pages. When using a page marker, the other query properties must be the same as those used in the previous query.
pageSize (optional)	Integer	The number of records to return per query (Max of 1000, defaults to 100)

Response

Property	Type	Description
items	Array of:Item	The list of currently detected items

Sample Code

var xhr = new XMLHttpRequest();
//return the next page's data 

//Note: Libraries such as JQuery.Param({pageMarker: "u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk"}) simplifies handling of query parameters.
var url = sprintf("http://BASE_URL/data/v1/items/show?pageMarker=%1$s", encodeURIComponent("u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk") );
xhr.open("GET", url, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string url = String.Format("http://BASE_URL/data/v1/items/show/history?pageMarker={0}", Uri.EscapeDataString("ZmeLu/fWX4e+s1CUxOxeXrrMdV415+LcdzEnZiFeUavMkEKYzZCcwwV8CKFUcUJI") );

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(url);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";

2   
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "items":[
      {
         "epc":"111100000000000000000019",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "xLocation":6.3,
         "yLocation":9.2,
         "zLocation":0,
         "zone":"ZONE1",
         "facility":HOME,
         "presenceConfidence":"HIGH",
         "lastModifiedTime":"2016-02-23T00:38:42Z"
      },
      {
         "epc":"300833B2DDD9000500010004",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "xLocation":1.9,
         "yLocation":2.1,
         "zLocation":0,
         "zone":"ZONE2",
         "facility":"HOME",
         "presenceConfidence":"HIGH",
         "lastModifiedTime":"2016-02-23T00:37:57Z"
      }
  ],
  "nextPageMarker": "bozBcaT89jaLIuUy+gdkWm8xz8FRimZz8++6HHecp9vNvz4PLFxwZeCWAN666lTE"
}

Get Item History

Query the history of items. A historic record for an item is created each time an Item transitions from one zone to another.

Authorized Roles

DataReader, Admin

HTTP Request

GET http://BASE_URL/data/v1/items/show/history

Properties

Property	Type	Description
epcPrefix (optional)	String	A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
jobId (optional)	String	A UUID job identifier, such as "ffa29f71-f0f9-426e-9ba4-45398361dc5d". This property identifies the job that reported the change in the item.
fromZone (optional)	String	A string zone identifier, such as "Men's Department". This property identifies the zone that the item moved out of.
toZone (optional)	String	A string zone identifier, such as "Men's Department". This property identifies the zone that the item moved into.
fromFacility (optional)	String	A string facility identifier, such as "Seattle Location". This property identifies the facility that the item moved out of.
toFacility (optional)	String	A string facility identifier, such as "Seattle Location". This property identifies the facility that the item moved into.
fromTime (optional)	String	Events which occurred on or after this time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
toTime (optional)	String	Events which occurred before this time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
epcFormat (optional)	One of: PURE_ID, TAG, RAW, UPC12, DEFAULT	Format of the EPC string. Defaults to raw hex strings if this property is not specified. All the options except DEFAULT and RAW will return only results with valid encoding.DEFAULT option gives the default format for the encoding. If the EPC is not encoded correctly, then the RAW format is used.
zoneTransitionsOnly (optional)	Boolean	Will restrict results to items that moved zones, defaults to true
minDistanceMoved (optional)	Number	Will restrict results to items that moved more than the minimum distance supplied (in meters).
pageMarker (optional)	String	A string indicating which page of results to return. A new marker is returned after each query and can be used to fetch subsequent pages. When using a page marker, the other query properties must be the same as those used in the previous query. When paired with the nextPageMarker field, this flag is beneficial for re-querying the same filtered data set at a later time, and expecting to only see the newest records.
pageSize (optional)	Integer	The number of records to return per query. The maximum value of this property is 1000. The default value is 100.
alwaysIncludePageMarker (optional)	Boolean	Always include the page marker in the query results.

Response

Property	Type	Description
history	Array of: ItemEvent	A list of item events filtered according to the submitted query
nextPageMarker	String	A string representing the place in the history where the next set of records begin
moreHistoryAvailable	Boolean	Whether there is more history available or this is the last set of records

Sample Code

var xhr = new XMLHttpRequest();
//return the next page's data 

//Note: Libraries such as JQuery.Param({pageMarker: "u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk"}) will simply handling query properties.
var url = sprintf("http://BASE_URL/data/v1/items/show/history?pageMarker=%1$s", encodeURIComponent("u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk") );
xhr.open("GET", url, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

//return the next page's data
string url = String.Format("http://BASE_URL/data/v1/items/show/history?pageMarker={0}", Uri.EscapeDataString("ZmeLu/fWX4e+s1CUxOxeXrrMdV415+LcdzEnZiFeUavMkEKYzZCcwwV8CKFUcUJI") );

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(url);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "history":[
      {
         "epc":"5BBA7E85407C51D8",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "fromZone":"ZONE1",
         "toZone":"ZONE2",
         "fromFacility":DEFAULT,
         "fromFloor": "1"
         "toFacility":"DEFAULT",
         "toFloor": "1"
         "fromX":12,9,
         "fromY":10.4,
         "toX":2.4,
         "toY":2.7,
         "observationTime":"2016-02-23T00:37:16Z"
      },
      {
         "epc":"111100000000000000000019",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "fromZone":"ZONE2",
         "toZone":"ZONE1",
         "fromFacility":null,
         "fromFloor": "1",
         "toFacility":"DEFAULT",
         "toFloor": "1",
         "fromX":null,
         "fromY":null,
         "toX":12.2,
         "toY":10.7,
         "observationTime":"2016-02-23T00:37:16Z"
      }
  ],
  "nextPageMarker": "xjR3rD6qFcV+p3yUurz0FIMSYHqxarq6xuvgVSFvU+crHVRshQ789d5TO6UI5m9w",
  "moreHistoryAvailable": true
}

Get Item Threshold Transitions

Query the transitions of items through facility thresholds. When running with threshold transitions configured a record of each transition for each item is kept.

Authorized Roles

DataReader, Admin

HTTP Request

GET http://BASE_URL/data/v1/items/show/transitions

Properties

Property	Type	Description
epcPrefix (optional)	String	A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned.
jobId (optional)	String	A UUID job identifier, such as "ffa29f71-f0f9-426e-9ba4-45398361dc5d". This property identifies the job that reported the transition of the item.
thresholdId (optional)	Integer	A numeric threshold ID. Only items that transitioned through this threshold will be returned. If provided, thresholdName must not be used.
thresholdName (optional)	String	A string threshold name. Only items that transitioned through this threshold will be returned. If provided, thresholdId must not be used.
destination (optional)	String	A string destination identifier, such as "OUT". This property identifies the destination that the item transitioned to.
facility (optional)	String	A facility name. Only transitions that occurred through thresholds in this facility will be returned. Additionally specifying a threshold (by name or by id) is allowed but not useful.
fromTime (optional)	String	Events which occurred on or after this time in ISO-8601 format such as "2017-05-02T15:35:01.560Z".
toTime (optional)	String	Events which occurred before this time in ISO-8601 format such as "2017-05-02T15:35:01.560Z".
epcFormat (optional)	One of: PURE_ID, TAG, RAW, UPC12, DEFAULT	Format of the EPC string. Defaults to raw hex strings if this property is not specified. All the options except DEFAULT and RAW will return only results with valid encoding.DEFAULT option gives the default format for the encoding. If the EPC is not encoded correctly, then the RAW format is used.
pageMarker (optional)	String	A string indicating which page of results to return. A new marker is returned after each query and can be used to fetch subsequent pages. When using a page marker, the other query properties must be the same as those used in the previous query. When paired with the nextPageMarker field, this flag is beneficial for re-querying the same filtered data set at a later time, and expecting to only see the newest records.
pageSize (optional)	Integer	The number of records to return per query. The maximum value of this property is 1000. The default value is 100.
alwaysIncludePageMarker (optional)	Boolean	Always include the page marker in the query results.

Response

Property	Type	Description
transitions	Array of: ItemThresholdTransitionEvent	A list of item threshold transition events filtered according to the submitted query
nextPageMarker	String	A string representing the place in the history where the next set of records begin
moreTransitionsAvailable	Boolean	Whether there is are more transition records available or this is the last set of records

Sample Code

var xhr = new XMLHttpRequest();
//return the next page's data 

//Note: Libraries such as JQuery.Param({pageMarker: "u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk"}) will simply handling query properties.
var url = sprintf("http://BASE_URL/data/v1/items/show/transitions?pageMarker=%1$s", encodeURIComponent("u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk") );
xhr.open("GET", url, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

//return the next page's data
string url = String.Format("http://BASE_URL/data/v1/items/show/transitions?pageMarker={0}", Uri.EscapeDataString("ZmeLu/fWX4e+s1CUxOxeXrrMdV415+LcdzEnZiFeUavMkEKYzZCcwwV8CKFUcUJI") );

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(url);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "transitions":[
    {
      "thresholdTransitionId": 1,
      "epc": "epc1",
      "jobId": "jobid1",
      "thresholdId": 1,
      "destination": "out",
      "confidence": 1,
      "creationTime": "2017-03-01T22:46:59Z"
    },
    {
      "thresholdTransitionId": 2,
      "epc": "epc2",
      "jobId": "jobid1",
      "thresholdId": 1,
      "destination": "out",
      "confidence": 1,
      "creationTime": "2017-03-01T22:48:10Z"
    },
    {
      "thresholdTransitionId": 3,
      "epc": "epc3",
      "jobId": "jobid1",
      "thresholdId": 1,
      "destination": "out",
      "confidence": 1,
      "creationTime": "2017-03-01T22:48:15Z"
    }
  ],
  "nextPageMarker": "xjR3rD6qFcV+p3yUurz0FIMSYHqxarq6xuvgVSFvU+crHVRshQ789d5TO6UI5m9w",
  "moreTransitionsAvailable": true
}

Item Data Message Queue

ItemSense provides an AMQP-based real-time event push system in addition to its REST query APIs.

A queue is configured with a specific query. Clients can then connect to that queue to receive messages matching the configured query.

Each property in the request body acts as a filtered item for that specific queue. If multiple properties are present in the request body, queue messages will only be created if all filtered properties are matched.

Authorized Roles

DataReader, Admin

HTTP Request

PUT http://BASE_URL/data/v1/items/queues

Properties

Property	Type	Description
deliveryMode (optional)	One of: NON_PERSISTENT PERSISTENT	Defaults to NON_PERSISTENT if this property is not specified. If PERSISTENT is specified, messages will be written to disk to be recovered in the event of an outage. This will utilize more disk space and affect performance.

Request Body

Property	Type	Description
fromFacility (optional)	String	The name of a facility to monitor for tag exit events
toFacility (optional)	String	The name of a facility to monitor for tag entry events
fromZone (optional)	String	The name of the zone to monitor for tag exit events
toZone (optional)	String	The name of the zone to monitor for tag entry events
epc (optional)	String	A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
jobId (optional)	String	The ID of the job to monitor for tag events
distance (optional)	Number	The minimum distance a tag must move before a queue event (or message) is created
zoneTransitionsOnly (optional)	Boolean	Flag to only create queue events for tags that have transitioned between zones. Default value is true.

Sample Code

// Note: this is nodejs code. AMQP cannot be used directly using browser code
var XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
var amqp = require('amqp');

var messageQueue = {
 fromZone: "BACK_OF_STORE",
 toZone: "FRONT_OF_STORE"
};

var queueConfig = {
  durable: true,
  noDeclare: true,
  arguments: {
    'x-expires': 3600000,
    'x-message-ttl': 3600000,
    'x-max-length-bytes': 1073741824
  }
};

var xhr = new XMLHttpRequest();

xhr.onreadystatechange = function() {
    console.log("State: " + this.readyState);

    if (this.readyState === 4) {
        console.log("Complete.\nBody length: " + this.responseText.length);
        console.log("Body:\n" + this.responseText);
        console.log(this.responseText);

        var queueInfo = JSON.parse(this.responseText);

        createConnection(queueInfo)
            .then((connection) => {
              console.log('Connection established');
              return createQueue(connection, queueInfo);
            })
            .then((newQueue) => {
              console.log('Queue established');
              return createSubscription(newQueue);
            });
    }
};

xhr.open("PUT", "http://BASE_URL/data/v1/items/queues?deliveryMode=NON_PERSISTENT", true);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(messageQueue));

function createConnection(queueInfo)  {
  return new Promise((resolve) => {
    const connection = amqp.createConnection({ url: queueInfo.serverUrl, login: "<USERNAME>", password: "<PASSWORD>"}, { reconnect: false });
    connection.on('ready', () => resolve(connection));
    connection.on('error', (err) => {
      console.log(`Error: ${err}`);
    });
  });
}

function createQueue(connection, queueInfo) {
  return new Promise((resolve) => {
    console.log(`Connecting to queue with ${queueInfo.queue} and ${JSON.stringify(queueConfig)}`);
    connection.queue(queueInfo.queue, queueConfig, queue => resolve(queue));
  });
}

function createSubscription(queue) {
  queue.subscribe((msg) => {
    console.log(`Message: ${msg.data}`);
  });
  console.log(`Listening`);
}

using System;
using System.Net;
using System.IO;
using System.Text;
using Newtonsoft.Json;
using RabbitMQ.Client;
using RabbitMQ.Client.Events;

namespace AMQP
{
    // Structure to store the AMQP data returned in the response
    class AMQPdata
    {
        public string serverUrl;
        public string queue;
    }

    // Request properties used to filter items for the message queue
    class requestParameters
    {
        public string fromZone="BACK_OF_STORE";
        public string toZone="FRONT_OF_STORE";
    }

    class Program
    {
        static int Main(string[] args)
        {
            string currentUser = "<USERNAME";
            string currentUserPassword = "<PASSWORD>";
            string BASE_URL = "...";
            string endpoint = "/data/v1/items/queues";

            HttpWebRequest httpRequest;
            HttpWebResponse httpResponse;
            AMQPdata amqp = new AMQPdata();
            requestParameters reqParams = new requestParameters();

            string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(currentUser + ":" + currentUserPassword));

            // Compose the request
            Uri uri = new Uri(BASE_URL + endpoint);
            httpRequest = (HttpWebRequest)HttpWebRequest.Create(uri);
            httpRequest.Headers.Add("Authorization", "Basic "+ encodedCredentials);
            httpRequest.Method = "PUT";
            httpRequest.ContentType = "application/json";

            // Add the request body
            using (var sw = new StreamWriter(httpRequest.GetRequestStream()))
            {
                // Put the request properties in JSON format for the request body
                string requestBody = JsonConvert.SerializeObject(reqParams);
                Console.WriteLine("Request body in JSON format: " + requestBody);
                sw.Write(requestBody);
            }

            // Send the request and get the response
            httpResponse = (HttpWebResponse)httpRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                // Save the JSON data returned in the response and then convert it to the AMQPdata structure 
                var amqpJSON = streamReader.ReadToEnd();
                var amqpConvertedFromJSON = JsonConvert.DeserializeObject<AMQPdata>(amqpJSON);
                amqp.serverUrl = amqpConvertedFromJSON.serverUrl.Replace("://", string.Format("://{0}:{1}@", currentUser, currentUserPassword));
                amqp.queue = amqpConvertedFromJSON.queue;

                // Print the reader data returned in the REST response
                Console.WriteLine("\nAMQP data returned in JSON format: " + amqpJSON + "\n");
                Console.WriteLine("\n  -- Parsed data --" +
                                  "\n  Server URL: " + amqp.serverUrl +
                                  "\n  Queue: " + amqp.queue +  "\n");                                   
            }

            // Open an AMQP connection and set up the queue for receiving messages
            ConnectionFactory factory = new ConnectionFactory();
            factory.Uri = new Uri(amqp.serverUrl);
            factory.AutomaticRecoveryEnabled = true;     

            using (var connection = factory.CreateConnection())
            using (var channel = connection.CreateModel())
            {
                Console.WriteLine("waiting");

                var consumer = new EventingBasicConsumer(channel);
                consumer.Received += (model, ea) =>
                {
                    var body = ea.Body;
                    var message = Encoding.UTF8.GetString(body);
                    Console.WriteLine("Message: {0}", message);
                };

                Console.WriteLine(channel.BasicConsume(queue: amqp.queue, autoAck: true, consumer: consumer));
                Console.WriteLine("Waiting for results. Hit Enter to Exit");
                Console.ReadLine();
            }       

            return 0;
        }
    }
}

Sample Response for Queue Configuration

{
  "serverUrl": "amqp://localhost:5672/%2F",
  "queue": "1127b6d0c96f6c55d42e54b390f9a6c50fc4911b956c1a3128a2e26c3f6481cd"
}

Sample Response for Message Reception

Message: {"epc":"F7091D9A2B9538B689F53AB8", ... observationTime":"2018-03-30T22:48:18.886Z","fromZone":"BACK_OF_STORE","toZone":"FRONT_OF_STORE", ... "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", ...}
Message: {"epc":"02CBA4FF091338C2A35ADB86", ... "observationTime":"2018-03-30T22:48:18.888Z","fromZone":"BACK_OF_STORE","toZone":"FRONT_OF_STORE", ... "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", ...}
Message: {"epc":"C38B2994C7BA3AD68961A233",... "observationTime":"2018-03-30T22:48:18.89Z","fromZone":"BACK_OF_STORE","toZone":"FRONT_OF_STORE", ... "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", ...}
Message: {"epc":"E7E92B38AB2C362497818237","observationTime":"2018-03-30T22:48:18.893Z","fromZone":"BACK_OF_STORE","toZone":"FRONT_OF_STORE", ... "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", ...}
Message: {"epc":"02D9D40D17A63E9595EB6890","observationTime":"2018-03-30T22:48:18.895Z","fromZone":"BACK_OF_STORE","toZone":"FRONT_OF_STORE", ... "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", ... }

Queue Message Data

Once a message queue has been configured, messages that match the filter criteria will be appended to the queue. The structure of each element in the queue is the same as an ItemEvent record in the Item History list. Idle queues (those without messages or a consumer) will be removed after one hour of inactivity. Empty queues with a consumer will remain active provided the connection uses the heartbeat mechanism. For AMQP best practices, see RabbitMQ Tutorials.

Threshold Data Message Queue

ItemSense provides an AMQP-based real-time event push system in addition to its REST query APIs.

A threshold queue is configured with a specific query. Clients can then connect to that queue to receive messages matching the configured query.

Authorized Roles

DataReader, Admin

HTTP Request

PUT http://BASE_URL/data/v1/items/queues/threshold

Properties

Property	Type	Description
deliveryMode (optional)	One of: NON_PERSISTENT PERSISTENT	Defaults to NON_PERSISTENT if this property is not specified. If PERSISTENT is specified, messages will be written to disk to be recovered in the event of an outage. This will utilize more disk space and affect performance.

Request Body

Property	Type	Description
threshold (optional)	String	The name of a threshold to monitor for events
jobId (optional)	String	The ID of the job to monitor for events

Sample Code

var messageQueue = {
 threshold: "REAR_THRESHOLD"
};

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/data/v1/items/queues/threshold?deliveryMode=NON_PERSISTENT", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(messageQueue));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

var messageQueue = new
                  {
                    threshold = "REAR_THRESHOLD"
                  };

Uri uri = new Uri("http://BASE_URL/data/v1/items/queues/threshold?deliveryMode=NON_PERSISTENT");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(messageQueue);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "serverUrl": "amqp://localhost:5672/%2F",
  "queue": "1127b6d0c96f6c55d42e54b390f9a6c50fc4911b956c1a3128a2e26c3f6481cd"
}

Threshold Queue Message Data

Once a message queue has been configured, messages that match the filter criteria will be appended to the queue.

The structure of each element in the queue is an ItemThresholdTransitionEvent.

Data Definitions

Item

Property	Type	Description
epc (optional)	String	The EPC of the item
tagId (not curently provided)	String	The ID of the tag that was read. Note that ItemSense does not currently provide the tagId, and the value of this field is always set to "000000000000"
jobId (optional)	String	The ID of the job that last saw the item
xLocation (optional)	Float	The x coordinate of the item's location
yLocation (optional)	Float	The y coordinate of the item's location
zLocation (optional)	Float	The z coordinate of the item's location
zone (optional)	String	The name of the zone in which the item was read
floor (optional)	String	The name of the floor on which the item was read
facility (optional)	String	The facility in which the item was read
presenceConfidence (optional)	String	(deprecated) - always returns `HIGH`. This value should no longer be relied upon as an indication of presence confidence.
lastModifiedTime (optional)	String	The time at which the item was read in ISO-8601 format such as "2017-05-02T15:35:01.560Z"

ItemEvent

Property	Type	Description
epc (optional)	String	The EPC of the tag for which the event occurred
tagId (optional)	String	The ID of the tag that was read. Note that ItemSense does not currently provide the tagId, and the value of this field is always set to "000000000000"
jobId (optional)	String	The ID of the job that reported the change in the item
fromZone (optional)	String	The name of the zone from which the tag moved
toZone (optional)	String	The name of the zone to which the tag moved
fromFloor (optional)	String	The name of the floor from which the tag moved
toFloor (optional)	String	The name of the floor to which the tag moved
fromFacility (optional)	String	The name of the facility from which the tag moved
toFacility (optional)	String	The name of the facility to which the tag moved
fromX (optional)	Float	The x coordinate of the location from which the tag moved
toX (optional)	Float	The x coordinate of the location to which the tag moved
fromY (optional)	Float	The y coordinate of the location from which the tag moved
toY (optional)	Float	The y coordinate of the location to which the tag moved
observationTime (optional)	String	The time at which the event occurred in ISO-8601 format such as "2017-05-02T15:35:01.560Z"

ItemThresholdTransitionEvent

Property	Type	Description
epc (optional)	String	The EPC of the tag for which the event occurred
thresholdTransitionId (optional)	Integer	The ID of the specific transition record
jobId (optional)	String	The ID of the job that generated the transition record
thresholdId (optional)	Integer	The ID of the threshold where this transition occurred
destination (optional)	String	The name of the destination that the item transitioned to
confidence (optional)	Float	The confidence value of the transition event
creationTime (optional)	String	The time at which the transition was recorded in ISO-8601 format such as "2017-05-02T15:35:01.560Z"

QueuedThresholdTransitionEvent

Property	Type	Description
epc (optional)	String	The EPC of the tag for which the event occurred
observationTime (optional)	Integer	The time at which the transition was recorded in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
fromZone (optional)	String	The type of transition, being "IN" or "OUT" this will always be the opposite value of toZone
toZone (optional)	String	The type of transition, being "IN" or "OUT" this will always be the opposite value of fromZone
threshold (optional)	String	The name of the threshold where this transition occurred
dockDoor (optional)	String	Deprecated. This property duplicates the `threshold` property and exists for backwards compatibility only.
jobId (optional)	String	The ID of the job that generated the transition record
confidence (optional)	Float	The confidence value of the transition event

Health

A read-only interface to query reader health status

Reader

Show the health of a single reader

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

GET http://BASE_URL/health/v1/readers/{readerName}

Path Parameters

Parameter	Type	Description
readerName	String	The name of the reader

Response

Parameter	Type	Description
readerName	String	The name of the reader
state	One of: AWAITING_AGENT IDLE RUNNING_JOB UPDATING_FIRMWARE NOT_RESPONDING ERROR	The state of the reader
lastCheckin	String	The time at which the reader last contacted itemsense in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
lastReboot	String	The time at which the reader was last re-booted in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
version	object	The version of firmware that the reader is running
connectionStatus	ConnectionStatus	The status of the health and monitoring connection to the reader
throughputStatus	ThroughputStatus	The throughput status of the reader
clockSyncStatus	ClockSyncStatus	The clock sync status of the reader
hardwareStatus	HardwareStatus	The hardware status of the reader
softwareStatus	SoftwareStatus	The software status of the reader

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/health/v1/readers/MY_READERNAME", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/readers/MY_READERNAME);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "readerName": "xArray-11-4D-3D",
  "state": "IDLE",
  "lastCheckin": "2016-08-23T15:33:59.496Z",
  "lastReboot": "2016-08-23T14:41:33.378Z",
  "version": {
    "App": "0.0.1.15",
    "Firmware": "5.6.2.240"
  },
  "connectionStatus": {
    "status": "HEALTHY",
    "code": null
  },
  "throughputStatus": {
    "status": "HEALTHY",
    "code": null
  },
  "clockSyncStatus": {
    "status": "HEALTHY",
    "code": null,
  },
  "hardwareStatus": {
    "status": "HEALTHY",
    "code": null,
    "devices": null
  },
  "softwareStatus": {
    "status": "HEALTHY",
    "code": null
  }
}

Readers

Show the health of all readers

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

GET http://BASE_URL/health/v1/readers

Response

An array of: Reader Health Response

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/health/v1/readers", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/readers);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "readerName": "xArray-11-4D-3D",
    "state": "RUNNING_JOB",
    "lastCheckin": "2016-08-23T20:08:57.771Z",
    "lastReboot": "2016-08-23T16:02:24.410Z",
    "version": {
      "App": "0.0.1.15",
      "Firmware": "5.6.2.240"
    },
    "connectionStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "throughputStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "clockSyncStatus": {
      "status": "HEALTHY",
      "code": null,
    },
    "hardwareStatus": {
      "status": "HEALTHY",
      "code": null,
      "devices": null
    },
    "softwareStatus": {
      "status": "HEALTHY",
      "code": null
    }
  },
  {
    "readerName": "xArray-11-42-2B",
    "state": "IDLE",
    "lastCheckin": "2016-08-23T20:08:57.403Z",
    "lastReboot": "2016-08-23T19:36:19.390Z",
    "version": {
      "App": "0.0.1.15",
      "Firmware": "5.8.0.26"
    },
    "connectionStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "throughputStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "clockSyncStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "hardwareStatus": {
      "status": "HEALTHY",
      "code": null,
      "devices": null
    },
    "softwareStatus": {
      "status": "HEALTHY",
      "code": null
    }
  }
]

Events

Search health events

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

POST http://BASE_URL/health/v1/events

Request Body

Parameter	Type	Description
readerNames	Array of: String	The set of reader names for which to query health events
types	Array of: String	The set of status types for which to query health events
codes	Array of: String	The set of status codes for which to query health events
fromTime	String	The beginning of the query time period in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
toTime	String	The end of the query time period in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
pageSize	Integer	The number of events to return per query
nextPageMarker	String	The marker of the next page to return

Response

Parameter	Type	Description
events	Array of: HealthEvent	List of reader health events
nextPageMarker	String	The value of the marker to supply for the next page of reader health results

Sample Code

var body = {
    "types": ["LIFECYCLE"]
};
var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/health/v1/events", true)
// Set authorization headers
xhr.send(body)

var body = {
    "types": ["LIFECYCLE"]
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/events);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
using (StreamWriter sw = new StreamWriter(request.GetRequestStream())
{
    string data = new JavaScriptSerializer().Serialize(body);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "events": [
    {
      "eventTime": "2016-08-23T14:41:33.378Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "REBOOT",
      "args": {
        "reason": "BootReason='Cold'"
      }
    },
    {
      "eventTime": "2016-08-23T14:02:46.316Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "REBOOT",
      "args": {
        "reason": "BootReason='Cold'"
      }
    },
    {
      "eventTime": "2016-08-22T22:57:55.217Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "VERSION_UPDATE",
      "args": {
        "newVersion": "{\"App\":\"0.0.1.15\",\"Firmware\":\"5.6.2.240\"}"
      }
    },
    {
      "eventTime": "2016-08-22T22:57:54.337Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "REBOOT",
      "args": {
        "reason": "BootReason='Processor / Reboot'"
      }
    }
  ],
  "nextPageMarker": null
}

Event Queue

Configure a queue to receive health event messages with the given filter

A queue is configured with a specific query. Clients can then connect to that queue to receive messages matching the configured query.

Authorized Roles

Admin, DataReader

HTTP Request

PUT http://BASE_URL/health/v1/events/queues

Parameters

Parameter	Type	Description
deliveryMode (optional)	One of: NON_PERSISTENT PERSISTENT	Defaults to NON_PERSISTENT if this parameter is not specified. If PERSISTENT is specified, messages will be written to disk to be recovered in the event of an outage. This will utilize more disk space.

Request Body

Parameter	Type	Description
readerName	String	The name of the reader to query
type	One of: CONNECTION THROUGHPUT CLOCK_SYNC HARDWARE_FAULT SOFTWARE_FAULT LIFECYCLE UNCLASSIFIED	The type of health event to query
code	String	The status code to query

Response

Parameter	Type	Description
serverUrl	String	The URL of the reader health event queue
queue	String	The queue identifier

Sample Code

var body = {
    "readerName": "xArray-11-4D-3D",
    "type": "CONNECTION",
    "code": "NETWORK",
};
var xhr = new XMLHttpRequest()
xhr.open("PUT", "http://BASE_URL/health/v1/events/queues?deliveryMode=NON_PERSISTENT", true)
// Set authorization headers
xhr.send(body)

var body = {
    "readerName": "xArray-11-4D-3D",
    "type": "CONNECTION",
    "code": "NETWORK",
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/events/queues?deliveryMode=NON_PERSISTENT);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
using (StreamWriter sw = new StreamWriter(request.GetRequestStream())
{
    string data = new JavaScriptSerializer().Serialize(body);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "serverUrl": "amqp://localhost:5672/%2F",
  "queue": "8913429d-d11e-404f-ab1a-9c01da4a9f0a"
}

Data Definitions

Each of the Reader Status objects has a status and a code property. When the status is HEALTHY, the code will be null. When the status is WARNING or FAILED, the code should be one of several values (see Code Details below).

ConnectionStatus

Parameter	Type	Description
status	One of: HEALTHY WARNING FAILED	The status of the connection
code	One of: BAD_CERTIFICATE HTTP_FAILURE or NETWORK	See Code Details

ThroughputStatus

Parameter	Type	Description
status	One of: HEALTHY WARNING FAILED	The status of reader throughput
code	One of: DROPPED_READ REPORT_BUFFER TAG_POPULATION_OVERFLOW	See Code Details

ClockSyncStatus

Parameter	Type	Description
status	One of: HEALTHY WARNING FAILED	The status of network clock (NTP) synchronization
code	One of: NTP CLOCK_SYNC	See Code Details

HardwareStatus

Parameter	Type	Description
status	One of: HEALTHY WARNING FAILED	The hardware status
code	One of: READER_COMMAND READER_EXCEPTION READER_RESTART UPGRADE_STATUS	See Code Details
devices	Array of: DeviceStatus	The status of each hardware device (e.g. all of the antennas on a reader)

DeviceStatus

Parameter	Type	Description
device	String	The hardware device e.g. a specific antenna
code	String	An optional string code HealthCode associated with the status

SoftwareStatus

Parameter	Type	Description
status	One of: HEALTHY WARNING FAILED	The status of reader throughput
code	One of: CHECKSUM COMMAND_NOT_FOUND CONFIG_SERVICE_SET EXTERNAL_COMMAND FILE_SYSTEM INVALID_SET_VARIABLE UNMARSHAL LLRP PROVISIONING READER_CONNECTION CRASH AGENT_OUTDATED	See Code Details

HealthEvent

Parameter	Type	Description
eventTime	String	The time of the event in ISO 8601 format such as "2017-05-02T15:35:01.560Z"
readerName	String	The name of the reader
type	One of: CONNECTION THROUGHPUT CLOCK_SYNC HARDWARE_FAULT SOFTWARE_FAULT LIFECYCLE UNCLASSIFIED	The type of event
code	String	See Code Details
args	Object	Additional event-specific properties, often including a helpful message about the cause of the event

Code Details

Below is a listing of all valid Type and Code combinations as they can appear in Health Events and in Reader Statuses. The same codes are used in both places. Note that not every Health Event type maps to a Reader Status property, and there are no currently known codes that appear in a DeviceStatus.

#	Code	Reader Status Property	Description
1	BAD_CERTIFICATE	ConnectionStatus	1. During provisioning. If invalid certificate is supplied by the IMC when accessing the /provision endpoint. (Note that this process returns a certificate for use on the ItemSense agent channel) 2. After provisioning. If the returned certificate starts failing
2	HTTP_FAILURE	ConnectionStatus	Anytime ItemSense returns a non successful HTTP status code. Can also happen during provisioning, when the agent "tests" the ItemSense HTTP connection settings.
3	NETWORK	ConnectionStatus	Something else went wrong with the network connection. e.g. network timeout
4	DROPPED_READ	ThroughoutStatus	Agent data buffer overflow error
5	REPORT_BUFFER	ThroughputStatus	Internal agent buffer is full or nearly full (conditions are distinguished by a message on the health event)
6	TAG_POPULATION_OVERFLOW	ThroughputStatus	Too many tags (in direction or location mode)
7	NTP	ClockSyncStatus	The on-reader NTP program failed to synchronize with a time provider, implying that the timestamps on reader are unreliable. (Implies an NTP server is running on the network (internal if no Internet connection))
8	CLOCK_SYNC	ClockSyncStatus	An agent report was received from the reader which showed that the reader's clock is significantly off from the server's clock. The report was dropped by ItemSense in order to prevent issues that occur with determining an endpoint's latest location when readers' clocks differ.
9	READER_COMMAND	HardwareStatus	Generated when any LLRP reader command does not return a successful status reply
10	READER_EXCEPTION	HardwareStatus	Asynchronous notification from the reader (reported via LLRP) of an uncategorized error condition
11	READER_RESTART	HardwareStatus	Reader closed LLRP connection unexpectedly and the agent could not re-open it
12	UPGRADE_STATUS	HardwareStatus	When the upgrade (agent or firmware) process encounters any kind of error, or times out
13	CHECKSUM	SoftwareStatus	Checksum failure of either CAP or firmware image
14	COMMAND_NOT_FOUND	SoftwareStatus	Agent is sent an unknown command by ItemSense
15	CONFIG_SERVICE_SET	SoftwareStatus	Surfaced when an error is encountered in the agent config (In practice, this is a software error, or the config file is corrupted)
16	EXTERNAL_COMMAND	SoftwareStatus	A program invoked in the octane firmware by the agent returned an error code, or a response that could not be processed
17	FILE_SYSTEM	SoftwareStatus	Any file system error within the agent process (usually due to full or corrupted file system)
18	INVALID_SET_VARIABLE	SoftwareStatus	Agent is sent an invalid variable set command by ItemSense (type, range etc)
19	UNMARSHAL	SoftwareStatus	ItemSense sent invalid or corrupted data
20	LLRP	SoftwareStatus	1. Invalid RF configurations are specified by ItemSense 2. Invalid LLRP packet was sent to the agent by the reader
21	PROVISIONING	SoftwareStatus	1. Invalid provisioning settings 2. Provisioning module failed to start (http server failed to start)
22	READER_CONNECTION	SoftwareStatus	Failed to open or close the LLRP connection, or to receive a message over LLRP
23	CRASH	SoftwareStatus	The agent crashed and the reader is about to reboot
24	AGENT_OUTDATED	SoftwareStatus	An agent report was received from the reader which did not report the reader's time. ItemSense accepted the report, but this is potentially risky because ItemSense will not know if the reader's clock is or becomes out of sync. Upgrading the reader's Agent software is highly recommended.
25	REBOOT	None	Communicates the previous reboot reason. (Note: This event does not contribute to bad health status)
26	HEALTH_RESET	None	Is a signal used when computing reader status, to indicate ItemSense should disregard all health events older than this one
27	KNOWN	None	Any other exception that is expected by the Agent but not by ItemSense, including unknown SNMP events from the reader
28	UNKNOWN	None	Anything not previously defined or expected.

Software

Reader software (firmware) can be queried and upgraded via these endpoints.

List Images

Show all versions of a specific image type

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/softwareVersions/list/{imageType}

Path Parameters

Parameter	Type	Description
imageType	One of: FIRMWARE_SPEEDWAY CAP_ITEMSENSE	The type of image

Response

An array of:

Parameter	Type	Description
versionInfo	VersionInfo	The version information associated with the image
description	String	A string describing the version
created	String	The time at which the image was created in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
updated	String	The time at which the image was updated in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
updateComment	String	A comment associated with the update
recordVersionNumber	Integer	An integer representing the update revision number

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/softwareVersions/list/FIRMWARE_SPEEDWAY", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/softwareVersions/list/FIRMWARE_SPEEDWAY);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
    {
        "versionInfo": {
            "versionIdentifier": {
                "version": "5.6.2.240",
                "imageType": "FIRMWARE_SPEEDWAY",
            },
            "imageName": "octane-5.6.2.240.upg",
            "checksum": "076dae4e1c37037a42e37d012014ad62",
        },
    "description": "Octane v5.6.2.240",
    "created": "2016-09-06T18:21:08.000Z",
    "updated": "2016-09-06T18:21:08.000Z",
    "updateComment": null,
    "recordVersionNumber": 1
    },
    ...
]

Show Image

Show a specific software image by type and version

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/softwareVersions/show/{imageType}/{version}

Path Parameters

Parameter	Type	Description
imageType	One of: FIRMWARE_SPEEDWAY CAP_ITEMSENSE	The type of image
version	String	The version of the software image

Response

Parameter	Type	Description
versionInfo	VersionInfo	The version information associated with the image
description	String	A string describing the version
created	String	The time at which the image was created in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
updated	String	The time at which the image was updated in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
updateComment	String	A comment associated with the update
recordVersionNumber	Integer	An integer representing the update revision number

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/softwareVersions/show/FIRMWARE_SPEEDWAY/MY_VERSION", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/softwareVersions/show/FIRMWARE_SPEEDWAY/MY_VERSION);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "versionInfo": {
        "versionIdentifier": {
            "version": "5.6.2.240",
            "imageType": "FIRMWARE_SPEEDWAY",
        },
        "imageName": "octane-5.6.2.240.upg",
        "checksum": "076dae4e1c37037a42e37d012014ad62",
    },
    "description": "Octane v5.6.2.240",
    "created": "2016-09-06T18:21:08.000Z",
    "updated": "2016-09-06T18:21:08.000Z",
    "updateComment": null,
    "recordVersionNumber": 1
}

VersionInfo

Parameter	Type	Description
versionIdentifier	VersionIdentifier	The version of the software image
imageName	String	The name of the software image
checksum	String	The checksum of the image

VersionIdentifier

Parameter	Type	Description
version	String	The version of the software image
imageType	One of: FIRMWARE_SPEEDWAY CAP_ITEMSENSE	The type of image

Show Upgrades

List all of the software upgrade jobs

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/control/v1/upgrades/show

Response

An array of:

Parameter	Type	Description
id	String	Identifier of the request
upgradeRequest	UpgradeRequest	Details of the upgrade request
created	String	When the upgrade was created in ISO-8601 format such as '2017-05-02T15:35:56.456Z'
updated	String	When the upgrade was last updated in ISO-8601 format such as '2017-05-02T15:35:56.456Z'
numDevices	Integer	The number of devices being upgraded
isCancelled	boolean	Whether or not the request to upgrade has been cancelled
numFailures	Integer	The number of devices that have failed to upgrade

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/control/v1/upgrades/show", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/show);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
    {
        "id": "",
        "upgradeRequest": {
            "target": {
                "type": "Facility",
                "values": "[MY_FACILITY]",
            },
            "versionIdentifier": {
                "version": "5.6.2.240",
                "imageType": "FIRMWARE_SPEEDWAY",
            },
        "created": "2017-05-02T15:35:56.456Z",
        "updated": "2017-05-02T16:01:45.345Z",
        "numDevices": 10,
        "isCancelled": false,
        "numFailures": 0
    },
    ...
]

Show Upgrade

Show the status of a specific upgrade job

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/control/v1/upgrades/show/{upgradeInstanceId}

Path Parameters

Parameter	Type	Description
upgradeInstanceId	String	The ID of the upgrade instance to retrieve

Response

Parameter	Type	Description
id	String	The identifier of the upgrade
version	VersionIdentifier	The software version to which to upgrade the readers
status	One of: WAITING IN_PROGRESS COMPLETED FAILED SKIPPED	The status of the upgrade
target	UpgradeRequestTarget	The criteria for specifying the set of readers to upgrade
details	UpgradeStatusDetails	The upgrade status details
elapsedTimeSeconds	Integer	The elapsed time of the upgrade
lastUpdatedTime	String	The time that the reader was last updated

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/control/v1/upgrades/show/7df1a27b-64d2-485c-9140-215c1e5b55cc", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/show/7df1a27b-64d2-485c-9140-215c1e5b55cc);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "id": "",
    "version": {
        "version": "5.6.2.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    },
    "status": "IN_PROGRESS",
    "target": {
        "type": "Facility",
        "values": ["MY_FACILITY"],
    },
    "details": {
        "readers": [
        {
            "name": "SpeedwayR-11-79-9D",
            "previousVersion": {
                "version": "5.6.2.240",
                "imageType": "FIRMWARE_SPEEDWAY"
            },
            "status": "WAITING",
            "elapsedTimeSeconds": 0,
            "lastUpdatedTime": "2016-09-06T22:27:31Z"
        },
        {
            "name": "xArray-11-3F-5F",
            "previousVersion": {
                "version": "0.0.0.0",
                "imageType": "FIRMWARE_SPEEDWAY"
            },
            "status": "IN_PROGRESS",
            "elapsedTimeSeconds": 0,
            "lastUpdatedTime": "2016-09-06T22:27:37.428Z"
      },
      {
            "name": "SpeedwayR-11-1E-13",
            "previousVersion": {
                "version": "0.0.0.0",
                "imageType": "FIRMWARE_SPEEDWAY"
            },
            "status": "WAITING",
            "elapsedTimeSeconds": 0,
            "lastUpdatedTime": "2016-09-06T22:27:31Z"
      }
    ]
  },
  "elapsedTimeSeconds": 5,
  "lastUpdatedTime": "2016-09-06T22:27:36.185Z"
}

A Note About Software Versions

In the Sample Response above, note each reader's previousVersion property. SpeedwayR-11-79-9D shows a previous version of 5.6.2.240 (coincidentally, this is equal to the version being upgraded to in the example), while xArray-11-3F-5F and SpeedwayR-11-1E-13 show a previous version of 0.0.0.0.

This is because the version of the software running on the latter two readers had not been previously registered with ItemSense (see Software Versions). The readers had properly reported in to ItemSense with their versions of the software, but during the process of initializing the software upgrade request, the readers' software versions were not recognized. For the purposes of this upgrade request, they were replaced by the fallback version 0.0.0.0.

This has no negative impact on the upgrade process.

Start Upgrade

Start a software upgrade

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/control/v1/upgrades/start

Request Body

Property	Type	Description
target (required)	UpgradeRequestTarget	The criteria for specifying the set of readers to upgrade
versionIdentifier (required)	VersionIdentifier	The software version to which to upgrade the readers
policy (optional)	UpgradePolicy	The upgrade policy to employ

Response

Parameter	Type	Description
upgradeInstanceId	String	Instance identifier of the upgrade

Sample Code

var body = {
    "target": {
        "type": "Facility",
        "values": ["FAC"],
    },
    "versionIdentifier": {
        "version": "5.6.2.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    }
};
var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/control/v1/upgrades/start", true)
// Set authorization headers
xhr.send(body)

var body = {
    "target": {
        "type": "Facility",
        "values": ["FAC"],
    },
    "versionIdentifier": {
        "version": "5.6.2.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    }
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/start);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
using (StreamWriter sw = new StreamWriter(request.GetRequestStream())
{
    string data = new JavaScriptSerializer().Serialize(body);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "upgradeInstanceId": "7df1a27b-64d2-485c-9140-215c1e5b55cc",
}

Cancel Upgrade

Cancel a specific upgrade job

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/control/v1/upgrades/stop/{upgradeInstanceId}

Path Parameters

Parameter	Type	Description
upgradeInstanceId	String	The ID of the upgrade instance to cancel

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/control/v1/upgrades/stop/7df1a27b-64d2-485c-9140-215c1e5b55cc", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/stop/7df1a27b-64d2-485c-9140-215c1e5b55cc);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Data Definitions

UpgradeRequest

Property	Type	Description
target (required)	UpgradeRequestTarget	The criteria for specifying the set of readers to upgrade
versionIdentifier (required)	VersionIdentifier	The software version to which to upgrade the readers
policy (optional)	UpgradePolicy	The upgrade policy to employ

VersionIdentifier

Property	Type	Description
version (required)	String	The version of the software image
imageType (required)	One of: FIRMWARE_SPEEDWAY CAP_ITEMSENSE	The type of image

UpgradeRequestTarget

Property	Type	Description
type (required)	One of: DEVICE FACILITY	The criteria for selecting the set of readers to upgrade
values (required)	Array of: String	The values of the criteria for selecting the set of readers to upgrade (i.e. if type = FACILITY, then a list of facility names, and if type = DEVICE, then a list of reader names)

UpgradeStatusDetails

Property	Type	Description
readers (required)	Array of: UpgradeDeviceStatus	The upgrade status for each reader

UpgradePolicy

Property	Type	Description
maxParallelReaders (optional)	integer	The maximum number of readers upgrading at any given moment. As readers finish, ItemSense will stay at maxParallelReaders by starting the upgrade process on the next in line. Default: 10
allowedReaderTypes (optional)	Array of: String	The types of readers that are allowed to be upgraded. Default: [SPEEDWAY, XARRAY, XSPAN, XPORTAL]

UpgradeDeviceStatus

Parameter	Type	Description
name	String	The name of the reader
previousVersion	VersionIdentifier	The previous version of the reader software
status	One of: WAITING IN_PROGRESS COMPLETED FAILED	The status of the upgrade
elapsedTimeSeconds	Integer	The elapsed time of the upgrade in seconds
lastUpdatedTime	String	The time that the reader software was last updated

Settings - SNMP

Configure SNMP authorization and trap destination settings

Update

Update the existing SNMP settings

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/settings/SNMP

Request Body

Property	Type	Description
authConfig (required)	Auth Config	The authentication configuration
trapTargetConfig (optional)	Trap Config	The trap configuration

Response

Parameter	Type	Description
authConfig	Auth Config	The authentication configuration currently in use
trapTargetConfig	Trap Config	The trap configuration currently in use

Sample Code

var snmpSettings =  {
                       authConfig: {
                            type: "V2_COMMUNITY",
                            communityName: "foo"
                         },
                        trapTargetConfig: {
                            host: "127.0.0.1",
                            port:162,
                            timeout: "PT05",
                            retries: 2,
                            messageType: "TRAP"
                        }
                      };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/settings/SNMP", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(snmpSettings));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/settings/SNMP");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    authConfig = new
                    {
                        type = "V2_COMMUNITY",
                        communityName = "foo"
                    },
                    trapTargetConfig = new
                    {
                        host = "127.0.0.1",
                        port = 162,
                        timeout = "PT05",
                        retries = 2,
                        messageType = "TRAP"
                    }
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "authConfig": {
        "type": "V2_COMMUNITY",
        "communityName": "foo"
     },
    "trapTargetConfig": {
        "host": "127.0.0.1",
        "port":162,
        "timeout": "PT05",
        "retries": 2,
        "messageType": "TRAP"
    }
}

Delete

Removes existing SNMP settings. This will stop the SNMP service within ItemSense.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/settings/SNMP

Request Body

None

Response

None

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/settings/SNMP", true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send();

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/settings/SNMP");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve current SNMP settings

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/settings/SNMP

Parameters

None

Response

The properties of the response are the same as that supplied in the Update SNMP response Body.

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/settings/SNMP", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/settings/SNMP");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "authConfig": {
        "type": "V2_COMMUNITY",
        "communityName": "foo"
     },
    "trapTargetConfig": {
        "host": "127.0.0.1",
        "port":162,
        "timeout": "PT05",
        "retries": 2,
        "messageType": "TRAP"
    }
}

SNMP Settings Data Definitions

Auth Configuration

For SNMP v2

Property	Type	Description
type (required)	String	Fixed to V2_COMMUNITY
communityName (optional)	String	Community name to authenticate with

For SNMP v3

Property	Type	Description
type (required)	String	Fixed to V3_USER_PRIV. In this mode, authPriv with SHA + AES encryption is supported
engineId (optional)	String	ID that uniquely identifies the agent in the device
userName (optional)	String	User name to authenticate with
authenticationKey (optional)	String	Authentication key to authenticate with (minimum 8 characters)
privacyKey (optional)	String	Privacy key to authentication with (minimum 8 characters)

Trap Configuration

Property	Type	Description
host (optional)	String	IP Address of the host to send traps to
port (optional)	String	Port of the host to send traps to
timeout (optional)	String	How long to wait before a trap is present if not acknowledged (formatted as ISO-8601 duration)
retries (optional)	String	Number of retries to attempt (total tries will be retries + 1)
messageType (optional)	String	The type of message to send. One of: TRAP, INFORM

Support

Factory Reset

Reset ItemSense to the default configuration. All item data and configuration data will be removed and put back to the starting state.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/support/v1/configuration/factoryReset

Response

None

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/support/v1/configuration/factoryReset", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/configuration/factoryReset);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

Item Reset

Remove all ItemSense item data. All item, item history and transition data will be removed from the system.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/support/v1/items/reset

Response

None

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/support/v1/items/reset", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/items/reset);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

Reader Reboot

Reboots a particular reader.

If the reader was participating in a job, it will reboot and then rejoin the job. If the reader was busy performing some other task, e.g., a firmware upgrade, that task may be interrupted, which is likely to have unpredictable and undesired consequences.

ItemSense does not expose a mechanism for tracking the progress of the reader's reboot. Determining whether a reader has completed its reboot should be done manually by observing the reader's status LEDs, or by attempting to reach the reader over the network.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/support/v1/readers/{readerName}/reboot

Path Parameters

Parameter	Type	Description
readerName	string	Identifier of the reader to be rebooted

Response

None

Sample Code

var readerName = "myReader"
var xhr = new XMLHttpRequest()
xhr.open("POST", `http://BASE_URL/support/v1/readers/${readerName}/reboot`, true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
String readerName = "myReader";
Uri uri = new Uri(String.Format(http://BASE_URL/support/v1/readers/{0}/reboot, readerName));
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

Export Logs

Download an export of the ItemSense internal logs for use by Impinj customer support. By default the file downloaded will include 7 days worth of logs starting from now going backwards.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/logs

Query Parameters

Parameter	Type	Description
from	String	Filter for logs after the given time in ISO-8601 format such as "2017-03-02T15:35:01.560Z"
to	String	Filter for logs before the given time in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
extended	boolean	Include extended logged data. This will include logs not filtered by the 'from' and 'to' parameters

Response

A compressed tar.gz file

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/support/v1/logs?from=2014-01-07T22%3A46%3A00%2B01%3A00", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/logs?fromTime=2014-01-07T22%3A46%3A00%2B01%3A00);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

Export Configuration

Download an export of the ItemSense internal configuration for use by Impinj customer support.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/configuration

Response

A compressed tar.gz file

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/support/v1/configuration", true)
// Set authorization headers
xhr.send()

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/configuration);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

HTTP Return Codes

ItemSense API returns the following HTTP codes:

Code	Meaning
200	Request was successful
202	Request was successful. Use the "Location" header to obtain status on the request.
204	Request was successful but there is no response body. Returned in response to delete requests.
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable -- the requested format was not JSON
500	Internal Server Error -- there was a problem with the server. Please try again later.
503	Service Unavailable -- server offline for maintenance. Please try again later.