Introduction

This is the API reference guide for Impinj ItemSense. It describes all publicly-visible API endpoints and the data structures used for parameters and return values.

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 Impinj 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 event publishing interface.

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

The Support endpoints are used to aid troubleshooting. They include:

Configuration
Log Requests
Factory Reset
ItemSense Time Sync
Item Reset
Iteration Data
Reader Reboot

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.

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 all item data endpoints

The roles of a user are configured when the user is created or updated. 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

Note that Get a Token for the Current User and Validate Token have been deprecated as of ItemSense release 2.3 and could be removed in a future release.

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, a user with administrative privileges must generate a token for you.

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

Deletes 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

Used to delete 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

POST http://BASE_URL/authentication/v1/validateToken

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

Impinj ItemSense is capable of managing multiple physical locations. Each physical location is called a "Facility," which is is independently able to run jobs, build zone maps, specify different reader definitions, and query items. 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.

If ItemSense is only using one facility, no additional configuration is necessary, and the facility name will not be required for other API endpoints. For 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

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

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 triangular (requiring three points), rectangular (requiring four points), or more more complex polygonal shapes (requiring the same number of points as the number of sides in the polygon). 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 Request Body

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 Request Body

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)

Note that groups are created implicitly as a property of the reader definition. For example, if 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.

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

Replace

This API is equivalent to createOrReplace in functionality.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/readerDefinitions/replace/{Name}

Request Body

The same as the Create Request Body

Response

The same as the Create Response

Query Parameter

Parameter	Type	Description
name	string	Name of reader definition to update. Must match name in request body.

Sample Code

var currentName = "";
var params =  {
   name: "",
   agentIdentifier: "",
   address: "",
   groups: [],
   type: "",
   placement: {
      x: 4.1,
      y: 3.65,
      z: 1.68,
      yaw: 30,
      pitch: 0,
      roll: 90,
      floor: 1
   },
   facility: "",
};

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http:///itemsense/configuration/v1/readerDefinitions/replace/" + currentName, true)
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Basic " + btoa(":"));
xhr.send(JSON.stringify(params));

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

Uri uri = new Uri("http:///itemsense/configuration/v1/readerDefinitions/replace/" + currentName);

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()))
{
    var data = new
    {
        name =  "",
        agentIdentifier = "",
        address = "",
        //groups = [],
        type = "",
        placement = new {
            x = 4.1,
            y = 3.65,
            z = 1.68,
            yaw = 30,
            pitch = 0,
            roll = 90,
            floor = 1
        },
        facility = ""
    };

    json = JsonConvert.SerializeObject(data);
    sw.Write(json);
}

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

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 Response 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 Response 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 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:

Reader Configuration

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 #reader-configuration-create-request-body"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
filters (optional)	Filter Configuration	Array of tag filter definitions. Must always be used in conjunction with `filterOperation`. Note that `filter` and `filters` are mutually exclusive. Using both at the same time will cause an error. Also, more than two filter arrays at a time are not supported.
filterOperation (optional)	Boolean	Flag that indicates how the filters are combined, as an AND or an OR operation. This property is necessary if the `filters` property is used.
method * (optional)	One of: CUSTOM LEGACY FAST_CYCLE METHOD_1_18_3 METHOD_1_21_3 METHOD_2 METHOD_3	Apply a set of built-in algorithmControl parameters based on the selected method When set to CUSTOM then algorithmControl must be supplied. For all other values algorithmControl must not be supplied Only available when the reader operation=LOCATION
algorithmControl * (optional)	Array of Integers	Set additional location algorithm configuration parameters May only be supplied when method=CUSTOM Only available when the reader operation=LOCATION
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, the 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. If not specified, or array is empty, all antennas will be used. 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.
receiveSensitivityInDbm (optional)	Integer	Used to filter out tag reads that fall below the specified value. Allows the user to reduce sensitivity by limiting range while maintaining power. Values from -70 to -30 are accepted. Defaults to -80 if no value is specified. Only available when the reader operation=INVENTORY.
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"
powerSweep (optional)	RF Power Sweep Configuration	When present this parameter will enable the Impinj-specific RF Power Sweep operation Available when the reader operation is INVENTORY or THRESHOLD.

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 Index	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.

RF Power Sweep Configuration

Property	Type	Description
minimumPowerLevel (required)	Number	The minimum power level that the RF Power Sweep will start at before incrementing. It must be specified in 0.25 dB increments and be less than the value of `transmitPowerInDbm`.
powerLevelStepSize (required)	Number	The step size that the power will increment by when applying RF Power Sweep. It must be specified in 0.25 dB increments.

Events

In addition to its REST query APIs, ItemSense includes a real-time event push system that allows you to configure a message queue that notifies you when a particular event occurs. This system includes a broker, which is an event messaging server, and a publisher, which is a managed connection to an event broker. To create a message queue, you define your event broker, then configure event publishers that will send messages to that broker. Event publishers can be reconfigured even after the job begins running. Note that it can take up to 30 seconds for ItemSense to see the changes.

The preferred mechanism for event messaging is through an external, user-provided AMQP or MQTT message broker (recommended for high-volume tag deployments.), or sending events to a user-specified URL using Webhook invocations. It is also possible to retrieve events from AMQP and MQTT queues that are provided through an ItemSense built-in message broker.

We do not recommend retrieving events through the Items API, which is intended for use during configuration and testing, nor writing to the database after your system enters production; if a large volume of tags is being read, the use of this API will likely result in performance issues.

ItemSense allows you to limit the messages posted to a queue by configuring filters at queue setup. You can filter by three event types:

Item
Health
Threshold

If multiple queues are configured, messages will be sent to all queues with a matching filter, and only those messages in which all the properties match those within the request will be published.

Create Broker

Create a new event broker.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/events/brokers/

Request Body

Property	Type	Description
id (supplied by ItemSense)	long	Id of the broker. Supplied by ItemSense at creation.
name (required)	string	name of the broker.
type (required)	string	One of AMQP, MQTT, or WEBHOOK.
host (optional)	string	IP address of broker.
port (optional)	integer	Port of the host.
username (optional)	string	Name of the user.
password (optional)	string	Password for the user.
internal (optional)	boolean	Determines if broker is internal. Defaults to false. Creating an internal broker is not allowed.
secureConnection (optional)	boolean	Determines if connection is secure. Defaults to false.
serverCertificate (optional)	string	Self-signed certificate, uploaded if SSL is used.

Sample Code

  var brokerConfiguration {
    "name": "Broker_Name",
    "type": MQTT,
    "host": "external_host.company.com",
    "port": 1883,
    "username": "admin",
    "password": "passgoeshere",
    "internal": false,
    "secureConnection": false,
  };

  var xhr = new XMLHttpRequest();
  xhr.open("POST", "http://BASE_URL/configuration/v1/events/brokers", true);
  xhr.setRequestHeader("Content-Type", "application/json");
  xhr.setRequestHeader("Authorization", "Basic" + btoa("admin:passgoeshere"));
  xhr.send(JSON.stringify(brokerConfiguration));

// Encode credentials
string encodedCredentials = ...

// Data for new broker
var brokerConfiguration = new
{
    name = "Broker_Name",
    type = "MQTT",
    host = "external_host.company.com",
    port = 1883,
    username = "admin",
    password = "passgoeshere",
    secureConnection = false
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/brokers");
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(brokerConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 5,
  "name": "Broker_Name",
  "type": "MQTT",
  "host": "external_host.company.com",
  "port": 1883,
  "username": "admin",
  "password": "passgoeshere",
  "internal": false,
  "secureConnection": false,
  "serverCertificate": null
}

Replace Broker

Replace an event broker.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/events/brokers{brokerId}

Request Body

Parameter	Type	Description
id	long	Id of the broker.

Property	Type	Description
name (required)	string	name of the broker.
type (required)	string	One of AMQP, MQTT, or WEBHOOK.
host (optional)	string	IP address of broker.
port (optional)	integer	Port of the host.
username (optional)	string	Name of the user.
password (optional)	string	Password for the user.
internal (optional)	boolean	Determines if broker is internal. Defaults to false. Creating an internal broker is not allowed.
secureConnection (optional)	boolean	Determines if connection is secure. Defaults to false.
serverCertificate (optional)	string	Self-signed certificate, uploaded if SSL is used.

Sample Code

  var updatedBrokerConfiguration = {
    "id": 5
    "name": "New_Broker_Name",
    "type": "AMQP",
    "host": "external_host.company.com",
    "port": 5762,
    "username": "admin",
    "password": "passgoeshere",
    "internal": false,
    "secureConnection": false,
  };
  var xhr = new XMLHttpRequest();
  xhr.open("PUT", "http://BASE_URL/configuration/v1/events/brokers{brokerId}", true)
  xhr.setRequestHeader("Content-Type", "application/json");
  xhr.setRequestHeader("Authorization", "Basic" + btoa("admin:passgoeshere"));
  xhr.send(JSON.stringify(updatedBrokerConfiguration));

// Encode credentials
string encodedCredentials = ...

// Updated data for existing broker
var updatedBrokerConfiguration = new
{
    id = 5,
    name = "New_Broker_Name",
    type = "AMQP",
    host = "external_host.company.com",
    port = 5762,
    username = "admin",
    password = "passgoeshere",
    secureConnection = false
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/brokers/" + updatedBrokerConfiguration.id);
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(updatedBrokerConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 5,
  "name": "New_Broker_Name",
  "type": "AMQP",
  "host": "external_host.company.com",
  "port": 5762,
  "username": "admin",
  "password": "passgoeshere",
  "internal": false,
  "secureConnection": false,
  "serverCertificate": null
}

Delete Broker

Delete the specified event broker.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/events/brokers/{brokerId}

Request Body

Property	Type	Description
id	long	Id of broker to be deleted. If successful, returns Response Code 204.

Sample Code

  var brokerIdToDelete = 5;
  var xhr = new XMLHttpRequest();
  xhr.open("DELETE", "http://BASE_URL/configuration/v1/brokers/{brokerIdToDelete}");
  xhr.setRequestHeader("Authorization", "Basic" + btoa("admin:passgoeshere"));
  xhr.send();

// Encode credentials
string encodedCredentials = ...

// Must be an existing broker
var brokerIdToDelete = 5;

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/brokers/" + brokerIdToDelete);
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 Broker

Get an event broker.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/events/brokers/{brokerId}

Request Body

Parameter	Type	Description
id	long	id of the broker. Supplied by ItemSense at creation.

Sample Code

var brokerIdToList = 5;
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/events/brokers/{brokerIdToList}" );
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

// Must be an existing broker
var brokerIdToList = 5;

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/brokers/" + brokerIdToList);
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 Broker Sample Response.

Get All Brokers

Retrieve all of the event brokers.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1//configuration/v1/events/brokers

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/events/brokers/");
xhr.setRequestHeader("Authorization", "Basic" + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/brokers");
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": "ItemSense internal AMQP",
    "type": "AMQP",
    "host": "localhost",
    "port": 5672,
    "username": "-",
    "password": "-",
    "internal": true,
    "secureConnection": false,
    "serverCertificate": null
  },
  {
    "id": 2,
    "name": "ItemSense internal MQTT",
    "type": "MQTT",
    "host": "localhost",
    "port": 1883,
    "username": "-",
    "password": "-",
    "internal": true,
    "secureConnection": false,
    "serverCertificate": null
  },
  {
    "id": 3,
    "name": "REPLACE_BROKER",
    "type": "MQTT",
    "host": "localhost",
    "port": 2,
    "username": "string",
    "password": "string",
    "internal": false,
    "secureConnection": true,
    "serverCertificate": "string"
  },
  {
    "id": 4,
    "name": "ExternalMQTTOnDev6",
    "type": "MQTT",
    "host": "isdev6.i4j.io",
    "port": 1883,
    "username": "admin",
    "password": "admindefault",
    "internal": false,
    "secureConnection": false,
    "serverCertificate": null
  },
  {
    "id": 5,
    "name": "ExternalSecureAMQPonDev6",
    "type": "AMQP",
    "host": "isdev6.i4j.io",
    "port": 5671,
    "username": "admin",
    "password": "admindefault",
    "internal": false,
    "secureConnection": true,
    "serverCertificate": "-----BEGIN CERTIFICATE-----\nMIIFsDCCA.....-----END CERTIFICATE-----"
  },
  {
    "id": 6,
    "name": "ExternalSecureAMQPonSQA53",
    "type": "AMQP",
    "host": "FVXENISQA53.i4j.io",
    "port": 5671,
    "username": "admin",
    "password": "admindefault",
    "internal": false,
    "secureConnection": true,
    "serverCertificate": "-----BEGIN CERTIFICATE-----\nMIIFsDCCA.....-----END CERTIFICATE-----"
  }
]

Test Broker

Test that the specified event broker is enabled by sending a message to it.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/events/brokers/{brokerId}/test

Request Body

Property	Type	Description
id	long	Id of broker to be tested. If successful, returns Response Code 204.

Sample Code

var brokerIdToTest = 5; 
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/events/brokers/{brokerIdToTest}/test");
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

// Must be an existing broker
var brokerIdToTest = 5;

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/brokers/" + brokerIdToTest + "/test");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";

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

Sample Response

204 No Content

Create Publisher

Create a new event publisher.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/events/publishers

Request Body

Property	Type	Description
id	long	Provided by ItemSense on creation of publisher.
brokerId (required)	long	Id of the broker to which the publisher connects.
name (required)	string	The name that identifies the publisher.
messageTypes (required)	array of strings	One or more of:HEALTH, ITEM, and THRESHOLD
messageOptions (required)	string	See AMQP, MQTT, or WEBHOOK.

Sample Code

var publisherConfiguration = {
  "brokerId" = 2,
  "name": "MY_PUBLISHER",
  "messageTypes": [ "HEALTH" ],
  "messageOptions": {
      "mqtt": {
        "topicPrefix": "yourPrefix",
        "topicSuffix": "yourSuffix",
        "qos": 0
      },
    },
  "filters": {
      "health": {
      "readerName": "yourSelectedReader",
      "type": "THROUGHPUT",
      },
    }
  };
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "http://BASE_URL/configuration/v1/events/publishers", true);
  xhr.setRequestHeader("Content-Type", "application/json");
  xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
  xhr.send(JSON.stringify(publisherConfiguration));

// Encode credentials
string encodedCredentials = ...

// Data for new publisher
var publisherConfiguration = new
{
    brokerId = 2,
    name = "MY_PUBLISHER",
    messageTypes = ["HEALTH"],
    messageOptions = new
    {
        mqtt = new
        {
            topicPrefix = "yourPrefix",
            topicSuffix = "yourSuffix",
            qos = 0
        }
    },
    filters = new
    {
        health = new
        {
          readerName = "yourSelectedReader",
          type = "THROUGHPUT"
        }
    }
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/publishers");
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(publisherConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 5,
  "brokerId": 2,
  "name": "MY_PUBLISHER",
  "messageTypes": [
    "HEALTH"
  ],
  "messageOptions": {
    "amqp": {
      "routingKey": null,
      "routingKeyPrefix": null,
      "routingKeySuffix": null,
      "deliveryMode": "PERSISTENT",
      "exchange": "amq.topic",
      "vhost": "/"
    },
    "mqtt": {
      "topic": null,
      "topicPrefix": "yourPrefix",
      "topicSuffix": "yourSuffix",
      "qos": 0
    },
    "webhook": {
      "messageTypePlacement": "PATH",
      "path": null,
      "pathPrefix": null,
      "pathSuffix": null,
      "authenticationType": null,
      "requestTimeout": 2500
    }
  },
  "filters": {
    "item": null,
    "health": {
      "readerName": "",
      "type": "THROUGHPUT",
      "code": null
    },
    "threshold": null
  }
}

Replace Publisher

Replace an event publisher.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/events/publishers{publisherId}

Request Body

Parameter	Type	Description
id	long	Id of the publisher.

Property	Type	Description
brokerId (required)	long	Id of the broker to which the publisher connects.
name (required)	string	The name that identifies the publisher.
messageTypes (required)	string	One of: HEALTH, ITEM, THRESHOLD
messageOptions (required)	string	See AMQP, MQTT, or WEBHOOK.

Sample Code

var updatedPublisherConfiguration = {
  "id": 4,
  "brokerId": 5,
  "name": "REPLACE_PUBLISHER",
  "messageTypes": ["HEALTH"],
  "messageOptions": {
    "mqtt": {
      "topicPrefix": "yourPrefix",
      "topicSuffix": "yourSuffix",
      "qos": 0
    }
  },
  "filters": {
    "health": {
    "readerName": "yourSelectedReader",
    "type": "THROUGHPUT",
    }
  }
};
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/events/publishers/{updatedPublisherConfiguration.id}", true)
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));

xhr.send(JSON.stringify(updatedPublisherConfiguration));

// Encode credentials
string encodedCredentials = ...

// Updated data for existing publisher
var updatedPublisherConfiguration = new
{
    id = 4,
    brokerId = 5,
    name = "REPLACE_PUBLISHER",
    messageTypes = ["HEALTH"],
    messageOptions = new
    {
        mqtt = new
        {
            topicPrefix = "yourPrefix",
            topicSuffix = "yourSuffix",
            qos = 0
        }
    },
    filters = new
    {
        health = new
        {
          readerName = "yourSelectedReader",
          type = "THROUGHPUT"
        }
    }
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/publishers/" + updatedPublisherConfiguration.id);
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(updatedPublisherConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 4,
  "brokerId": 5,
  "name": "REPLACE_PUBLISHER",
  "messageTypes": [
    "HEALTH"
  ],
  "messageOptions": {
    "amqp": {
      "routingKey": null,
      "routingKeyPrefix": null,
      "routingKeySuffix": null,
      "deliveryMode": "NON_PERSISTENT",
      "exchange": "amq.topic",
      "vhost": "/"
    },
    "mqtt": {
      "topic": "string",
      "topicPrefix": "yourPrefix",
      "topicSuffix": "yourSuffix",
      "qos": 0
    },
    "webhook": {
      "messageTypePlacement": "PATH",
      "path": null,
      "pathPrefix": null,
      "pathSuffix": null,
      "authenticationType": null,
      "requestTimeout": 2500
    }
  },
  "filters": {
    "item": null,
    "health": {
      "readerName": "string",
      "type": "CONNECTION",
      "code": "string"
    },
    "threshold": null
  }
}

Delete Publisher

Delete the specified event publisher.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/events/publishers/{publisherId}

Request Body

Property	Type	Description
id	long	Id of publisher to be deleted. If successful, returns Response Code 204.

Sample Code

var publisherIdToDelete = 5;
var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/events/publishers" + publisherIdToDelete);
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

// Must be an existing publisher
var publisherIdToDelete = 5;

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/publishers/" + publisherIdToDelete);
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 Publisher

Get an event publisher.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/events/publishers/{publisherId}

Request Body

Property	Type	Description
publisherId (required)	long	Id of the publisher.

Sample Code

var publisherIdToList = 5;
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/events/publishers{publisherIdToList}");
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

// Must be an existing publisher
var publisherIdToList = 5;

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/publishers/" + publisherIdToList);
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 Request Body.

Get All Publishers

Retrieve all of the event publishers.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/events/Publishers

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/events/publishers");
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/publishers");
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,
    "brokerId": 3,
    "name": "ExternalSecureAMQPEverything",
    "messageTypes": [
      "HEALTH",
      "THRESHOLD",
      "ITEM"
    ],
    "messageOptions": {
      "amqp": {
        "routingKey": null,
        "routingKeyPrefix": "external",
        "routingKeySuffix": "everything",
        "deliveryMode": "NON_PERSISTENT",
        "exchange": "amq.topic",
        "vhost": "/"
      },
      "mqtt": {
        "topic": null,
        "topicPrefix": null,
        "topicSuffix": null,
        "qos": 0
      },
      "webhook": {
        "messageTypePlacement": "PATH",
        "path": null,
        "pathPrefix": null,
        "pathSuffix": null,
        "authenticationType": null,
        "requestTimeout": 2500
      }
    },
    "filters": null
  },
  {
    "id": 2,
    "brokerId": 4,
    "name": "ExternalMQTTEverything",
    "messageTypes": [
      "HEALTH",
      "THRESHOLD",
      "ITEM"
    ],
    "messageOptions": {
      "amqp": {
        "routingKey": null,
        "routingKeyPrefix": null,
        "routingKeySuffix": null,
        "deliveryMode": "NON_PERSISTENT",
        "exchange": "amq.topic",
        "vhost": "/"
      },
      "mqtt": {
        "topic": null,
        "topicPrefix": "external",
        "topicSuffix": "everything",
        "qos": 0
      },
      "webhook": {
        "messageTypePlacement": "PATH",
        "path": null,
        "pathPrefix": null,
        "pathSuffix": null,
        "authenticationType": null,
        "requestTimeout": 2500
      }
    },
    "filters": null
  },
  {
    "id": 3,
    "brokerId": 5,
    "name": "MY_PUBLISHER",
    "messageTypes": [
      "HEALTH"
    ],
    "messageOptions": {
      "amqp": {
        "routingKey": null,
        "routingKeyPrefix": null,
        "routingKeySuffix": null,
        "deliveryMode": "NON_PERSISTENT",
        "exchange": "amq.topic",
        "vhost": "/"
      },
      "mqtt": {
        "topic": "string",
        "topicPrefix": "string",
        "topicSuffix": "string",
        "qos": 0
      },
      "webhook": {
        "messageTypePlacement": "PATH",
        "path": null,
        "pathPrefix": null,
        "pathSuffix": null,
        "authenticationType": null,
        "requestTimeout": 2500
      }
    },
    "filters": {
      "item": null,
      "health": {
        "readerName": "string",
        "type": "CONNECTION",
        "code": "string"
      },
      "threshold": null
    }
  }
]

Test Publisher

Test that the specified event publisher is enabled by sending a message to it.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/events/publishers/{publisherId}/test

Request Body

Property	Type	Description
id	long	Id of publisher to be tested. If successful, returns Response Code 204.

Sample Code

var publisherIdToTest = 3;
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/events/publishers/{publisherIdToTest}/test", true);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Basic " + btoa("admin:passgoeshere"));
xhr.send();

// Encode credentials
string encodedCredentials = ...

// Must be an existing publisher
var publisherIdToTest = 3;

Uri uri = new Uri("http://BASE_URL/configuration/v1/events/publishers/" + publisherIdToTest + "/test");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";

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

Sample Response

204 No Content

Message Options

AMQP

Property	Type	Description
routingKey (optional)	string	Routing key of the publisher. Every message that ItemSense sends to AMQP will have a routing key, which will consist of the type of message being sent. If used, routingKey overrides both routingKeyPrefix and routingKeySuffix.
routingKeyPrefix (optional)	string	If specified, value will be attached to front of message type.
routingKeyPrefix (optional)	string	If specified, value will be attached to back of message type.
deliveryMode (required)	string	Determines if the delivery mode is persistent or non-persistent. Defaults to non-persistent.
exchange (optional)	integer	Type of exchange used by publisher. Defaults to topic. "impinj" as a prefix is not allowed.
vhost (optional)	string	Virtual host for the publisher.

MQTT

Property	Type	Description
topic (optional)	string	Every message that ItemSense sends to AMQP will have a topic,which tells what type of message is sent. If used, topic overrides both topicPrefix and topicSuffix.
topicPrefix (optional)	string	If specified, value will be attached to front of message type.
topicSuffix (optional)	string	If specified, value will be attached to back of message type.
qos (required)	string	Defines guarantee of delivery for specific message (At most once: 0; At least once: 1; Exactly once: 2). Defaults to 0.

Webhook

Property	Type	Description
messageTypePlacement (optional)	string	One of PATH or QUERY_PARAM. If QUERY_PARAM is selected, the parameter, messageType, will be appended to the HTTP POST Request URL. Ex: "http://HOST_NAME/MY_PATH/messageType=HEALTH".
path (optional)	string	Path specified in call.
pathPrefix (optional)	string	If specified, value will be attached to front of path.
pathSuffix (optional)	string	If specified, value will be attached to back of path.
authenticationType (optional)	string	One of BASIC or DIGEST. BASIC communicates credentials using unemcrypted base64 encoding. DIGEST encrypts by applying a hash function.
requestTimeout (optional)	long	Converted to milliseconds. Must be 100 or more. Default is 2500.

Item

Property	Type	Description
minimumMovement (optional)	Float	The minimum distance in meters a tag must move before a queue event (or message) is created.
jobNamePrefixes (optional)	String	If specified, value(s) attached to the front of the job name(s).
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
epcPrefix (optional)	String	A hexadecimal string representing an EPC prefix of an item. Only items with EPCs that start with this prefix will be returned.
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."
zoneTransitionsOnly (optional)	Boolean	Will restrict results to items that have moved from one zone to another. Defaults to true.

Health

Parameter	Type	Description
readerName (optional)	String	The name of the reader to query.
type (optional)	One of: CONNECTION THROUGHPUT CLOCK_SYNC HARDWARE_FAULT SOFTWARE_FAULT LIFECYCLE UNCLASSIFIED	The type of health event to query.
code (optional)	String	The status code to query. See Code Details

Health Types

ConnectionStatus

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

ThroughputStatus

Property	Type	Description
status (optional)	One of: HEALTHY WARNING FAILED	The status of reader throughput
code (optional)	One of: DROPPED_READ REPORT_BUFFER TAG_POPULATION_OVERFLOW	See Code Details

ClockSyncStatus

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

HardwareStatus

Property	Type	Description
status (optional)	One of: HEALTHY WARNING FAILED	The hardware status
code (optional)	One of: READER_COMMAND READER_EXCEPTION READER_RESTART UPGRADE_STATUS	See Code Details

SoftwareStatus

Property	Type	Description
status (optional)	One of: HEALTHY WARNING FAILED	The status of reader throughput
code (optional)	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

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	RECOVERY	ConnectionStatus	Reader rebooted and returned online after a 30-35 second interval of NO_RESPONSE
5	DROPPED_READ	ThroughoutStatus	Agent data buffer overflow error
6	REPORT_BUFFER	ThroughputStatus	Internal agent buffer is full or nearly full (conditions are distinguished by a message on the health event)
7	TAG_POPULATION_OVERFLOW	ThroughputStatus	Too many tags (in direction or location mode)
8	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))
9	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.
10	READER_COMMAND	HardwareStatus	Generated when any LLRP reader command does not return a successful status reply
11	READER_EXCEPTION	HardwareStatus	Asynchronous notification from the reader (reported via LLRP) of an uncategorized error condition
12	READER_RESTART	HardwareStatus	Reader closed LLRP connection unexpectedly and the agent could not re-open it
13	UPGRADE_STATUS	HardwareStatus	When the upgrade (agent or firmware) process encounters any kind of error, or times out
14	CHECKSUM	SoftwareStatus	Checksum failure of either CAP or firmware image
15	COMMAND_NOT_FOUND	SoftwareStatus	Agent is sent an unknown command by ItemSense
16	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)
17	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
18	FILE_SYSTEM	SoftwareStatus	Any file system error within the agent process (usually due to full or corrupted file system)
19	INVALID_SET_VARIABLE	SoftwareStatus	Agent is sent an invalid variable set command by ItemSense (type, range etc)
20	UNMARSHAL	SoftwareStatus	ItemSense sent invalid or corrupted data
21	LLRP	SoftwareStatus	1. Invalid RF configurations are specified by ItemSense 2. Invalid LLRP packet was sent to the agent by the reader
22	PROVISIONING	SoftwareStatus	1. Invalid provisioning settings 2. Provisioning module failed to start (http server failed to start)
23	READER_CONNECTION	SoftwareStatus	Failed to open or close the LLRP connection, or to receive a message over LLRP
24	CRASH	SoftwareStatus	The agent crashed and the reader is about to reboot
25	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.
26	REBOOT	None	Communicates the previous reboot reason. (Note: This event does not contribute to bad health status)
27	HEALTH_RESET	None	Is a signal used when computing reader status, to indicate ItemSense should disregard all health events older than this one
28	KNOWN	None	Any other exception that is expected by the Agent but not by ItemSense, including unknown SNMP events from the reader
29	UNKNOWN	None	Anything not previously defined or expected.

Threshold

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

Example Event Messages

Sample Item Event

{
  "epc": "E7E92B38AB2C362497818237",
  "tagId": "",
  "jobId": "8b2edc53-83a1-4e06-8ebf-5fb6ddbbcfa2",
  "jobName": "jobName",
  "from": {
    "zone": "ABSENT",
    "floor": null,
    "facility": null,
    "x": null,
    "y": null
},
  "to": {
    "zone": "FACILITY",
    "floor": "1",
    "facility": "DEFAULT",
    "x": 0.0,
    "y": 0.0
  },
  "observationTime": "2019-03-29T20:16:46Z"
}

Sample Health Event

{
  "eventTime": "2019-03-29T20:08:10.153211Z",
  "type": "TYPE",
  "code": "CODE",
  "readerName": "xarray-11-00-00.impinj.com",
  "args": {
    "reason": "REASON"
  }
}

Sample Threshold Event

{
  "epc": "E7E92B38AB2C362497818237",
  "fromZone": "OUT",
  "toZone": "IN",
  "threshold": "MyFavoriteThreshold",
  "thresholdId": 1,
  "confidence": 1.0,
  "jobId": "3e73759c-e419-42b8-9688-4a0e1b6cf457",
  "jobName": "threshold_job",
  "observationTime": "2019-03-29T05:31:48.427Z"
}

Data Definitions

The following tables provide the semantic meaning of values returned in the fields of event messages:

ItemEvent

Property	Type	Description
epc	String	The EPC of the tag for which the event occurred
tagId	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 currently set to empty ("")
jobId	String	The ID of the job that reported the change in the item
jobName	String	The name of the job that reported the change in the item
from	JSON Object	The set of location values from which the tag moved, of type Location Details
to	JSON Object	The set of location values to which the tag moved, of type Location Details
observationTime	String	The time at which the event occurred in ISO-8601 format such as "2017-05-02T15:35:01.560Z"

HealthEvent

Parameter	Type	Description
eventTime	String	The time at which the event occurred in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
readerName	String	The name of the reader that experienced the event
type	One of: CONNECTION THROUGHPUT CLOCK_SYNC HARDWARE_FAULT SOFTWARE_FAULT LIFECYCLE UNCLASSIFIED	The type of health event
code	String	The status code of the event. See Code Details

LocationReport

Property	Type	Description
zone	String	The zone name for the reported location
floor	String	The floor name for the reported location
facility	String	The facility name for the reported location
x	Float	The x coordinate of the reported location
y	Float	The y coordinate of the reported location

ThresholdTransitionEvent

Property	Type	Description
epc	String	The EPC of the tag for which the event occurred
observationTime	Integer	The time at which the transition was recorded in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
fromZone	String	The type of transition, being "IN" or "OUT" this will always be the opposite value of toZone
toZone	String	The type of transition, being "IN" or "OUT" this will always be the opposite value of fromZone
threshold	String	The name of the threshold where this transition occurred
thresholdId	Integer	The ID of the threshold where this transition occurred
jobId	String	The ID of the job that generated the transition record
jobName	String	The name of the job that generated the transition record
confidence	Float	The confidence value of the transition event, ranging from 0.0 to 1.0

Threshold

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

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 specifying 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

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.

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	Controls how frequently the lastModifiedTime of a tag is updated when the tag is read but has not moved. Set with a string-based ISO 8601 duration format, PnDTnHnMn.nS, representing the time interval between heartbeat updates. Example = "PT10M", Minimum = "PT1S"
tagExpiryDuration (optional)	String	A string in ISO 8601 duration format, PnDTnHnMn.nS, 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 duration format.) representing the time interval between heartbeat updates. Example = "PT10M", Minimum = "PT1S"
tagExpiryDuration (optional)	String	A string in ISO 8601 duration 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(){
    {"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 use all the readers in the specified facility that have been selected 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 in which the job will be run
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 duration 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. Must not be specified when a threshold recipe is used
reportToDatabaseEnabled (optional)	Boolean	(deprecated) Flag for determining if the job should relay tag reads into the Items database. Note that if this value is false, then data is not available via the Items API. Defaults to true
reportToHistoryEnabled (optional)	Boolean	(deprecated) Flag for determining if the job should relay tag reads into the Item History database. Note that if this value is 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	(deprecated) Flag for determining if the job should consider data from previous or other active jobs when calculating item zone changes. Defaults to true

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	String	The duration for which the job has been active, in ISO 8601 duration format such as "P23DT12H30M5.044S"
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
facility	String	The name of the facility in which the job was run
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,
    "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}

Parameter

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

Query Parameter

Parameter	Type	Description
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 Start a Job response.

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 responses

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. Specifying both this property and the jobIds property will result in an error.
jobIds (optional)	String	A comma-separated list of job identifiers, such as "ffa29f71-f0f9-426e-9ba4-45398361dc5d, a6ce7f09-deb0-40f5-9ed7-0cf923440850". This parameter identifies items that were reported by any of the given jobs. Specifying both this property and the jobId property will result in an error.
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. Will return the raw hex strings (e.g. E280-1160-6000-0205-077D-321F) if this property is not specified. All options except DEFAULT and RAW require that the tags have SGTIN-96 encoding. If not correctly encoded, they return no data. The DEFAULT option also requires valid SGTIN-96 encoding to decode the EPC and, if successful, returns data in PURE_ID format, but on failure, will revert to RAW format, which returns all tags, regardless of encoding. Note that ItemSense allows EPCs of various lengths up to 256 bits, but will only decode 96-bit EPCs that follow the SGTIN-96 standard.
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"}) will simply handling query properties.
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";

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 has a significant state change. Examples of a significant state change include zone change, tag movement beyond the minimum threshold, and elapsed heartbeat interval.

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. Specifying both this property and the jobIds property will result in an error."
jobIds (optional)	String	A comma-separated list of job identifiers, such as "ffa29f71-f0f9-426e-9ba4-45398361dc5d, a6ce7f09-deb0-40f5-9ed7-0cf923440850". This parameter identifies items that were reported by any of the given jobs. Specifying both this property and the jobId property will result in an error.
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. Will return the raw hex strings (e.g. E280-1160-6000-0205-077D-321F) if this property is not specified. All options except DEFAULT and RAW require that the tags have SGTIN-96 encoding. If not correctly encoded, they return no data. The DEFAULT option also requires valid SGTIN-96 encoding to decode the EPC and, if successful, returns data in PURE_ID format, but on failure, will revert to RAW format, which returns all tags, regardless of encoding. Note that ItemSense allows EPCs of various lengths up to 256 bits, but will only decode 96-bit EPCs that follow the SGTIN-96 standard.
zoneTransitionsOnly (optional)	Boolean	Will restrict results to items that moved zones, defaults to true
minDistanceMoved (optional)	Float	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. Defaults to true.

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"}) simplifies handling query parameters.
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",
         "jobName": "locationJob",
         "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",
         "jobName": "locationJob",
         "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 thresholds. When threshold jobs are running and configured to report to the database, a record of each item transition is stored.

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. Specifying both this property and the jobIds property will result in an error.
jobIds (optional)	String	A comma-separated list of job identifiers, such as "ffa29f71-f0f9-426e-9ba4-45398361dc5d, a6ce7f09-deb0-40f5-9ed7-0cf923440850". This parameter identifies items that were reported by any of the given jobs. Specifying both this property and the jobId property will result in an error.
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. Will return the raw hex strings (e.g. E280-1160-6000-0205-077D-321F) if this property is not specified. All options except DEFAULT and RAW require that the tags have SGTIN-96 encoding. If not correctly encoded, they return no data. The DEFAULT option also requires valid SGTIN-96 encoding to decode the EPC and, if successful, returns data in PURE_ID format, but on failure, will revert to RAW format, which returns all tags, regardless of encoding. Note that ItemSense allows EPCs of various lengths up to 256 bits, but will only decode 96-bit EPCs that follow the SGTIN-96 standard.
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. Defaults to true.

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)	Float	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: "", 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 = "(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", "fromFacility": "Store51", "fromFloor": "MainFloor", "fromX": -1.57, "fromY": 12.22, "fromZone":"BACK_OF_STORE", "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", "jobName": "AfternoonLocation", "observationTime":"2018-03-30T22:48:18.886Z", "tagId": "", "toFacility": "Store51", "toFloor": "MainFloor", "toX": 2.21, "toY": 8.71, "toZone":"FRONT_OF_STORE"}
Message: {"epc":"02CBA4FF091338C2A35ADB86", "fromFacility": "Store51", "fromFloor": "MainFloor", "fromX": -2.17, "fromY": 13.41, "fromZone":"BACK_OF_STORE", "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", "jobName": "AfternoonLocation", "observationTime":"2018-03-30T22:48:18.888Z","tagId": "", "toFacility": "Store51", "toFloor": "MainFloor", "toX": 4.98, "toY": 6.29, "toZone":"FRONT_OF_STORE"}
Message: {"epc":"C38B2994C7BA3AD68961A233", "fromFacility": "Store51", "fromFloor": "MainFloor", "fromX": -2.17, "fromY": 13.41, "fromZone":"BACK_OF_STORE", "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", "jobName": "AfternoonLocation", "observationTime":"2018-03-30T22:48:18.89Z","tagId": "", "toFacility": "Store51", "toFloor": "MainFloor", "toX": 3.15, "toY": 3.05, "toZone":"FRONT_OF_STORE"}
Message: {"epc":"E7E92B38AB2C362497818237", "fromFacility": "Store51", "fromFloor": "MainFloor", "fromX": 0.41, "fromY": 12.92, "fromZone":"BACK_OF_STORE", "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", "jobName": "AfternoonLocation", "observationTime":"2018-03-30T22:48:18.893Z","tagId": "", "toFacility": "Store51", "toFloor": "MainFloor", "toX": 7.48, "toY": 4.31, "toZone":"FRONT_OF_STORE"}
Message: {"epc":"02D9D40D17A63E9595EB6890", "fromFacility": "Store51", "fromFloor": "MainFloor", "fromX": 1.27, "fromY": 13.45, "fromZone":"BACK_OF_STORE", "jobId":"de9cfdf2-ac9e-4d14-a5cc-b00430140902", "jobName": "AfternoonLocation", "observationTime":"2018-03-30T22:48:18.895Z","tagId": "", "toFacility": "Store51", "toFloor": "MainFloor", "toX": 4.19, "toY": 6.54, "toZone":"FRONT_OF_STORE"}

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. 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/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
jobName (optional)	String	The name 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
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

Property	Type	Description
readerNames (optional)	Array of: String	The set of reader names for which to query health events
types (optional)	Array of: String	The set of status types for which to query health events
codes (optional)	Array of: String	The set of status codes for which to query health events (see Code Details below).
fromTime (optional)	String	The beginning of the query time period in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
toTime (optional)	String	The end of the query time period in ISO-8601 format such as "2017-05-02T15:35:01.560Z"
pageSize (optional)	Integer	The number of events to return per query
nextPageMarker (optional)	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

Query 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 (optional)	String	The name of the reader to query
type (optional)	One of: CONNECTION THROUGHPUT CLOCK_SYNC HARDWARE_FAULT SOFTWARE_FAULT LIFECYCLE UNCLASSIFIED	The type of health event to query
code (optional)	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

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

ThroughputStatus

Property	Type	Description
status (optional)	One of: HEALTHY WARNING FAILED	The status of reader throughput
code (optional)	One of: DROPPED_READ REPORT_BUFFER TAG_POPULATION_OVERFLOW	See Code Details

ClockSyncStatus

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

HardwareStatus

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

DeviceStatus

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

SoftwareStatus

Property	Type	Description
status (optional)	One of: HEALTHY WARNING FAILED	The status of reader throughput
code (optional)	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

Property	Type	Description
eventTime (optional)	String	The time of the event in ISO 8601 format such as "2017-05-02T15:35:01.560Z"
readerName (optional)	String	The name of the reader
type (optional)	One of: CONNECTION THROUGHPUT CLOCK_SYNC HARDWARE_FAULT SOFTWARE_FAULT LIFECYCLE UNCLASSIFIED	The type of event
code (optional)	String	See Code Details
args (optional)	Object	Additional event-specific properties, often including a helpful message about the cause of the event
readerFacility (optional)	String	The facility to which the reader has been assigned by the user.

Code Details

#	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	RECOVERY	ConnectionStatus	Reader rebooted and returned online after a 30-35 second interval of NO_RESPONSE
5	DROPPED_READ	ThroughoutStatus	Agent data buffer overflow error
6	REPORT_BUFFER	ThroughputStatus	Internal agent buffer is full or nearly full (conditions are distinguished by a message on the health event)
7	TAG_POPULATION_OVERFLOW	ThroughputStatus	Too many tags (in direction or location mode)
8	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))
9	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.
10	READER_COMMAND	HardwareStatus	Generated when any LLRP reader command does not return a successful status reply
11	READER_EXCEPTION	HardwareStatus	Asynchronous notification from the reader (reported via LLRP) of an uncategorized error condition
12	READER_RESTART	HardwareStatus	Reader closed LLRP connection unexpectedly and the agent could not re-open it
13	UPGRADE_STATUS	HardwareStatus	When the upgrade (agent or firmware) process encounters any kind of error, or times out
14	CHECKSUM	SoftwareStatus	Checksum failure of either CAP or firmware image
15	COMMAND_NOT_FOUND	SoftwareStatus	Agent is sent an unknown command by ItemSense
16	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)
17	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
18	FILE_SYSTEM	SoftwareStatus	Any file system error within the agent process (usually due to full or corrupted file system)
19	INVALID_SET_VARIABLE	SoftwareStatus	Agent is sent an invalid variable set command by ItemSense (type, range etc)
20	UNMARSHAL	SoftwareStatus	ItemSense sent invalid or corrupted data
21	LLRP	SoftwareStatus	1. Invalid RF configurations are specified by ItemSense 2. Invalid LLRP packet was sent to the agent by the reader
22	PROVISIONING	SoftwareStatus	1. Invalid provisioning settings 2. Provisioning module failed to start (http server failed to start)
23	READER_CONNECTION	SoftwareStatus	Failed to open or close the LLRP connection, or to receive a message over LLRP
24	CRASH	SoftwareStatus	The agent crashed and the reader is about to reboot
25	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.
26	REBOOT	None	Communicates the previous reboot reason. (Note: This event does not contribute to bad health status)
27	HEALTH_RESET	None	Is a signal used when computing reader status, to indicate ItemSense should disregard all health events older than this one
28	KNOWN	None	Any other exception that is expected by the Agent but not by ItemSense, including unknown SNMP events from the reader
29	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	System-generated Universally Unique Identifier (UUID) returned as a string
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": "9b76015b-43e8-4fe1-9af6-599a439883e8",
        "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	System-generated Univerally Unique Identifier (UUID) returned as a string
version	VersionIdentifier	The software version to which to upgrade the readers
status	One of: WAITING IN_PROGRESS COMPLETED FAILED	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": "9b76015b-43e8-4fe1-9af6-599a439883e8",
    "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. 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 SKIPPED	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

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();

Download Iteration Data Log

Retrieves iteration data.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/logs/iterationData/{jobId}

Request Body

Parameter	Type	Description
jobId	String	A UUID job identifier, such as "cbfa1f54-c3b0-40d4-9597-e4fec9b9e623" Identifies the job for which the iteration data log should be returned.

Response

Response | Description 200 | Iteration data log returned 404 | Iteration data log not present

Sample Code

var userName = "Admin"
   var xhr = new XMLHttpRequest();
   xhr.open("GET", "http://BASE_URL/support/v1/logs/iterationData/" + jobID);
   xhr.setRequestHeader("Authorization", "Basic " + btoa("Admin:admindefault"));
   //xhr.setRequestHeader("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
   xhr.send();

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

            Uri uri = new Uri("http://BASE_URL/support/v1/logs/iterationData/" + jobID);
            HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

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

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

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

Configure ItemSense Time Sync

Configures the setting for enabling itemsenseTimeSync.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/support/v1/readers/itemsenseTimeSync

Request Body

Parameter	Type	Description
enabled	boolean	Enables or disables itemsenseTimeSync settings. Defaults to enabled, true.

Response Body

204 Request was successful but there is no response body.

Sample Code

var params = {};
params.enabled = BOOLEAN;

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/itemsense/support/v1/readers/itemsenseTimeSync", true);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Basic " + btoa("USER:PASSWORD"));
xhr.send(JSON.stringify(params));

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

Uri uri = new Uri("http://BASE_URL/itemsense/support/v1/readers/itemsenseTimeSync");

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()))
{
  var data = new
  {
    enabled = false
  };

  json = JsonConvert.SerializeObject(data);
  sw.Write(json);
}

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

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

Sample Response

No content

Get ItemSense Time Sync

Retrieve setting that dictates if ItemSense configures readers and gateways to use ItemSense Server for time synchronization.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/readers/itemsenseTimeSync

Response

Parameter	Type	Description
enabled	boolean	Returns the setting that dictates if ItemSense is configuring readers and gateways to use ItemSense Server for time synchronization.

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/itemsense/support/v1/readers/itemsenseTimeSync");
xhr.setRequestHeader("Authorization", "Basic " + btoa("USER:PASSWORD"));
xhr.send();

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

Uri uri = new Uri("http:///itemsense/support/v1/readers/itemsenseTimeSync");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

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

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

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

Sample Response

{
  "enabled": true
}

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/itemsense/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 = "";
var url = "http:///itemsense/support/v1/readers/" + readerName + "/reboot";

var xhr = new XMLHttpRequest();
xhr.open("POST", url, true);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.setRequestHeader("Authorization", "Basic " + btoa(":"));
xhr.send();

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

Uri uri = new Uri("http:///itemsense/support/v1/readers/" + readerName + "/reboot");

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();
}

Export ItemSense 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; 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();

Create Reader Logs Request

Instruct ItemSense to gather logs from readers. Can designate specific readers or include all readers in the request. When complete, logs are downloaded via Get Reader Logs API.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/support/v1/readers/logs/requests

Request Body

Property	Type	Description
readerNames (optional)	Array of: String	Names of the readers from which to download logs; if empty, all readers are included in the request

Response Body

Parameter	Type	Description
requestId	String	The ID of the log export request
state	String	The state of the newly created log export request; this is always "RUNNING" for the initial request
message	String	Details of the newly created log export request
requestTime	String	The request creation time in ISO 8601 format, such as "2017-05-02T15:35:01.560Z"
completeTime	String	The request completion time in ISO 8601 format, such as "2017-05-02T15:35:01.560Z;" always null on creation
readerNames	Array of: String	The names of the readers from which logs are exported
readersStates	Key Value List	A list of readers' states, grouped by state; on creation, all readers or all readers specified as part of the request are listed under "RUNNING"
downloadUrl	String	The URL to which results of this request are downloaded when complete

Sample Code

var readers = {
                "readerNames": [
                  "READER_NAME_1",
                  "READER_NAME_2"
                ]
              };

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

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/support/v1/readers/logs/requests");

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
                {
                    "readerNames": [
                      "READER_NAME_1",
                      "READER_NAME_2"
                    ]
                });
    sw.Write(data);
}

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

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

Sample Response

{
  "requestId": "750b8a3e-08b2-4f34-8dcf-81c9041e00b3",
  "state": "RUNNING",
  "message": "",
  "requestTime": "2018-09-11T18:13:20.776Z",
  "completeTime": null,
  "readerNames": [
    "xArray-11-30-0D"
  ],
  "readersStates": {
    "RUNNING": [
      "xArray-11-30-0D"
    ],
    "ERROR": [],
    "DONE": []
  },
  "downloadUrl": "/support/v1/readers/logs/download"
}

Get Reader Logs Status

ItemSense gathers logs in an asynchronous manner. Poll this endpoint until the process is complete before attempting to download the gathered reader logs.

Authorized Roles

ConfigManager, Admin

HTTP Request

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

Response Body

Parameter	Type	Description
requestId	String	Identifier for log latest export request
state	String	State of the log export request. Valid values are: RUNNING, DONE, ERROR
message	String	Details about the log export request, usually blank
requestTime	String	The request creation time in ISO 8601 format, such as "2017-05-02T15:35:01.560Z"
completeTime	String	The request completion time in ISO 8601 format, such as "2017-05-02T15:35:01.560Z"
readerNames	Array of: String	The names of the readers
readersStates	Key Value List	A map of states to lists of reader names; key values are: RUNNING, DONE, ERROR
downloadUrl	String	The URL to download the results of this request when it completes

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", `http://BASE_URL/support/v1/readers/logs/requests`, true);
xhr.requestHeaders("Content-Type", "application/json");
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/support/v1/readers/logs/requests");

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();
}

Get Reader Logs

Download the last export of the reader logs for use by Impinj customer support. Reader log exports are kept for 4 days.

Authorized Roles

ConfigManager, Admin

HTTP Request

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

Response

A compressed tar.gz file

Sample Code

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

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/readers/logs/download);
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 ItemSense 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();
}

Get ItemSense Version

Get version information about ItemSense and its components.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/version

Response

Property	Type	Description
version	string	Current version of ItemSense instance.

Sample Code

var userName = "Admin"
   var xhr = new XMLHttpRequest();
   xhr.open("GET", "http://bg-ubuntu/itemsense/support/v1/version);
   xhr.setRequestHeader("Authorization", "Basic " + btoa("Admin:admindefault"));
   //xhr.setRequestHeader("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
   xhr.send();

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

            Uri uri = new Uri("http://bg-ubuntu/itemsense/support/v1/version);
            HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

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

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

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

Sample Response

{
  "imcClientBuild": "409",
  "imcClientCommitId": "d0aca75c956838d82769d3d2136ac7d4c4a46c9d",
  "imcClientVersion": "2.3.0",
  "imcServerBuild": "847",
  "imcServerCommitId": "dcf246b522a440a79ea2d674870da66613e8bf9e",
  "imcServerVersion": "2.3.0",
  "version": "2.3.0-eng+258",
  "isv2Version": "isreg/isv2:1.0.4"
}

In 2.3, Only the version property is guaranteed as a valid return. All other properties returned should be considered unreliable, and ignored.

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.