CenterScape API Specification

VERSION 1.1
CONTENTS
i
CenterScape API Specification i
Trademarks v
Copyright Statement vi
1.0 Introduction 1
1.1 General System Structure 1
1.2 HTTP-based API Interface 1
1.3 HTTP Authentication 2
1.4 Standard Output Formatting 3
1.5 Error Reporting 3
1.6 Macros 4
1.7 Actions 8
2.0 Data Model 9
2.1 Object Types 9
Entity Type 10
Entity 12
Attribute 13
Attribute Class 14
Entity Type Attribute 17
Custom Attribute Type 21
3.0 Data Schema 22
3.1 Attribute Classes 22
$aAssetDoorOpen 22
$aAssetTag 23
$aAssetHumidity 23
$aAssetImage 24
$aAssetLockClosed 24
$aAssetLockCount 25
$aAssetLockOpen 25
$aAssetLowBattery 26
$aAssetMotion 26
$aAssetMotionCount 27
$aAssetPanic 27
$aAssetSensorLowBattery 28
$aAssetTamper 28
$aAssetTemperature 29
$aAssetUserPayload 29
$aBoundAsset 30
$aCookieData 30
$aDescription 31
 $aDetectedLocation 31
$aEnabled 32
$aLocation 32
$aName 33
$aOnline 33
$aPassword 34
$aServiceDate 34
$aViewAttributes 35
Retired 35
Type 36
3.2 Entity Types 36
$tRoot 37
$tEntity 37
$tUserEntity 38
$tAsset 38
$tAssetAlert 39
$tUnassignedTag 39
3.3 Custom Attribute Types 39
$tLocation 40
$tUnknownLocation 40
4.0 Putting It Together: An Example 41
5.0 Command Reference 59
5.1 Attribute Class 59
5.2 Audit Log 63
5.3 Entity 65
5.4 Configuration Import 69
5.5 Configuration Export 71
5.6 Current User 76
5.7 Change Password 77
5.8 Database Configuration 79
5.9 Entity Type 81
5.10 Filter 86
5.11 Filter Delete 92
5.12 Filter Update 93
5.13 History 97
5.14 Report Output 101
5.15 Report 103
5.16 Tag 105
5.17 Tag Import 109
5.18 Schemas 112
5.19 Zone Manager Import 113
6.0 Command Examples 115
6.1 Exporting Assets By Filter - All Assets Attributes 115
6.2 Exporting Assets By Filter – Specific Asset Attributes 115
6.3 Importing New Assets 116
6.4 Updating Existing Assets 116
6.5 Querying a Specific Asset By GUID 117
6.6 Querying Assets By Location 117
6.7 Creating a Filter and Listening for Updates 118
6.8 Query All Unresolved Alerts 119
6.9 Create an Instant Report 119
6.10 Create a Report 120
7.0 Programming Tools 122
Trademarks

RF Code™ and the RF Code logo are trademarks of RF Code, Inc. Microsoft®, Windows, Windows
Server, SQL Server, and Internet Explorer are trademarks of the Microsoft Corporation in the United
States and other countries. PostgreSQL™ is a registered trademark of the PostgreSQL Global Devel-
opment Group. Intel Core Duo Processor ™ is a trademark of Intel Corporation in the US and/or other
countries. Firefox® is a registered trademark of the Mozilla Foundation. ChromeTM is a trademark of
Google, Inc. Safari® is a trademark of Apple Inc., registered in the US and other countries. IBM® and
WebSphere® are trademarks of IBM Corporation, registered in the US and/or other countries. Oracle™,
Java™, and Java Management Extensions™ are registered trademarks of Oracle and/or its affiliates.
BACnet® is a registered trademark of ASHRAE. Modbus™ is a trademark of the Modbus Organization,
Inc. Eclipse™ and BIRT™ are trademarks of the Eclipse Foundation, Inc. NetBotz™ is a Registered
Trademark of American Power Conversion Corporation. The Bluetooth® word mark and logos are
registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by RF Code is under
license. All other product names are copyright and registered trademarks or trade names of their respective
owners.
Bluetooth QD ID: B012541
Copyright Statement

CenterScape API Specification REV 00

Copyright © 2008-2016 RF Code, Inc. All Rights Reserved.
This document, the hardware, and the firmware described therein are furnished under license and may only
be used or copied in accordance with the terms of such license. The information in these pages is furnished
for informational use only, is subject to change without notice, and should not be construed as a com-
mitment by RF Code, Inc. RF Code assumes no responsibility or liability for any errors or inaccuracies that
may appear in these pages.
Information in this document is provided solely to enable system and software users to use RF Code
products. RF Code reserves the right to make changes without further notice to any products herein. RF
Code makes no warranty, representation, or guarantee regarding the suitability of its products for any par-
ticular purpose, nor does RF Code assume any liability arising out of the application or use of any product,
and specifically disclaims any and all liability, including without limitation consequential or incidental dam-
ages.
The user of this system is cautioned that any changes or modifications to this system, not expressly
approved by RF Code, Inc., could void the warranty. Every effort has been made to supply complete and
accurate information. However, RF Code assumes no responsibility for its use, or for any infringements of
patents or other rights of third parties, which would result.
RF Code, Inc.
9229 Waterford Centre Blvd.
Suite 500
Austin, TX 78758
[Link]
1.0 Introduction

This specification is intended to provide the details needed for third-party software and driver
developers to successfully produce code that integrates with RF Code CenterScape, version 1.1 or
later, produced by RF Code, Inc.
The interfaces provided are intended to expose all available features of the product in a supported and
consistent fashion, allowing applications to be developed that will require little or no changes in order
to support future versions of the CenterScape product. That said, RF Code does reserve the right to
change any or all of these interfaces in future product releases.
Any questions, comments, or suggestions concerning this specification can be sent to the RF Code
Developer Support e-mail address, sdk@[Link].

1.1 General System Structure

The RF Code CenterScape server consists of an application server, supported on 64-bit commercially
available Linux distributions and Microsoft Windows 7/8/10 and Windows Server systems (64-bit Intel
architecture). The interfaces provided by the product are consistent between all supported operating sys-
tems. The server interfaces with one or more RF Code Zone Manager servers which in turn interface
with the Zone Manager-supported RFID readers.
The CenterScape server provides a HTTP-based interface (implemented on port 6580 on the server)
which supports JSON (JavaScript Object Notation) output.

1.2 HTTP-based API Interface

The HTTP-based API interface for CenterScape is the supported interface for application imple-
mentation, as most program languages and environments support efficient issuing of HTTP-based
requests and parsing of the responses. In addition, most corporate networking systems support a variety
of mechanisms for managing HTTP-based traffic through firewalls, proxies, and other technologies.
Lastly, the HTTP-based APIs can easily be used by both other web server-based applications and web
browser-based applications (such as those implemented using JavaScript in HTML documents).
The CenterScape server follows a representational state transfer (REST) model for most of the APIs.
The following table maps the HTTP method to the supported API operation:

CenterScape API Specification 1

 HTTP Method API Operation

POST Create/Update

GET Read

PUT Update/Replace

DELETE Delete

The HTTP methods map one-to-one to the relational database CRUD operations.
The REST model is resource-centric where the resources being operated on are specified in the URL
to the right of the hostname. All CenterScape APIs are declared under a command URL path:
[Link]
For example, to request a specific CenterScape entity, you might construct the following HTTP
request:
GET [Link]
The GET HTTP command verb is used to retrieve information. The response that is returned is
encoded in either a Javascript Object Notation (JSON) or Comma Separated Value (CSV) formatted
response.

1.3 HTTP Authentication

CenterScape server access requires an authenticated user ID and password. The CenterScape server
will accept either Form-based or Basic authentication to authenticate a user.
The CenterScape Web UI uses Form-based authentication. The CenterScape server returns the HTTP
header requesting Basic authorization when an unauthenticated request is received for requests which
do not originate from the CenterScape Web UI. If you are using a command line tool such as curl, you
can use the “-u user:password” parameter to send a request using Basic authentication.
Since neither Form-based or Basic authentication is considered secure, the CenterScape server should
be configured to use HTTPS if there is a concern the user ID or password can be intercepted.

CenterScape API Specification 2

1.4 Standard Output Formatting

Command output is encoded consistently for the two output formatting types, although the content of
each command is specific to that command.
For JSON-encoded output, each command will return a valid JSON object or array. If an object is
returned (JSON objects are enclosed in curly brackets “{ }”), it will contain one or more comma-sep-
arated attribute-value pairs. If an array is returned (JSON arrays are enclosed in square brackets “[ ]”),
it will contain zero or more JSON objects. Any application processing the JSON-formatted output
must check if the returned entity is an object or array.
For CSV-encoded output, the first line will be a header line containing the object identifiers and attrib-
utes that are being returned in the response set. Following the header line, there is a line for each entity
that is returned in the response set.

1.5 Error Reporting

If an API returns a HTTP status code other than 200 (OK), a single JSON-encoded status object is
returned. An example of a status object indicating a required field is missing a value would be:
{
"success":false
,"errors":[
{
"code":"AttributeRequired"
,"message":"Required value is missing for Entity Root"
,"field":"$aName"
}
]
}
l The “success” attribute indicates the overall status of the request.
l “errors” is a JSON array containing the one or more JSON objects indicating the error condition
(s).

CenterScape API Specification 3

 l “message” is a human-readable error message indicating the error condition.
l “field” is the ID of the attribute which has an error condition.

1.6 Macros

Macros are variables specified during the configuration of some attributes and which are replaced with
actual values when the system sends or displays the attribute value. Macros can be used within:
l Email action messages
l Directory paths and filenames for various actions
l The titles of dashboard widgets

Macros are inserted by specifying the macro name within the text value of an attribute, prefaced with a
dollar sign and enclosed between curly brackets. An example of an email event action configured to
include the time that the event occurred would have the following value for the event action message:
Event Time: ${TIME}
Using this value, if an event occurs at 12:30:15 p.m. and the event is configured to execute the email
action, then the email message sent when the event is triggered would be:
Event Time: 12:30:15 pm
Since alerts and events are generated from a source entity, and since the attributes that an entity has
associated with it are definable by the system administrator, macros provide a way to specify that a spe-
cific attribute from an alert or event source should be inserted. This is done by using the macro name
“SOURCE.” followed by the ID of the attribute. The following example macro would insert an
entity’s description:
${SOURCE.$aDescription}

CenterScape API Specification 4

 Available Macros:

For Alerts For Events For Reports

TIMESTAMP TIMESTAMP TIMESTAMP

DATE DATE DATE

YEAR YEAR YEAR

MONTH MONTH MONTH

DAY DAY DAY

TIME TIME TIME

HOUR HOUR HOUR

MINUTE MINUTE MINUTE

SECOND SECOND SECOND

MILLISECOND MILLISECOND MILLISECOND

TIMEZONE_OFFSET TIMEZONE_OFFSET TIMEZONE_OFFSET

ID ID ID

SOURCE_ID SOURCE_ID NAME

RESOLVE_TIME TRIGGER_NAME TYPE

SEVERITY TRIGGER_TYPE JOB_ID

TRIGGER_ATTRIBUTE1_
DESCRIPTION JOB_NAME
ID

TRIGGER_ATTRIBUTE1_
START_TIME JOB_START_TIME
NAME

STATE TRIGGER_OPERATOR1 JOB_STOP_TIME

CenterScape API Specification 5

 Available Macros:

For Alerts For Events For Reports

THRESHOLD_NAME TRIGGER_VALUE1 FILTER_LOCATION

TRIGGER_ATTRIBUTE2_
THRESHOLD_TYPE FILTER_TYPE
ID

TRIGGER_ATTRIBUTE2_
URL TYPE_ID
NAME

THRESHOLD_
TRIGGER_OPERATOR2
ATTRIBUTE1_ID

THRESHOLD_
TRIGGER_VALUE2
ATTRIBUTE1_NAME

THRESHOLD_ TRIGGER_ATTRIBUTE3_
OPERATOR1 ID

TRIGGER_ATTRIBUTE3_
THRESHOLD_VALUE1
NAME

THRESHOLD_
TRIGGER_OPERATOR3
ATTRIBUTE2_ID

THRESHOLD_
TRIGGER_VALUE3
ATTRIBUTE2_NAME

THRESHOLD_
FILTER_LOCATION
OPERATOR2

THRESHOLD_VALUE2 FILTER_TYPE

THRESHOLD_
TRIGGER_TIME
ATTRIBUTE3_ID

THRESHOLD_
[Link]
ATTRIBUTE3_NAME

CenterScape API Specification 6

 Available Macros:

For Alerts For Events For Reports

THRESHOLD_ SOURCE_TRIGGER_
OPERATOR3 VALUE 1

SOURCE_TRIGGER_
THRESHOLD_VALUE3
VALUE2

SOURCE_TRIGGER_
FILTER_LOCATION
VALUE3

FILTER_TYPE TRIGGER_ID

[Link]

SOURCE_THRESHOLD_
ADAPTIVE_VALUE

SOURCE_THRESHOLD_
VALUE1

SOURCE_THRESHOLD_
VALUE2

SOURCE_THRESHOLD_
VALUE3

THRESHOLD_ADAPTIVE_
ATTRIBUTE_ID

THRESHOLD_ADAPTIVE_
ATTRIBUTE_NAME

THRESHOLD_ADAPTIVE_
ATTRIBUTE_OPERATOR

THRESHOLD_ADAPTIVE_
VALUE

THRESHOLD_ID

CenterScape API Specification 7

 NOTE: Unlike alerts and events, reports do not reference a source asset and as a result they
do not have any ${SOURCE.attribute_name} macros available.

1.7 Actions

Various Actions can be configured to execute in association with Alerts, Events, and Reports. These
actions are designed to push information about the associated alert, event, or report to outside systems.
Actions can be configured to send information using various protocols, including:
l For alerts, events and reports:
o email

o ftp
o sftp (SSH File Transfer)
o http
o https

l For alerts and events (but not reports)

o Logging

o SNMP v1 Traps
o SNMP v3 Traps
o SNMP v3 Informs
o Commands to devices connected to a serial port

Serial device actions send the commands specified in the action. Email actions send the message spe-
cified in the action after doing proper text replacement of any macros specified in the message. The out-
put of all other actions includes:
l The replaced values for all macros available to the action (see table in Macros above), with the
exception of the following macros, which only output a partial date or time: DATE, YEAR,
MONTH, DAY, TIME, HOUR, MINUTE, SECOND, MILLISECOND,
TIMEZONE_OFFSET.
l Additional source attributes specified in the definition of the source alert or event (not applicable
to reports).
l Other values for backwards compatibility of alert actions. All alert action name/value pairs from
previous versions of HTTP and FTP alert actions are included and supported. Since some names
do not match the macro name for the same value, the value is duplicated.

CenterScape API Specification 8

2.0 Data Model

The data model describes the major elements necessary to understand the functionality of RF Code’s
CenterScape.

2.1 Object Types

The CenterScape data model centers around the definition of and interaction with a family of core
object types. Each of these object types plays a role in supporting and defining the behavior and fea-
tures of the CenterScape system, and many of the object types interact with one another to bring this
about. Most of the object types require instances to have a globally unique object ID (“GUID”) – an
alphanumeric, case-sensitive identifier string that must be unique and cannot be changed during an
object’s life cycle.
The four primary object types in the CenterScape data model are Entity Types, Attribute Classes,
Attributes, and Entities. An Entity Type can be roughly described as what an object is; for example, an
Entity Type could be a vehicle, or more specifically a car. An Attribute Class is used to describe the
characteristics or properties of an Entity Type. An Entity is an object whose type is a reference to an
existing Entity Type. As Entity is to an Entity, so too is Attribute to Attribute Class. An instance of an
Attribute is a name/value pair where the name refers to a defined Attribute Class and the value is the
value of the attribute constrained to the Attribute Class type and any other constraints that may be spe-
cified in the declaration of the Attribute Class.
As you read this document, the terms Entity Type and Asset Type, Entity and Asset are used inter-
changeably. Entity Types and Entities are internal terms used to describe data model objects. Asset
Types and Assets are customer terms used to describe the same data model objects.
Each of the object types will be discussed in more detail and images of the CenterScapeWeb UI will
be used to demonstrate how these data model objects are created and updated using the CenterScape
Web UI.
You will need Administrative privileges if you wish to modify the CenterScape data model (Entity
Types and Attribute Classes) via the Web UI. Navigate to the CenterScape Admin Console and select
the “Data Schema” Tab.

CenterScape API Specification 9

Entity Type
Entity Types are objects representing the different types of Entity objects defined within CenterScape.
Entity Types are used to define the population of attributes that may be present on Entities (instances of
a type). Each Entity Type must have a unique object ID.
Entity Types can be arranged in a hierarchy, by allowing one Entity Type to be specified as the “par-
ent” of other Entity Types. Entity Type attributes also inherit from parent to child, so setting the “city”
attribute of a parent Entity Type will cause that attribute to be “shown” on all of its children (and any
descendants), unless those Entity Types provide their own value for the “city” attribute. A child Entity
Type may override any of its parent Entity Type Attribute objects. A child may not, however, remove
an Entity Type Attribute its parent defines.
In most cases, an Entity Type defines the attributes which make up an Entity unless the Attribute Class
object has the “inherit_attributes” value set to false. Setting “inherit_attributes” can be useful for attrib-
utes of type “typeref-list”.

CenterScape API Specification 10

 Entity Type Properties

Describes the class of object. For entity types the value is “entity_
class
type”.

The globally unique ID for this entity type. For entity types that are
guid created using the CenterScape Web UI, a suggested entity type GUID
is automatically generated but can be overridden.

parent The GUID of the parent entity type.

name Presentation label.

description Describes this entity type in detail.

Describes whether or not a user can delete this entity type. Entity
deletable Type objects defined by the CenterScape server and not a user are
marked as non-deletable.

An array of objects that contain the attribute classes which are used
attributes
when creating instances of an entity type.

To relate this back to the CenterScape Web UI, the CenterScape administrator would select the “Asset
Types” section under the “Data Schema” tab. Here, the administrator would be presented with the fol-
lowing interface:

CenterScape API Specification 11

On the left side of the “Asset Types” panel, a tree of the customer’s Asset Types is displayed.
When a type is selected, the panel to the right is used to display information about the selected type.
The “Name” field is the value of the type’s “name” attribute, the “Description” field is the value of the
type’s “description” attribute, the “ID” field is the value of the type’s guid, and the “Parent” field is the
value of the type’s “parent” field. The other areas of the panel define the Attribute Classes that are asso-
ciated directly with the type or indirectly through the type’s ancestor. This “Attributes” group is used to
display the values of the type’s “attributes” field. How Attribute Classes are associated with Entity
Types will be discussed in greater detail in a later section.
The “class” attribute and the “deletable” attribute are both hidden from the user. The “class” attribute is
used to indicate the type of data model object (Entity Type, Attribute Class, or Entity). Since we are
working with Entity Types, the class is always “entity_type”. The “deletable” attribute is used to con-
trol whether an Entity Type can be deleted by an Administrator. By default, all user-defined types can
be deleted and the value of this Entity Type property is set to true. Most system-defined types cannot
be deleted.
You can easily create your own Entity Types in the CenterScape Web UI by selecting an existing type
in the left panel and then selecting the “New Asset Type” button. The selected type will be the parent
type of the newly created Asset Type. In the following screenshot, an administrator has clicked New
Asset Type and is creating a new type whose name is “Car” and whose ID (guid) is “CAR”.

Entity
Entity objects provide the main interface for interacting with CenterScape. An Entity object represents
a single instance of an asset or tag with one or more associated properties or attributes. Each Entity
object has a single well-known attribute named “type” which represents the base type of the Entity.
The type of the Entity corresponds to an existing Entity Type object. The CenterScape user typically
creates entities (or assets if you prefer) under the “Asset” tab in the CenterScape User Console.

CenterScape API Specification 12

When creating a new asset, the user is prompted to select an asset type. You may already be familiar
with the window used to select the type of new asset to create:

The types listed in the drop-down list are the customer’s asset types that were previously created in the
“Asset Types” Administrative Console.
Every asset the customer creates must have a type, a unique name, and a unique object ID.
When Entities are created using the CenterScape Web UI, the user is not prompted to supply an object
ID; rather, the CenterScape server will generate a unique object ID at the time a new object request is
made. Users of the CenterScape API interface can opt for this same behavior if the value of the object
ID is not significant to a customer’s data model. If specifying the object ID is important, the Center-
Scape API user can specify the object ID when a request to create an new entity is made. Either way,
the object ID is required to be unique.
An asset has zero or more associated Attribute objects. Each Attribute corresponds to a single property
of the Entity. The available attributes of the entity are defined by the entity’s Entity Type objects.
A CenterScape user may choose to either retire or purge an asset. A retired asset no longer records his-
tory, but its existing history is still available to view. A purged asset and any associated historical val-
ues are completely removed from the CenterScape server as if it never existed.

Attribute
An Attribute represents a single property of an asset. Each Attribute has an associated value. The data
type of the Attribute’s value is described within the Attribute’s associated Attribute Class object. Each
attribute may store history depending on the “History Recorded” property of the Attribute Class.

CenterScape API Specification 13

Attribute Class
An Attribute Class represents the definition of an Attribute. In essence, an Attribute Class defines what
the value of an asset property is allowed to be. Just like every other object created in the CenterScape
data model, each Attribute Class must have a unique object ID. An Attribute Class has the following
properties:

Attribute Class Properties

Describes the class of object. For attribute classes the value is “attribute_
class
class”.

guid The globally unique ID for this attribute class.

name Presentation label.

description Describes this attribute class in detail .

Describes whether or not a user can delete this attribute class. Attribute
deletable Class objects defined by the CenterScape server and not a user are
marked as non-deletable.

If true, this attribute class is no longer accessible for editing. History can
retired
still be viewed. Updates to attributes of this class no longer occur.

If true, all changes to an attribute of this class are recorded in the history.
history
If false, only the current value is stored.

Used only by string, string-list and enum Attribute Classes. An array

values which contains the list of values allowed for this attribute class. For the
enum type, each value corresponds to a specific enumerated value.

If this attribute class’s type is type-ref, then entities will inherit the value of
inherit_attributes
the attributes defined on the entity type.

CenterScape API Specification 14

 Attribute Class Properties

One or more constraints on the value of attributes of this class. Double

and long data types can be constrained by a minimum or maximum value.
A string, password, or string-list can be constrained using a regular expres-
constraints
sion. A typeref, typeref-list, entityref and entityref-list values can be con-
strained by an Entity Type. For example, a user may constrain a location
attribute to only values within the “Texas” Entity Type hierarchy.

The type of encoding for a password attribute class. Blowfish and SHA-
encoding
512 are supported.

The data type for values of this attribute class. See the table below for the
type
list of data types.

One of the following strings:

l info – Set by CenterScape and not a user. Used for informational
values, such as the version of an application, which are visible to a
user.
l hidden – Set by CenterScape and not a user. These values are not
shown to a user. CenterScape uses “hidden” values to associated
metadata required to interact with an entity. For example, asso-
use ciating the tag type of a tag with a tag entity.
l config – CenterScape or a user may modify this attribute. All user
created attributes are set to “config”.
l status – Set by CenterScape and not a user. Used for status values
set by CenterScape which are visible to a user. For example, the
motion value of a tag is determined by the CenterScape and not a
user.

Used only by Zone Manager. The $zName is an alias which points to

Zone Manager’s name for this attribute. For example, in CenterScape the
$zName
attribute may have the GUID of “$aHost” while in Zone Manager the
attribute is called “host”. In this case, the $zName value is “host”.

CenterScape API Specification 15

The following table lists Attribute Class data types.

Attribute Class Data Types

boolean A true/false value.

date A single date, such as January 31, 2008.

8 bytes IEEE 754. Covers a range from 4.94065645841246544e-

double
324d to 1.79769313486231570e+308d.

A reference to an entity object. This is a simple association. The

entityref entity with this attribute does not inherit its entity referenced attrib-
utes.

A list of references to entity objects. This is a simple association. The

entityref-list entity with this attribute does not inherit its entity referenced attrib-
utes.

An enumeration. The value of an attribute of this type is one of the

enum
values listed in the attribute class’ “values” property.

8 bytes signed (two’s complement). Ranges from -

long
9,223,372,036,854,775,808 to +9,223,372,036,854,775,807.

A hash table of values. A map must contain a “__mapkeytype” and

“__mapvaluetype” entries which contain the data type of the hash
map
table key and value. Currently map values may only be defined by
the AssetServer and not a user.

Holds a password value. The encoding used is specified by the attrib-

password
ute class’s “encoding” property.

string A string.

string list A list of strings.

A single date/time accurate to seconds and expressed in GMT.

Note: The CenterScape web interface will adjust the value of a

timestamp
timestamp value by the browser’s time zone, and offset from GMT.
No adjustment is made to a timestamp value if the value is being
updated via an CenterScape API.

CenterScape API Specification 16

If we navigate back to the Admin Console in the CenterScape Web UI and select the “Data Schema”
tab, you will notice two sections called “Asset Attributes” and “System Attributes”. “Asset Attributes”
is used by the CenterScape administrator to create attributes that are part of the customer’s data
schema. An example would be to create a color attribute.

The Color attribute has a type of “String List” and a list of declared String Values or “Red”, “Green”,
“Blue”, “Black” and “White”. These are the valid values for the Color attribute. If we attempted to set
a Color attribute to “Yellow”, the server would reject the request indicating the attempt to set the attrib-
ute to an illegal value.
The “System Attributes” section is used to view and modify some of the CenterScape built-in Attribute
Classes. It is provided mainly for information purposes; however, the CenterScape administrator is
allowed to modify the presentation labels for the built-in Attribute Classes.

Entity Type Attribute

Now that we have an Entity Type declared and an Attribute Class declared, we want to bind or asso-
ciate an Attribute Class to an Entity Type. To do this, we use another CenterScape data model object
called an Entity Type Attribute. The Entity Type Attribute is just another object that describes how an
Entity Type should display an Attribute Class, if the Attribute Class should have a default value, the
order an Attribute Class should be presented relative to other Attribute Classes, and whether an Attrib-
ute Class’s value is required.
The following table list the properties of an Entity Type Attribute:

CenterScape API Specification 17

 Entity Type Attribute Properties

Describes the class of object. For entity type attributes, the value is
class
“entity_attribute”.

guid The globally unique ID of an existing attribute class.

If true, upon creation of an Entity a user must provide a value for this
required
attribute.

A static entity type attribute is an attribute which is an instance of the

Entity Type and not the Entity. In this case, the Entity Type stores the
current value and the history of the attribute. For example, a location
Entity Type defines a static attribute named “city” with the value
“Austin”. All Entities which have a typeref attribute whose value is
isStatic “location” then will also have an attribute named “city” with the value
“Austin”.
A non-static entity type attribute makes an attribute available for the
Entity to define. For example, a “Server” Entity Type may have the
attribute “RAM”. In this case different servers have different amounts
of RAM therefore the “RAM” attribute should be non-static.

Describes whether or not a user can delete this attribute class. Attribute
deletable Class objects defined by the CenterScape server and not a user are
marked as non-deletable.

For static attributes this defines the value of the attribute. For non-static
attributes this defines a default value. When a user creates an Entity the
value
non-static attribute is populated with the default value which the user
may change.

Defines the sort order for attributes on the Entity user interface (UI).
sortPriority
Attributes with a lower sort priority are displayed first.

Attributes with the same category are shown on the Entity UI grouped
together within a titled box. Category has a lower precedence than sort
priority as a result attributes with the same category may appear in two
different titled boxes. For example, suppose an entity type contains
category
attributes “city” with sort priority 100 and “state” with sort priority 300
both in the “location” category and a third attribute “host” with sort pri-
ority 200 and category “network”. In this example, the UI will have
three titled boxes, “location”, “network” and “location”.

CenterScape API Specification 18

If we select the “Car” asset type in the “Asset Types” panel, we see on the panel to the right, the Car
asset does add any Attribute Classes of its own. The “Car” asset type does have other attributes asso-
ciated with it as a result of inheriting these attributes from its ancestors. Now we want to start tracking
the color of our car assets. To do this, we would simply select the “Car” asset type on the left and then
select the “Add” button in the “Attributes” group box. At this point, you will be presented with the dia-
log:

At the top of the dialog is a list of the Attribute Classes which are available to add to the asset type.
The remaining fields match the properties in the table listed above. The “Category” and “Field Order”
are strictly used for presentation. Let’s add the “Color” attribute and specify its Category as “Appear-
ance” with a Field Order of “500”. Going back to the Web UI we see that “Color” is now an attribute
of “Car”:

CenterScape API Specification 19

We can also view how the Web UI will construct a dialog when updating or creating a “Car” asset
type by selecting the button “View Sample Input Form”. The dialog will appear as:

You will notice the numbers in parentheses down the side are the field order numbers specified for
each Entity Type Attribute. This information is displayed to the CenterScape administrator to show
why attributes appear before or after other attributes in a dialog.
We can add another attribute, “Asset Image,” to the “Car” asset type under the category of “Images”
and with a Field Order of “600”. If we view the sample input form again, we get the expected results:

CenterScape API Specification 20

Custom Attribute Type
When an asset is created in CenterScape, a single asset type is selected. That asset type defines the
properties associated with the asset. A custom attribute type allows the value of an attribute to con-
tribute other attributes to the asset.
For example, let’s say I have a laptop asset that is located in Austin, Texas and when the asset is in
Austin, Texas, you want its Building attribute set to “A-500”. If that same laptop is located in Palo
Alto, California, you want its “State Asset Code” set to “C.1.33”. The custom attribute type allows
you to change the attributes that are associated with an asset by choosing one custom type versus
another.

CenterScape API Specification 21

3.0 Data Schema

The CenterScape server defines attribute classes, entity types, and entities, which allows for the con-
figuration and monitoring of CenterScape itself and for the definition of asset types by the customer.

3.1 Attribute Classes

This section lists a subset of the built in attribute classes and a description of their use. The attributes lis-
ted are those the end user can apply to their own asset types or are automatically added to a customer’s
asset as a result of a tag being associated to an asset. By convention, all built-in attribute class guids
start with “$a” or “$z”.

$aAssetDoorOpen

$aAssetDoorOpen Properties

guid $aAssetDoorOpen

type bool

name Door

history true

use status

Reports if the door switch on the asset is reporting a door opened con-
description
dition reported by the asset’s tag.

CenterScape API Specification 22

$aAssetTag

$aAssetTag Properties

guid $aAssetTag

type entityref-list

name Asset Tag

history true

use config-view

“typeref” : “$tTag”
constraints Value of this attribute must be constrained to references to entities
whose type is “$tTag” or inherits from “$tTag”.

This attribute contains the reference to the tag with which an asset is
description associated. Even though this attribute is a list, CenterScape does not
support associating more than one tag to an asset.

$aAssetHumidity

$aAssetHumidity Properties

guid $aAssetHumidity

type double

name Humidity

history true

use config-view

printf %.1f

units rh

description Reports the humidity at the asset (raw value in % RH).

CenterScape API Specification 23

$aAssetImage

$aAssetImage Properties

guid $aAssetImage

type mimeref

name Asset Image

history false

use config-view

description The value of this attribute is an image file associated with an asset.

$aAssetLockClosed

$aAssetLockClosed Properties

guid $aAssetLockClosed

type bool

name Lock Closed

history true

use status

description Reports the asset’s lock closed status reported by the asset’s tag.

CenterScape API Specification 24

$aAssetLockCount

$aAssetLockCount Properties

guid $aAssetLockCount

type long

name Lock Count

history true

use status

description Reports the asset’s lock count reported by the asset’s tag.

$aAssetLockOpen

$aAssetLockOpen Properties

guid $aAssetLockOpen

type bool

name Lock Opened

history true

use status

description Reports the asset’s lock opened status reported by the asset’s tag.

CenterScape API Specification 25

$aAssetLowBattery

$aAssetLowBattery Properties

guid $aAssetLowBattery

type bool

name Low Battery

history true

use status

Reports if the asset has detected a low battery condition reported by the
description
asset’s tag.

$aAssetMotion

$aAssetMotion Properties

guid $aAssetMotion

type bool

name Motion

history true

use status

description Reports the asset’s motion status reported by the asset’s tag.

CenterScape API Specification 26

$aAssetMotionCount

$aAssetMotionCount Properties

guid $aAssetMotionCount

type long

name Motion Count

history true

use status

description Reports the asset’s motion count reported by the asset’s tag.

$aAssetPanic

$aAssetPanic Properties

guid $aAssetPanic

type bool

name Panic

history true

use status

description Reports if the panic switch has been activated on the asset’s tag.

CenterScape API Specification 27

$aAssetSensorLowBattery

$aAssetSensorLowBattery Properties

guid $aAssetSensorLowBattery

type bool

name Sensor Low Battery

history true

use status

Reports if the asset has detected a low battery condition for an attached
description
sensor.

$aAssetTamper

$aAssetTamper Properties

guid $aAssetTamper

type bool

name Tamper

history true

use status

Reports if the asset has detected a tamper attempt as reported by the

description
asset’s tag.

CenterScape API Specification 28

$aAssetTemperature

$aAssetTemperature Properties

guid $aAssetTemperature

type double

name Tem

history true

use status

printf %.1f

units Celsius

description Reports the temperature of the asset (raw value in degrees C).

$aAssetUserPayload

$aAssetUserPayload Properties

guid $aAssetUserPayload

type long

name User Payload

history true

use status

description Reports an asset’s numeric payload as reported by the asset’s tag.

CenterScape API Specification 29

$aBoundAsset

$aBoundAsset Properties

guid $aBoundAsset

type entityref

name Associated Asset

history true

use hidden

“typeref” : “$tEntity”
constraints Value of this attribute must be constrained to references to entities whose
type is “$tEntity” or inherits from “$tEntity”.

This attribute contains the reference to the entity (asset) to which a tag is
description
bound.

$aCookieData

$aCookieData Properties

guid $aCookieData

type map

name CookieData

history false

use hidden

This attribute is used by the CenterScapeWeb UI to contain user UI set-

description
tings.

CenterScape API Specification 30

$aDescription

$aDescription Properties

guid $aDescription

type string

name Description

history true

use config-view

The value of this attribute is intended to contain a descriptive label for an

description
asset.

$aDetectedLocation

$aDetectedLocation Properties

guid $aDetectedLocation

type typeref

name Detected Location

history true

use status

description The location of an asset based on the server’s configured location rules.

CenterScape API Specification 31

$aEnabled

$aEnabled Properties

guid $aEnabled

type bool

name Enabled

history true

use config-view

The value of this attribute is intended to control the enable/disable state of

description
an object.

$aLocation

$aLocation Properties

guid $aLocation

type typeref

name Asset Location

history true

use config-view

“typeref” : “$tLocation”
constraints Values of this attribute must be references to a entity type that is a des-
cendant of the “$tLocation” type.

true
inherit_attributes The attribute values associated to the location typeref will be inherited by
asset.

description The value of this attribute is the current declared location of an asset.

CenterScape API Specification 32

$aName

$aName Properties

guid $aName

type string

name Name

history true

use config-view

The attribute is used to contain the name of an asset. Values of this attrib-
ute must be unique for all objects defined in CenterScape. The value of
description this attribute can be changed. The CenterScape Web UI uses this attribute
to uniquely identify or select assets. All user-defined assets types contain
this attribute.

$aOnline

$aOnline Properties

guid $aOnline

type bool

name Online Status

history true

use status

If the value of this attribute is true, the tag associated with the asset is cur-
description
rently observable from one or more readers.

CenterScape API Specification 33

$aPassword

$aPassword Properties

guid $aPassword

type password

name Password

history true

use config

encoding “SHA-512”

Password attribute used for resources that need user/password authen-

description
tication.

$aServiceDate

$aServiceDate Properties

guid $aServiceDate

type date

name Service Date

history true

use status

description This attribute contains the creation date of an object.

CenterScape API Specification 34

$aViewAttributes

$aViewAttributes Properties

guid $aViewAttributes

type string-list

name View Attributes

history false

use config

A list of zero or more attribute guids that define the attributes to be dis-
description
played when a view is selected in the CenterScape Web UI.

Retired

Retired Properties

guid retired

type bool

name Retired

history true

use hidden

This attribute is used to set the retired status of an asset. If the value of this
attribute is false, an asset is considered active. If the value is true, an asset
is considered retired. This attribute is used throughout the CenterScape
description
Web UI when generating reports or viewing an asset’s attributes. When
retiring an asset through the CenterScape Web UI, the user has the option
of disassociating its asset tag.

CenterScape API Specification 35

Type

Type Properties

guid type

type typeref

name Asset Type

history true

use hidden

“typeref” : “$tRoot”
constraints Value of this attribute must be a reference to “$tRoot” or any descendant
of “$tRoot”.

This attribute is the type of any object in the system. The value of this
description
attribute cannot be changed after an object is created.

3.2 Entity Types

As described in “Object Types”, entity types can be defined hierarchically. The CenterScape server
defines and uses many built-in types to configure and monitor the state of the CenterScape server. The
CenterScape administrator is expected to create new entity types which model their customer’s assets.
Most of the built-in entity types defined are only accessible by a user with administrator privileges.
This section lists the entity types a customer will encounter when defining new entity types used when
modeling their own asset types. By convention, all built-in entity type GUIDs start with “$t”. All built-
in entity types have their “deletable” property set to false.

CenterScape API Specification 36

$tRoot

$tRoot Properties

guid $tRoot

parent

name Root

This entity type is the root node in the entity type hierarchy for both sys-
description tem- and customer-defined entity types. With the exception of custom
attribute types, all entity types have this type as their ancestor.

$tEntity

$tEntity Properties

guid $tEntity

parent $tRoot

name Entity

description Base entity type for all user and system objects.

$aName
Every instance of $tEntity (or ancestor of $tEntity) has the $aName attrib-
attributes ute. Values of the $aName attribute must be unique for any type which
has the $aName attribute. This attribute is used in multiple places in the
Web UI to uniquely identify and select entity instances.

CenterScape API Specification 37

$tUserEntity

$tUserEntity Properties

guid $tUserEntity

parent $tEntity

name User Entity

description Parent type for user-related objects.

$tAsset

$tAsset Properties

guid $tAsset

parent $tUserEntity

name Asset

description Base entity type for all user-related objects.

$aDescription
attributes
$aLocation

CenterScape API Specification 38

$tAssetAlert

$tAssetAlert Properties

guid $tAssetAlert

parent $tAlert

name Asset Alert

Root of the entity type tree for alerts that are created from thresholds
description
applied to assets.

$tUnassignedTag

$tUnassignedTag Properties

guid $tUnassignedTag

parent $tUserEntity

name Unassigned Tag

Entity type used when creating instances of tags which have been accep-
description
ted by a user to associate to an asset.

attributes $aLocation

3.3 Custom Attribute Types

There are several built-in custom attributes types defined by the CenterScape server’s schema, the most
notable of which is $tLocation. The $tLocation custom attribute type is the root of all user-defined loc-
ations.

CenterScape API Specification 39

$tLocation

$tLocation Properties

guid $tLocation

parent

name Location

description This entity type is the root node for all user-created locations.

$tUnknownLocation

$tUnknownLocation Properties

guid $tUnknownLocation

parent $tLocation

name Unknown Location

This is the entity type used to designate the value of the $aLocation attrib-
description ute of an asset when the location of an asset cannot be determined using
the currently defined location rules.

CenterScape API Specification 40

4.0 Putting It Together: An Example

To illustrate the concepts outlined in the data model and data schema sections, a small data schema is
presented. The following example will use JSON as the representation format.
The sample schema will model IT equipment. A good place to start is to create a list of object types
that you want to model. This will help you determine how you want to classify your asset types. For
this example, we will limit the equipment list to Servers.
Now that we know what we want to model, we need to think about the information we want to track
for each of the asset types we have. The list of information you want to track on each object type will
be a good starting place for the attribute classes you need to create for modeling your assets.
The root of the customer’s data model begins by creating one or more child asset types from the built-
in asset type “Asset”. CenterScape already associates several built-in attribute classes with the Asset
entity type: “Name”, “Description, “Asset Location”.
In this example, we’re going to use the default object type hierarchy:

The JSON representation for these entity types (excluding the built-in type “$tAsset”) is expressed as:
[
{
"class" : "entity_type",
"guid" : "INVENTORY",

CenterScape API Specification 41

 "name" : "Inventory",
"parent" : "$tAsset",
"deletable" : true,
"description" : "",
},
{
"class" : "entity_type",
"guid" : "EQUIPMENT",
"name" : "Equipment",
"parent" : "$tInventory",
"deletable" : true,
"description" : "",
},
{
},
{
"class" : "entity_type",
"guid" : "SERVER",
"name" : "Server",
"parent" : "EQUIPMENT",
"deletable" : true,
"description" : "",
}
]
For all IT assets, we want to track the Purchase Terms (Purchase, Leaser, or Loaner), Purchase Date,
Purchase Value, Manufacturer, and Model.
The JSON representation for these attributes classes can be expressed as:
[
{
"class" : "attribute_type",
"guid" : "PURCHASE_TERMS",
"type" : "string",

CenterScape API Specification 42

 "deletable" : true,
"history" : true,
"inherit_attributes" : false,
"subtype" : "",
"name" : "Purchase Terms",
"description" : "",
"values" : [ "Purchase", "Lease", "Loaner" ]
},
{
"class" : "attribute_type",
"guid" : "PURCHASE_DATE",
"type" : "date",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"subtype" : "",
"name" : "Purchase Date",
"description" : "",
"values" : [ ]
},
{
"class" : "attribute_type",
"guid" : "MODEL",
"type" : "string",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"subtype" : "",
"name" : "Model",
"description" : "",
"values" : [ ]
},

CenterScape API Specification 43

{
"class" : "attribute_type",
"guid" : "MANUFACTURER",
"type" : "string",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"subtype" : "",
"name" : "Manufacturer",
"description" : "",
"values" : [ "Acer", "American Power Conversion", "Apple", "Asus", "BenQ", "Brocade",
"Brother", "Canon", "Cisco Systems", "Compaq", "Dell", "D-Link", "EMC Corporation", "Epson",
"Everex", "Extreme Networks", "Foundry Networks", "Fujitsu", "Fujitsu Siemens", "Gateway",
"Hewlett-Packard", "Hitachi", "IBM", "Iomega", "Juniper Networks", "Konica Minolta", "Leibert",
"Lenovo", "Lexmark", "LG Electronics", "Linksys", "Logitech", "Maxtor", "NEC", "NCR", "Nor-
tel", "OKI", "Olivetti", "Panasonic", "Philips", "Ricoh", "Samsung", "Seagate", "Sharp", "SMC Net-
works", "Sony", "Sun Microsystems", "Toshiba", "Unisys", "ViewSonic", "WatchGuard",
"Westinghouse", "Xerox" ]
},
{
"class" : "attribute_type",
"guid" : "PURCHASE_VALUE",
"type" : "double",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"subtype" : "",
"name" : "Purchase Value",
"description" : "",
"constraints" : {
"min" : 1.0
},
"values" : [ ]
}

CenterScape API Specification 44

]

Let’s examine a few of the attribute classes individually to illustrate some of the capabilities of the
CenterScape data model.
l Purchase Terms: In the attribute class “Purchase Terms”, we see the type of the attribute class
is “string”. The attribute class also defines the “values” as “[ "Purchase", "Lease", "Loaner" ]”.
By specifying the “values” field in the attribute class, we are restricting the value of this field to
be one of the values listed in the values array. A value for this attribute other than one of these
strings will be flagged by the server as invalid.
l Purchase Date: This represents the date an IT asset was purchased.
l Model: The model of the IT asset. Any string value is valid for this attribute class.
l Manufacturer: Like “Purchase Terms”, this attribute class is a string whose values are limited
to those specified in the “values” array.
l Purchase Value: The purchase price of the IT asset. The minimum value for values of this
attribute class cannot be lower than 1.0 otherwise the CenterScape server will indicate the value
is invalid.
Up to this point we have three entity types and five new attribute classes. The attribute classes have
been defined but they have not been assigned to any asset type. In order to assign an attribute class to
an entity type we must use entity type attributes. Each entity type attribute is used to declare how the
CenterScape Web UI presents an attribute class and some additional data-binding semantics for an
attribute class/entity type mapping.
In the following example, “Purchase Terms”, Purchase Date”, “Manufacturer”, and “Purchase Value”
have all been added to “Equipment”.
{
"class" : "entity_type",
"guid" : "EQUIPMENT",
"name" : "Equipment",
"parent" : "$tInventory",
"deletable" : true,
"description" : "",
"attributes" : [
{
"guid" : "PURCHASE_TERMS",
"class" : "entity_attribute",
"deletable" : true,

CenterScape API Specification 45

 "required" : false,
"isStatic" : false,
"category" : "Basic Information",
"sortPriority" : 50
},
{
"guid" : "PURCHASE_DATE",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"category" : "Basic Information",
"sortPriority" : 60
},
{
"guid" : "MANUFACTURER",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"category" : "Basic Information",
"sortPriority" : 70
},
{
"guid" : "MODEL",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"category" : "Basic Information",
"sortPriority" : 80
},

CenterScape API Specification 46

 {
"guid" : "PURCHASE_VALUE",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"category" : "Basic Information",
"sortPriority" : 65
}
]
}

As you can see, the declaration of the entity type “Equipment” has grown considerably. The difference
is the addition of the entity type attribute “attributes”. “attributes” is an array of attribute classes that
have been added to the definition of the entity type. Each entry in this array is an entity type attribute.
The order they are declared has no bearing on how they appear when presented in the CenterScape
Web UI. A sample input form for an Equipment would appear as:

The entity type attribute “sortPriority” determines the order of an attribute independent of entity type
attribute “category”.
If we want to track additional information that is specific to one of the child types of “Equipment”, we
would update their entity type declarations to include the additional entity type attributes. For this

CenterScape API Specification 47

example, we will introduce one additional attribute class for “Servers”. The additional “Server” Attrib-
ute Class is:
{
"class" : "attribute_type",
"guid" : "SERVER_FORM_FACTOR",
"type" : "string",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"subtype" : "",
"name" : "Server Form Factor",
"description" : "",
"values" : [ "Rackmount", "Blade", "Micro" ]
}
To add this attribute to the “Server” entity type, the new “Server” entity type declaration would be:

[
{
"class" : "entity_type",
"guid" : "SERVER",
"name" : "Server",
"parent" : "EQUIPMENT",
"deletable" : true,
"description" : "",
"attributes" :
[
{
"guid" : "SERVER_FORM_FACTOR",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,

CenterScape API Specification 48

 "category" : "Server Information",
"sortPriority" : 1400,
"value" : "Rackmount"
}
]
}
]

The new attribute is added in a new category: “Server Information”. Since “Server” inherits from
“Equipment”, it has all the attributes of an “Equipment” asset plus the “Server Form Factor” attribute.
Also, the “value” field has been added to the entity type attribute. The value “Rackmount” will be used
as the default value for the “Server Form Factor” attribute. A sample input form for a “Server” would
appear as:

The new attribute appears at the bottom of the dialog as a result of the sortPriority being greater than all
other attributes. In addition, the attribute is displayed in a new group box as a result of the new cat-
egory: “Server Information”.
This small sample has addressed attribute classes, entity types and entity type attributes. One powerful
feature of the CenterScape data model which has not been demonstrated is the use of custom attribute
types. A custom attribute type looks identical to an entity type except the root entity type of a custom
attribute type does not have a parent.
For this example, let’s say we want to track the department to which an IT Asset is assigned. We could
easily create a new string attribute class whose values are all the valid department names that exist in
your organization. As you dig a bit deeper, perhaps you realize when an IT Asset is assigned to a

CenterScape API Specification 49

department, there is additional information that each department maintains for its IT Equipment and
that list of attributes each department maintains is different from department to department. A custom
attribute type is the perfect choice for modeling this information.
For this example, the custom type is displayed in the CenterScape Web UI as:

The JSON representation for these entity types would be expressed as:
[
{
"class" : "entity_type",
"guid" : "DEPARTMENT",
"name" : "Department",
"deletable" : true,
"description" : ""
},
{
"class" : "entity_type",
"guid" : "FINANCE",
"name" : "Finance",
"parent" : "DEPARTMENT",
"deletable" : true,
"description" : ""
},
{
"class" : "entity_type",
"guid" : "ENGINEERING",
"name" : "Engineering",
"parent" : "DEPARTMENT",
"deletable" : true,
"description" : ""
}
]

CenterScape API Specification 50

As you can see the, the Custom Attribute Type declarations are identical to those declared for the
object type hierarchy. Also it is worth mentioning the “Department” entity type has no parent. We can
now associate additional attributes to the “Finance” Entity Type and “Engineering” Entity Type. The
new attributes are “Manager”, “Contains Employee Data”, and “System Use” expressed using the fol-
lowing JSON:
[
{
"class" : "attribute_type",
"guid" : "MANAGER",
"type" : "string",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"name" : "Manager",
"use" : "config-view",
"description" : "",
"values" : [ ]
},
{
"class" : "attribute_type",
"guid" : "CONTAINS_EMPLOYEE_DATA",
"type" : "bool",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"name" : "Contains Employee Data",
"use" : "config-view",
"description" : "",
"values" : [ ]
},
{
"class" : "attribute_type",

CenterScape API Specification 51

 "guid" : "SYSTEM_USE",
"type" : "string",
"deletable" : true,
"history" : true,
"inherit_attributes" : false,
"restrictable" : false,
"name" : "System Use",
"use" : "config-view",
"constraints" : {
"values" : true
},
"values" : [ "Build", "Development", "Test", "Production" ]

}
]

As before, we apply the attribute classes to the entity types. In this example, the “Department” Entity
Type remains the same. Each child type of “Department” has new Attribute Classes added. The “Man-
ager” Attribute Class has been associated with both “Engineering” and “Finance”. When the “Man-
ager” attribute is applied to “Engineering” entity type , its value is “Bob Murphy” and “isStatic” is true.
This means the value is constant and cannot be overridden. When “Manager” is applied to “Finance”,
its value is “Tom Kendle”. Again, it is declared to be static and its value cannot be overridden. The
“System Use” attribute class is associated with the “Engineering” entity type and the “Contains
Employee Data” attribute class is associated with the “Finance” Entity Type. The updated entity type
definitions are expressed using the following JSON:

[
{
"class" : "entity_type",
"guid" : "DEPARTMENT",
"name" : "Department",
"deletable" : true,
"description" : ""
},

CenterScape API Specification 52

 {
"class" : "entity_type",
"guid" : "ENGINEERING",
"name" : "Engineering",
"parent" : "DEPARTMENT",
"deletable" : true,
"description" : "",
"attributes" : [
{
"guid" : "SYSTEM_USE",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"category" : "Department",
"sortPriority" : 2010
},
{
"guid" : "MANAGER",
"class" : "entity_attribute",
"deletable" : true,
"required" : true,
"isStatic" : true,
"value" : "Bob Murphy",
"category" : "Department",
"sortPriority" : 2000
}
]
},
{
"class" : "entity_type",
"guid" : "FINANCE",

CenterScape API Specification 53

 "name" : "Finance",
"parent" : "DEPARTMENT",
"deletable" : true,
"description" : "",
"attributes" : [
{
"guid" : "CONTAINS_EMPLOYEE_DATA",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"value" : false,
"category" : "Department",
"sortPriority" : 2010
},
{
"guid" : "MANAGER",
"class" : "entity_attribute",
"deletable" : true,
"required" : true,
"isStatic" : true,
"value" : "Tom Kendle",
"category" : "Department",
"sortPriority" : 2000
}
]
}
]
The custom types have been created and new attribute classes have been associated with these types.
Now we need a way for associating the custom entity types to the entity type hierarchy. The first thing
we need to do is create a new attribute class that references the custom type hierarchy. This new attrib-
ute is called “Owning Department” represented by:

CenterScape API Specification 54

{
"class" : "attribute_type",
"guid" : "OWNING_DEPARTMENT",
"type" : "typeref",
"deletable" : true,
"history" : true,
"inherit_attributes" : true,
"restrictable" : false,
"name" : "Owning Department",
"use" : "config-view",
"constraints" : {
"typeref" : "DEPARTMENT",
"typeref_select" : "leaf"
}
}

This attribute class’s type is “typeref”. This means the value of this attribute must be a GUID of an
Entity Type. The constraints object is used to limit the branch or node in the entity type hierarchy for
valid values of this attribute class. Now we apply this attribute just like any other to a node in the entity
type hierarchy. In this case, we’ll say all Servers should have an Owning Department so we add the
attribute to the “Server” entity type expressed as:

[{
"class" : "entity_type",
"guid" : "SERVER",
"name" : "Server",
"parent" : "EQUIPMENT",
"deletable" : true,
"restrictable" : false,
"description" : "",
"attributes" : [ {
"guid" : "$aMountType",
"class" : "entity_attribute",

CenterScape API Specification 55

 "deletable" : true,
"required" : true,
"isStatic" : false,
"value" : "MOUNT_TYPE_RACK_U_MOUNT",
"category" : "Rack Configuration",
"sortPriority" : 60
}, {
"guid" : "OWNING_DEPARTMENT",
"class" : "entity_attribute",
"deletable" : true,
"required" : false,
"isStatic" : false,
"category" : "Department",
"sortPriority" : 2000
}]
}]
The “Owning Department” is a drop-down tree selection allowing the customer to select which depart-
ment the IT Asset belongs. By selecting “Finance”, the entity now inherits the attributes associated
with the “Finance” custom entity type as illustrated in is Server input form:

CenterScape API Specification 56

The new entity will now have the “Manager” attribute set to “Tom Kendle” and the other Finance
attribute “Contains Employee Data” is presented because it is part of the “Finance” entity type defin-
ition.
Similarly, if “Engineering” is selected as the Owning Department value, the “Manager” attribute is set
to “Bob Murphy” and the “System Use” attribute is presented because it is part of the “Engineering”
entity type as illustrated in the dialog:

CenterScape API Specification 57

CenterScape API Specification 58
5.0 Command Reference

The HTTP command URLs used to configure and monitor the CenterScape server are presented in
this section. For each HTTP command, a functional description is provided for the four basic HTTP
methods (GET, POST, PUT, and DELETE).
The minimum privilege required to execute a command is specified. If an attempt to execute a com-
mand is made with credentials that do not meet the minimum privilege, a HTTP status code of 401 is
returned.

5.1 Attribute Class

Attribute Class Management

Command <base-url>/attributeclass

The attributeclass command is used to create, update, or delete attrib-

Description
ute classes.

Retrieves one or more attribute classes.

Command syntax and parameters:

l attributeclass

GET Retrieves all attributes classes.

l attributeclass/<object-guid>

object-guid (required) – The GUID of the attribute class to

retrieve.
Retrieves the attribute class with the specified object GUID.

CenterScape API Specification 59

 Attribute Class Management

l attributeclass?type=<object-type-guid>

type = object-type-guid (required) – The object type GUID.

Retrieves all attributes classes which are defined for the spe-
cified object type and all its inherited type(s).

Command output:

If the command is successful, the output is either a JSON-encoded

array of the requested attribute classes or a single JSON object rep-
resenting the requested attribute class.

Minimum privilege level required:

Asset Viewer

Curl example:

curl -u user:password '[Link]

port/api/attributeclass/'$aAssetMotion'

Creates an attribute class.

Command syntax and parameters:

l attributeclass/

POST body contains a JSON-encoded attribute class object.

POST
Command output:

If the command is successful, indicated by HTTP status code 201, no

output is returned. If the command is unsuccessful, indicated by
HTTP status code 400, a JSON-encoded errors object is returned.

Minimum privilege level required:

CenterScape API Specification 60

 Attribute Class Management

System Administrator

Curl example:

curl -i -H 'content-type: application/json' -u admin:admin -d @<post-

body-filename> '[Link]

Where <post-body-filename> is the name of the file containing the

post body.

Updates an existing attribute class.

Command syntax and parameters:

l attributeclass/<object-guid>

object-guid (required) – Attribute class object guid.

Updates the attribute class with the specified object guid.

POST body contains a JSON-encoded attribute class object.

Command output:

PUT If the command is successful, indicated by HTTP status code 201, no

output is returned. If the command is unsuccessful, indicated by
HTTP status code 400, a JSON encoded errors object is returned.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -X PUT -H 'content-type: application/json' -u admin:admin -d

@<post-body-filename> '[Link]

Where <post-body-filename> is the name of the file containing the

post body.

CenterScape API Specification 61

 Attribute Class Management

Deletes an existing attribute class.

Command syntax and parameters:

l attributeclass/<object-guid>

object-guid (required) – Attribute class object guid.

Deletes the attribute class with the specified object guid.

Command output:
DELETE
If the command is successful, indicated by HTTP status code 200, no
output is returned.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -X DELETE -u admin:admin '[Link]

port/api/attributeclass/object-guid'

CenterScape API Specification 62

5.2 Audit Log

Audit Log Retrieval

Command <base-url>/audit

Description The audit command is used to retrieve audit log messages.

Retrieves audit log messages within a specified time range or all audit
messages.

Command syntax and parameters:

l audit?from=<utc-start-time>&to=<utc-end-time>&start-
t=<starting-index>&limit=<max-result-count>

from (optional) – UTC start time value

to (optional) – UTC end time value
start (optional) – The index of the first item in the result set
from which to return results. For example, if a audit query
GET returns 100 items, specifying a start value of 5 will prune off
the first 5 elements from the result set.
limit (optional) – The maximum number of log messages to
return.

Command output:

If the command is successful, a JSON object is returned with

the count of audit messages and an array of audit messages
which include the timestamp in milliseconds the audit message
was logged, the user which initiated the action and the message
indicating the change which occurred.

CenterScape API Specification 63

 Audit Log Retrieval

The following is a sample response:

{
"count" : 2,
"data" : [

"timestamp" : 1225303027379,
"message" : "User Login - admin - from remote address
[Link]",
"user" : "admin"
},
{
"timestamp" : 1225303023679,
"message" : "User Login - foo - from remote address
[Link]",
"user" : "foo"
}
]
}

Minimum privilege level required:

System Administrator

Curl example:

curl -u admin:admin [Link]

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 64

5.3 Entity

Entity Object Management

Command <base-url>/entity

The entity command is used to create, update, or delete user and sys-
Description
tem objects.

Retrieves one or more entities.

Command syntax and parameters:

l entity/<object-guid>

object-guid (required) - The guid of the object to retrieve.

l entity?type=<entity-type-guid>

entity-type-guid (required) – The guid of an entity type. All

instances of the specified type are retrieved.

GET
Command output:

If the command is successful, an array of JSON objects or a single

JSON object is returned.

Minimum privilege level required:

The minimum privilege level required is dependent on the type of the

object being requested. In general, system object types require Sys-
tem Administrator privilege, whereas user asset types require the least
privileged user Asset Viewer.

Curl example:

curl -u viewer:viewer [Link]

CenterScape API Specification 65

 Entity Object Management

Creates an entity of a specific type.

Command syntax and parameters:

l entity/

POST body contains the JSON-encoded object to create. The object

is validated using the semantics of the type of entity to create and the
attribute classes referenced by this type and its inherited types.

Command output:

If the command is successful, the response is the JSON-encoded

object of the newly created object. If the command is unsuccessful, an
errors object is returned indicating the reason or reasons why the
POST object creation failed.

Minimum privilege level required:

The minimum privilege level required is dependent on the type of the

object being to create. In general, creation of system object require
System Administrator privilege, whereas creation of user asset object
require the least privileged user Asset Viewer.

Curl example:

curl -i -X PUT -H 'content-type: application/json' -u admin:admin -d

@<post-body-filename> [Link]

Where <post-body-filename> is the name of the file containing the

post body.

CenterScape API Specification 66

 Entity Object Management

Updates an entity of a specific type.

Command syntax and parameters:

l entity/<object-guid>

Post body contains a JSON-encoded object to update. Attributes are

removed from an entity by setting their attribute value to 'null'.

You can use this command to update one or more attributes on one or
more entities using a several parameters which allow you to specify
the set of entities to update.

filter (required) – Boolean set to true to indicate a filter

definition is included in the command paramters.

type (required) – The guid of the entity types to update.

PUT
attribute (optional) – The guid of the attribute class to filter
by.

operator (optional) – The filter operator to apply to the

attribute and value.

value (optional) – The attribute value.

attribute2 (optional) – The guid of the second attribute

class to filter by.

operator2 (optional) – The second filter operator to apply

to the attribute and value.

value2 (optional) – The second attribute value.

CenterScape API Specification 67

 Entity Object Management

Deletes an entity
l entity/<object-guid>
object-guid (Required) – The guid of the entity to delete.

Similar to the PUT method, you can use this command do delete one
or more entities which match a specific filter criteria.

type (required) – The guid of the entity types to update.

attribute (optional) – The guid of the attribute class to filter

by.

DELETE operator (optional) – The filter operator to apply to the

attribute and value.

value (optional) – The attribute value.

attribute2 (optional) – The guid of the second attribute

class to filter by.

operator2 (optional) – The second filter operator to apply

to the attribute and value.

value2 (optional) – The second attribute value.

CenterScape API Specification 68

5.4 Configuration Import

Configuration Import

Command <base-url>/configimport

The configimport command is used to create or update existing

Description entities, entity types or attribute classes. It is intended to allow the
customer to create or update assets in a bulk format.

GET N/A

The post is either a multi-part form upload or contains in the

body a JSON-encoded object which indicates the default schema
to load.

Command syntax and parameters:

l configimport

This command supports two different methods for creating

or updating entities.
POST
The first format is a multi-part form upload. The format of
the data is either CSV or JSON where the mime type of a
CSV part should be “text/csv” and “application/json” for a
JSON part. If the file being uploaded has an extension that
ends with “.csv”, it will be interpreted as a CSV file
regardless of the part’s content type.

CenterScape API Specification 69

 Configuration Import

Command output:

A JSON-encoded status object is returned indicating if the

request was successful. If it was not successful, the status object
contains an array of error messages indicating the reason or reas-
ons why the request failed.

Minimum privilege level required:

The minimum privilege level required is dependent on the type

of the objects being imported. Since the file of objects being
imported may contain assets of different types, the requester must
have the privilege level necessary to create or update all assets
contained in the file being uploaded, otherwise the request will
fail.

Curl example:

curl -X POST -u admin:admin -F 'filecontent=@<[Link]>'

'[Link]

Where <[Link]> is the name of the file containing the post

body.

PUT N/A

DELETE N/A

CenterScape API Specification 70

5.5 Configuration Export

Configuration Export

Command <base-url>/configexport

The configexport command is used to export existing entities, entity

Description
types, or attribute classes.

This command can be used to export a collection of CenterScape

objects (either system objects or customer’s assets).

Command syntax and parameters:

l configexport

The configexport command supports a variety of methods to

export information from the CenterScape server. The first
method allows System Administrators to export the user asset
schema (Asset Type, Attribute Classes, and Custom Attribute
GET Types). The configexport command supports three ways of
exporting data: schema export, export by filter, export by guid.

Schema export allows you to back up your customer asset

schema by exporting all the customer’s assets types, attribute
classes, and custom attribute types.

Export by filter allows you to specify a filter condition an asset

must match for it to be exported.

Export by guid allows you to explicitly specify the guids of the

assets to export.

CenterScape API Specification 71

 Configuration Export

The following are the supported parameters for this command:

General parameters:

format = <“JSON”|“CSV”> Set the response format.

Schema export parameters:

schema = <true> Indicates the customer’s asset schema should be

exported.

Filter export parameters:

To export by filter, you would use the same parameters as those for
the api/filter command.

filter = <true> Indicates the configexport command is exporting the

assets that match those of the filter defined in the request body.

type = <type-guid> (required when exporting by filter) Specifies the

filter asset types.

location = <location-type-guid> (optional) Specifies the filter location

of an asset.

attribute = <attribute-guid> (optional) Specifies the guid of the attrib-

ute used in the filter condition.

operator = <“eq” | “ne” | “gt” | “lt” | “ge” | “le”, “undef”| “def”, “con-
tains” | “containselement” | “startswith” | “in” | “inlist”> (optional) Spe-
cifies the operator used when comparing the value of the filter
attribute.

value = <attribute comparison value> (optional) Specifies the value to

compare in the filter condition.

CenterScape API Specification 72

 Configuration Export

attributeset = (optional) <attribute-guid | “*”> (optional) Specifies the

list of attributes that should be returned for the assets matching the fil-
ter. The parameter is repeated for each attribute that is requested. If
the value of this parameter is “*”, then all attributes for the assets
matching the filter are returned in the result.

attributesort = <attribute-guid> (optional) Specifies the attribute used

to sort the filter results.

sortorder = <“asc” | “desc” | “none”> (optional) Specifies the sort

order applied to the attributesort parameter.

showretired = <“yes” | “no” | “both”> (optional) Specifies if the result

set should include retired assets. The default is “no”.

dateformat = <“iso8601”> (optional) Specifies if time stamps and

date attributes should be formatted using the ISO 8601 format.

mimerefs = <“true” | “false”> (optional) Specifies if the result set

should include mime objects (image files) if assets have attributes ref-
erencing them.

prettyprint = <“true” | “false”> (optional) Specifies if the result set

should use an attribute’s name, rather than <guid>, to represent an
attribute.

resolverefs = <“true” | “false”> (optional) Specifies if the result set

should use a custom attribute in the format of <attribute-
guid>.$aName, rather than <attribute-guid>, and its value should be
the name of an asset, rather than <entity-guid>.

Guid export parameters:

guid = <entity-guid> Specifies the guid of the asset to export. This

parameter is repeated for every asset to export.

Schema export parameters:

CenterScape API Specification 73

 Configuration Export

Config export parameters:

type = <entity-type-guid> Specifies the type of entity (configuration)

to export. This parameter is repeated for every entity type to export.
<entity-type-guid> includes $tSmtpServer, $tRanger, $tReader,
$tTagGroup, $tSensorDefinition, $tLocation, $tRule, $tUser,
$tGroup, $tLdapAuthenticationMethod, $tAssetLink, $tAs-
setAlertAction, $tAssetAlertThreshold, $tAssetTemplate, $tAt-
tributeView, $tUserDashboard, $tFolder, $tMap, $tMapView,
$tHotspot, $tHotSpotTarget, $tReport, $tReportAction, $tBirtTem-
plate, $tEventTrigger, $tEventTrigger, $tMonitor, $tStatPack,
$tStatPolicy.

Command output:

The output of the command is a file containing the requested assets or

schema to export. If the format of the request is “JSON” the file con-
tains a JSON array of matching requested objects. If the format is
“CSV”, a comma-separated file is returned.

Minimum privilege level required:

The minimum privilege level required is dependent on the type of the

objects being exported. Since the file of objects being exported may
contain assets of different types, the requester must have the privilege
level necessary to view all the assets contained in the file being down-
loaded, otherwise the request will fail. If the request is to export the
customer asset schema, System Administrator privilege is required.

Curl example:

MadCap:conditions="[Link]">curl -u admin:admin -i 'loc-

alhost:8080/api/configexport?filter=true&type=$tAsset
&dateformat=iso8601' (user-friendly date)

CenterScape API Specification 74

 Configuration Export

Curl example:

Export custom schema:

curl u admin:admin -d ‘schema=true’ -i ‘loc-

alhost:8080/api/configexport’

Export server configuration and smtp server setting:

curl -u admin:admin -d 'type=$tServerConfig&type=$tSmtpServer'

"localhost:8080/api/configexport"

POST Export all assets with user-friendly date/time:

curl u admin:admin -d 'filter=true&type=$tAsset

&dateformat=iso8601' -i 'localhost:8080/api/configexport'

Export Temperature/Humidity sensors with Rack Position Top and

current temperature greater than 20 degrees Celsius:

curl -u admin:admin -d 'filter=true&type=TEMPERATURE_

HUMIDITY
&attribute=RACK_POSITION&-operator=eq
&value=Top&attribute2=$aAssetTemperature&operator2=
gt&value2=20' -i 'localhost: 8080/api/configexport'

PUT N/A

DELETE N/A

CenterScape API Specification 75

5.6 Current User

Current User

Command <base-url>/currentuser

The currentuser command is used to retrieve information, including

Description
authorized roles, for the currently authenticated browser user.

The command returns a JSON-encoded object containing user inform-

ation.

Command syntax and parameters:

l currentuser

Command output:

GET The output of the command is a JSON-encoded object containing the

current user information.

Minimum privilege level required:

Asset Viewer

Curl example:

curl -i -u admin:admin [Link]

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 76

5.7 Change Password

Change Password

Command <base-url>/changepassword

The changepassword command is used to allow unprivileged users

Description
the ability to modify their own password.

GET N/A

Updates the password for the currently authenticated user.

Command syntax and parameters:

l changepassword

The body should contain a URL-encoded form the with the fol-
lowing parameters:
POST
userName (required) – The name of the user for which to
change the password

currentPassword (required) – The user’s current password.

newPassword (required) – The new password for the specified

user.

CenterScape API Specification 77

 Change Password

Updates the password for the currently authenticated user.

Command syntax and parameters:

Command output:

If the command is successful, indicated by HTTP status code 200, no output is

returned.
POST
Minimum privilege level required:

Asset Viewer

Curl example:

curl -i -X POST -u user:password -d "user-

Name=user&currentPassword=password&newPassword=newpassword"
[Link]

PUT N/A

DELETE N/A

CenterScape API Specification 78

5.8 Database Configuration

Database Configuration

Command <base-url>/databaseconfiguration

The databaseconfiguration command is used to create, update or

Description
retrieve the configuration to connect to a database server.

Retrieves the current database configuration.

Command syntax and parameters:

l databaseconfiguration

Command output:

GET If the command is successful, a JSON-encoded object is returned rep-

resenting the current database configuration.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -u admin:admin [Link]

CenterScape API Specification 79

 Database Configuration

Creates or updates the configuration used to connect to a database server.

Command syntax and parameters:

l databaseconfiguration

The POST body contains a JSON-encoded object representing the

new or updated database configuration.

Example:

{
"type":"POSTGRESQL",
"host":"localhost",
"port":"5432",
"name":"rfcode",
POST "user":"rfcode",
"password":"rfcode",
"contact":""
}

Command output:

If the command is successful, no output is returned from the command. If

the command is unsuccessful, an errors object is returned indicating the
reason or reasons why the object update failed.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -X POST -u admin:admin [Link]

PUT N/A

DELETE N/A

CenterScape API Specification 80

5.9 Entity Type

Entity Type

Command <base-url>/entitytype

The entitytype command is used to create, update or delete entity type

Description
objects.

Retrieves one or more entity types.

Command syntax and parameters:

General parameters:

l format = <“JSON”|“CSV”> Set the response format.

GET
l entitytype?children=true

Returns entity types which do not have a parent.

children = <true> (optional) – Return all child entity types of the

top-level entity types.

CenterScape API Specification 81

 Entity Type

l entitytype/<object-type-guid>?inherited=<true|false>

object-type-guid (required) The guid of the entity type to retrieve.

Returns the specified entity type and all its children unless the inher-
ited parameter is set to false.

inherited = <true|false> (optional) – Return the entity types the spe-

cified entity type inherits from.

Command output:

The output of the command is one or more entity types encoded using the
requested format. The default format is JSON.

Minimum privilege level required:

Asset Viewer

Curl example:

curl -i -u admin:admin [Link]

Creates a new entity type.

Command syntax and parameters:

l entitytype
POST
The POST body should contain a JSON-encoded object rep-
resenting the new entity type.

Example:

CenterScape API Specification 82

 Entity Type

{
"guid":"TRUCK",
"name":"Truck",
"description":"",
"deletable":true,
"parent":"$tAsset"

Command output:

If the command is successful, no output is returned from the command. If

the command is unsuccessful, an errors object is returned indicating the
reason or reasons why the object update failed.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -X POST -H 'content-type: application/json' -u admin:admin -d

@<post-body-filename> [Link]

Where <post-body-filename> is the name of the file containing the post

body.

Updates an existing entity type.

Command syntax and parameters:

l entitytype/<entity-type-guid>
PUT
The POST body contains a JSON-encoded object representing the
updated entity type.

Example:

CenterScape API Specification 83

 Entity Type

"guid":"TRUCK",
"name":"Truck",
"description":"",
"deletable":true,
"parent":"$tAsset",
"children":[],"attributes": [{"guid":"COLOR",

"name":"Color",

"deletable":true,

“required":true,

"isStatic":false,

"category":"Appearance",

"sortPriority":500}],

"class":"entity_type"
}

Command output:

If the command is successful, no output is returned from the command. If

the command is unsuccessful, an errors object is returned indicating the
reason or reasons why the object update failed.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -X PUT -H 'content-type: application/json' -u admin:admin -d

@<post-body-filename> [Link]

CenterScape API Specification 84

 Entity Type

Where <post-body-filename> is the name of the file containing the post

body.

Deletes an existing entity type.

Command syntax and parameters:

l entitytype/<entity-type-guid>

entity-type-guid (required) – The guid of the entity type to delete.

Command output:

DELETE If the command is successful, no output is returned from the command. If

the command is unsuccessful, an errors object is returned indicating the
reason or reasons why the object update failed.

Minimum privilege level required:

System Administrator

Curl example:

curl -i -X DELETE -u admin:admin [Link]

type-guid

CenterScape API Specification 85

5.10 Filter

Filter Query

Command <base-url>/filter

The filter command allows you to create a query by creating a number of

conditions based on asset type, asset location, asset attribute values, and
other asset states. The assets which match all the conditions specified in
the filter are included in the result set returned to the command caller.

The most basic form of the filter command is querying assets by type. In
fact, asset type is the only required condition that must be specified in the
filter command, all other parameters are optional.

There are two methods the filter command can use. The first method
allows you to construct a filter and then query which assets on the Center-
Description Scape server match the condition(s) specified in the filter. When the com-
mand is run the assets that match the conditions specified in the filter are
returned in the result set.

The second method allows you to declare the conditions an asset must
match in order to be returned in the result set just like the first method;
however, by specifying a unique value for the filterid, you are instructing
the CenterScape server to remember the filter definition and accumulate
change notifications to the result set initially returned. You can then issue
another command - “filterupdates” to listen for these change notifications
to the assets that were originally returned from the filter command.

CenterScape API Specification 86

 Filter Query

The filter and filterupdates commands use session cookies to correlate the
calling application across multiple requests. Normally, if the commands
are called from a web page, the browser will manage the session cookie.
When not using a browser, the session cookie can be specified by append-
ing “;jsessionid=<session-cookie>” on the end of a url but before any para-
meters.

You can think of the filter command as a means of defining a view into
the set of assets in the CenterScape server. Using a filteridi parameter, the
server will accumulate change notifications to the view. You can think of
the filterupdates command as the means of receiving updates for the cur-
rently defined filters.

Query assets by type and location, or any arbitrary attribute value.

Command syntax and parameters:

l filter

type = <entity-type-guid> (required) – The base type of the objects

for which to receive change notifications.

location = <location-type-guid> (optional) – The entity type guid

of the location object the entities must equal to in order to be
included in the result set. For example, if the location is FLORIDA,
GET only entities that have a location of FLORIDA would be included
in the result set.

attribute = <attribute-guid> (optional) Specifies the guid of the attrib-

ute used in the filter condition.

operator = <”eq” | “ne” | “gt” | “lt” | “ge” | “le”, “undef”| “def”,

“contains” | “containselement” | “startswith” | “in”> (optional) Spe-
cifies the operator used when comparing the value of the filter attrib-
ute.

CenterScape API Specification 87

 Filter Query

The output of the command is a JSON-encoded array containing the res-

ults of the filter query. There are additional objects encoded in the array
which indicate how the response should be decoded. Each object returned
contains an attribute called “updtype” which indicates information about
the result set of the results themselves. The possible values of “updtype”
are:

create - An asset entered the filter result set.

update - An asset that was in the result set has been updated or
is part of the initial set returned.
delete - An asset has been removed from the result set as a result
of the asset being deleted on the CenterScape server.
entered - An asset has entered the filter result set as a result of
one or more the asset attributes being updated to match the filter
condition(s).
exited - An asset has exited the filter result set as a result of the
asset’s attribute(s) no longer matching the filter condition(s).
countupd - The number of assets which are returned from the
command.
rowlist - If sorting was requested, the rowlist is the sorted order
of the entity guids in the result set.

A example will illustrate how the command output is formatted. The fol-
lowing curl example is used to query all the assets of the root asset type
'$tAsset':

curl -i -u admin:admin [Link]

The results of the command are:

CenterScape API Specification 88

 Filter Query

"class" : "fltupdevt",

"timestamp" : 1225474644976,

"updtype" : "countupd",

"count" : 1

},

"class" : "fltupdevt",

"timestamp" : 1225474644976,

"updtype" : "entered",

"entity" : {

"class" : "entity",

"guid" : "CAR_fcf94f38",

"retired" : false,

"deletable" : true

},

CenterScape API Specification 89

 Filter Query

"updtype" : "rowlist",

"last-update" : true,

"roworder" : [ "CAR_fcf94f38" ]

Each object in the result set also includes the CenterScape timestamp of
when the event was created.

The first object included in the result set is of an “updtype” of “countupd”.

This object indicates how many asset updates are included in the response.

The next object that is returned is the single asset that matched the filter
condition and in this example is bounded by the maximum count of 1. The
asset itself is nested in the object under the “entity” property. For all the
assets returned from this command, the “updtype” is “entered”.

The last update is a “rowlist” object which contains the “roworder” prop-
erty. This is the new sort for the contents of the assets in the filter result
set.

Minimum privilege level required:

The minimum privilege level required is dependent on the type of the

objects being request by the filter’s type parameter. In general, Asset
Viewer is required when specifying customer asset types. System types
require System Administrator privilege.

Curl example:

curl -i -u admin:admin [Link]

%24tAsset&filterid=fid_84133&attribute=

CenterScape API Specification 90

 Filter Query

TRUE&attributeset=%24aName&attributesort=
%24aName&sortorder=asc&start=0&count=25

This example queries the assets whose tag tamper attribute are currently
true. The name attribute is returned for each asset, the entities are sorted in
ascending order by their name and the view starts at the first asset in the
sorted list and returns a maximum of 25 assets.

POST Same as GET. The parameters are URL-encoded in the body of the post.

PUT N/A

DELETE N/A

CenterScape API Specification 91

5.11 Filter Delete

Filter Delete

Command <base-url>/filterdelete

The filterdelete command is used to delete a filter that was previously cre-
ated as interested in receiving change notifications. The server will release
Description
any resources allocated for accumulating change notifications for the filter.

Delete a filter.

Command syntax and parameters:

l filterdelete?filterid=<filter id>

filterid = <filter id> (required) – The id of the filter to delete. This

value should match the filterid parameter value used when creating
a filter.

GET Command output:

No output is returned from this command.

Minimum privilege level required:

Asset Viewer

Curl example:

curl -i -u admin:admin [Link]

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 92

5.12 Filter Update

Filter Update

Command <base-url>/filterupdate

The filterupdate command allows to request asset change noti-

fications for all filters created using the same session id and for filters
that specified a value for the filterid parameter.

The filterupdate command is used to periodically drain the queue of

accumulated change notifications for the saved filters. The caller is
expected to invoke this command, wait for any updates that may have
Description accumulated, process the change notifications received from the
CenterScape server and repeat this process as long as the caller is
interested in receiving change notifications.

Filter change notifications will be accumulated for saved filters up till

the point where they are deleted using the filterdelete command or if
they expire. A saved filter will expire if there has been no request to
retrieve change notifications for a filter for 120 seconds.

CenterScape API Specification 93

 Filter Update

Request asset change notifications.

Command syntax and parameters:

l filterupdates?_timeout=<milliseconds>&_maxcnt=<maximum
assets to return>

_timeout = <millisecond> (optional) - This parameter controls

how long the server waits to accumulate filter change noti-
fications before returning to the caller. If the server already has
change notifications queued when filterupdates is called, those
results are immediately returned to the caller. If there are no
pending change notifications, the server waits up to the timeout
period or until a change notification is queued before returning
to the caller. The default timeout is 30 seconds (30000 mil-
liseconds).
l _maxcnt = <count> (optional) – This parameter is used to
bound the size of the change notifications returned in any
single call to the filterupdates command. If this parameter is not
specified, all queued change notifications are returned to the
caller.

Command output:

The output of the command is a JSON-encoded array containing the

results of the filter query. If there are no queued filter change noti-
fications, an empty JSON array “[]” is returned. There are additional
objects encoded in the array which indicate how the response should
be decoded. Each object returned contains an attribute called “upd-
type” which indicates information about the result set of the results
themselves. The possible values of “updtype” are:

create - An asset entered the filter result set.

update - An asset that was in the result set has been
updated or is part of the initial set returned.
delete - An asset has been removed from the result set as a

CenterScape API Specification 94

 Filter Update

The following is a response to filterupdates as a result of a new Car

asset type being created.

{
"class" : "fltupdevt",
"filterid" : "fid_63020",
"timestamp" : 1225481827543,
"updtype" : "countupd",
"count" : 2
},
{
"class" : "fltupdevt",
"filterid" : "fid_63020",
"timestamp" : 1225481827543,
"updtype" : "create",
"entity" : {
"class" : "entity",
"guid" : "CAR_76c931e4",
"retired" : false,
"deletable" : true,
"$aName" : "F-150",
"$aDescription" : "",
"type" : "CAR"
}
},
{
"class" : "fltupdevt",
"filterid" : "fid_63020",
"timestamp" : 1225481827543,
"updtype" : "rowlist",
"last-update" : true,
"roworder" : [ "CAR_76c931e4", "CAR_fcf94f38" ]
}

CenterScape API Specification 95

 Filter Update

Minimum privilege level required:

Asset Viewer. The filter command will control the privilege of the
assets which can be requested by a user and in turn receive change
notifications using this command.

Curl example:

curl -i -u admin:admin [Link]

Same as GET. The parameters are URL-encoded in the body of the

POST
post.

PUT N/A

DELETE N/A

CenterScape API Specification 96

5.13 History

History

Command <base-url>/history

This history command is used to report all value changes for all assets
or a subset of assets for a specified time range. The population of
assets reported on can be subset by asset type and optionally asset loc-
ation. The time range specified for the API can be an absolute time
range (for example, February 1, 2014 to February 28, 2014) or rel-
ative to the current time (for example, the last hour relative to the time
the API is invoked).
Description
The API can optionally be invoked to report the “lead-in” value for
all assets being reported on. The lead in value is described as the
value of an attribute on or before the start time of the report. If the
lead in value is already known, it is recommended to not report the
lead in value due to the additional resource expense required to query
these values.

Retrieves the asset changes during the time range specified in the com-
mand for all or the specified list of attributes.

Command syntax and parameters:

l history?filtertype=tAsset&seconds=600&name=
GET LastTenMinutes&prettyprint=false&format=
CSV&leadin=true

filtertype (required) – The GUID of the asset type specifying

the assets to report on. If the intent is to report on all assets, the
value of this parameter should be “$tAsset”.

CenterScape API Specification 97

 History

filterlocation (optional) – The GUID of a location. This allows the

caller to subset the population of assets being returned by the location
specified.

name (optional) – The name of the report. Used to give a name to the
report when the report output is JSON.

seconds (optional) – The number of seconds indicating the range of

the report relative to the current time. For example, if you want to
report history for the last ten minutes, the value of seconds is 600.

start (optional) – The start time of the report in milliseconds. (Epoch

time)

stop (optional) – The stop time of the report in milliseconds. (Epoch

time)

calendar (optional) – Allows the user to specify the start/stop time of

the report using convenient calendar values. The values for calendar
are:

thisday – The current day from midnight to the current time.

thisweek – The current week from Sunday midnight to the current

time.

thismonth – The current month from the first of the month to the cur-
rent time.

yesterday – The beginning of yesterday to the end of yesterday.

lastweek – The beginning of the start of last week to the end of last
week.

lastmonth – The beginning of the start of last month to the end of last
month.

CenterScape API Specification 98

 History

(optional) – Used to display the raw value of an attribute or the

cooked value of an attribute relative to the servers timezone/locale.
The value is either true or false.

format (optional) – Used to specify the output format. The value is

either JSON or CSV. The default is JSON.

leadin (optional) – Used to specify if the leadin value should be repor-

ted for attributes. If the leadin value is known, the value of the attrib-
ute should be false due to the additional expense incurred to produce
the leadin value.

attribute (optional) – The GUID of the attribute(s) to report. If the

attribute is omitted, all attributes which had a value change during the
report interval are returned.

Command output:

The output of this command are the results of the attribute changes
presented in either a JSON or CSV.
Minimum privilege level required:

The minimum privilege level required is dependent on the type of the

objects in the report output. Since the report output may contain assets
of different types, the requester must have the privilege level neces-
sary to view all the assets contained in the report, otherwise the
request will fail.

Curl example:

To report the history changes for all assets for the last ten minutes and
output the result using CSV:

curl -u admin:admin '[Link]

history?seconds=600&filtertype= %24tAsset&name=
LastTenMinutes&prettyprint=false&format=
CSV<adin=true'

CenterScape API Specification 99

 History

To report the history changes for all assets from the beginning of May
1st, 2014 to the end of May 1st 2014:

curl -u admin:admin '[Link]

history? start=1398902400000&stop=
1398988799999&filtertype= %24tAsset&name=
MayFirst2014&prettyprint=false&format=
CSV<adin=true'

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 100

5.14 Report Output

Report Output

Command <base-url>/reportoutput

The reportoutput command is used to generate report output from a pre-

Description
viously created report.

Retrieves (generates) a report for a specified report object.

Command syntax and parameters:

Command output:

The output of this command are the results of the report presented in either
a JSON, CSV, PDF, XML, or PNG image file

Minimum privilege level required:

GET
The minimum privilege level required is dependent on the type of the
objects in the report output. Since the report output may contain assets of
different types, the requester must have the privilege level necessary to
view all the assets contained in the report, otherwise the request will fail.

Curl example:

curl -i -u admin:admin '[Link]

localhost:6580/api/reportoutput/$tAssetReportJob_a44efddc.csv'

curl -i -u admin:admin '[Link]

localhost:6580/api/reportoutput/$tAssetReportJob_a44efddc.xml?start=10'

CenterScape API Specification 101

 Report Output

Retrieves (generates) a report for a specified report object.

Command syntax and parameters:

Command output:

The output of this command are the results of the report presented in either
a JSON, CSV, PDF, XML, or PNG image file

Minimum privilege level required:

The minimum privilege level required is dependent on the type of the

objects in the report output. Since the report output may contain assets of
different types, the requester must have the privilege level necessary to
view all the assets contained in the report, otherwise the request will fail.

Curl example:

curl -i -u admin:admin '[Link]

localhost:6580/api/reportoutput/$tAssetReportJob_a44efddc.csv'

curl -i -u admin:admin '[Link]

localhost:6580/api/reportoutput/$tAssetReportJob_a44efddc.xml?start=10'

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 102

5.15 Report

Report

Command <base-url>/report

The report command is used to output an instant report for the specified
Description
entity and attribute.

Retrieves (generates) a report for a specified report object.

Command syntax and parameters:

Command output:

The output of this command are the results of the report generated in either
a JSON, CSV, PDF, XML, or PNG image file.
GET
Minimum privilege level required:

The minimum privilege level required is the same as the privilege of the
entity-guid used when creating the instant report.

Curl example:

curl -i -u admin:admin '[Link]

localhost:6580/api/[Link]?attr=$aAssetMotion&entity=CAR_
fe986be7&msecsAgo=21600000&name=Instant%20Report%20Example'

CenterScape API Specification 103

 Report

Command <base-url>/report

The report command is used to output an instant report for the specified
Description
entity and attribute.

Retrieves (generates) a report for a specified report object.

Command syntax and parameters:

Command output:

The output of this command are the results of the report generated in either
a JSON, CSV, PDF, XML, or PNG image file.

Minimum privilege level required:

The minimum privilege level required is the same as the privilege of the
entity-guid used when creating the instant report.

Curl example:

curl -i -u admin:admin '[Link]

localhost:6580/api/[Link]?attr=$aAssetMotion&entity=CAR_
fe986be7&msecsAgo=21600000&name=Instant%20Report%20Example'

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 104

5.16 Tag

Tag

Command <base-url>/tag

The tag command is used to retrieve detailed diagnostic information for a

Description
specific RFID tag from the Zone Manager(s) connected to Asset Server.

Retrieves detailed tag information for a specified tag.

Command syntax and parameters:

l tag/<tag-guid>

Minimum privilege level required:

tag-guid (required) – The guid of the tag for which to retrieve detailed
GET
information.

Command output:

The output of the command is a JSON-encoded object containing the tag

data retrieved from all Zone Managers which are within range of the tag.
The top most properties of the object are the Zone Manager GUIDs which
are currently observing the tag. An example output where only the local
Zone Manager is observing the tag is:

CenterScape API Specification 105

 Tag

Retrieves detailed tag information for a specified tag.

Command syntax and parameters:

Minimum privilege level required:

tag-guid (required) – The guid of the tag for which to retrieve detailed
information.

Command output:

The output of the command is a JSON-encoded object containing the tag

data retrieved from all Zone Managers which are within range of the tag.
The top most properties of the object are the Zone Manager GUIDs which
are currently observing the tag. An example output where only the local
Zone Manager is observing the tag is:

"LOCAL_RANGER" : {

"RFCLOC00005495" : {

"id" : "RFCLOC00005495",

"attributes" : {

"tagid" : "00005495",

"taggroupid" : "$zTagGroup_mantis04A_9c88adf9",

"tagtype" : "mantis04A",

"irlocator" : "000",

CenterScape API Specification 106

 Tag

"motion" : "false",

"tamper" : "false",

"panic" : "false",

"lowbattery" : "false",

"locationzone" : "",

"confidencebyrule" : {

},

"confidencebyrule_resolved" : {

},

"taglinks" : [ {

"tagid" : "RFCLOC00005495",

"channelid" : "$zReaderM200_7277a2b_channel_A",

"ssi" : -66,

"channelid_resolved" : "Desk CHANNEL_A"

}, {

"tagid" : "RFCLOC00005495",

"channelid" : "$zReaderM200_7277a2b_channel_B",

"ssi" : -87,

CenterScape API Specification 107

 Tag

"channelid_resolved" : "Desk CHANNEL_B"

}]

},

"zonemanager" : "Local Zone Manager"

Minimum privilege level required:

CenterScape

Curl example:

curl -i -u admin:admin [Link]

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 108

5.17 Tag Import

Tag Import

Command <base-url>/tagimport

Description The tagimport command is used to import RFID tag IDs.

GET N/A

The post is either a multi-part form upload or contains in the body a

JSON-encoded object which contains the guids of the tags to create.

Command syntax and parameters:

l tagimport

If the POST is a multi-part form upload, the format of the tag file is:

[Link],[Link]
POST
LOCATE00003845,24FE2A9B

...

If the POST is not a multi-part form upload, the body of the POST
is expected to be a JSON-encoded array with the following format:

CenterScape API Specification 109

 Tag Import

The post is either a multi-part form upload or contains in the body a

JSON-encoded object which contains the guids of the tags to create.

Command syntax and parameters:

Command output:

The output of the command is a JSON-encoded status object indicating

how many of the tags were imported out of the request. Example:

"success" : true,

"messages" : [

"code" : "[Link]",

"message" : "The tag import was successful: 0 tag(s) were impor-

ted and 1 tag(s) already existed."

Minimum privilege level required:

CenterScape

Curl example:

curl -i -X POST -H 'content-type: application/json' -u admin:admin -d

@<post-body-filename> [Link]

Where <post-body-filename> is the name of the file containing the post

CenterScape API Specification 110

 Tag Import

body.

PUT N/A

DELETE N/A

CenterScape API Specification 111

5.18 Schemas

Schemas

Command <base-url>/schemas

The schemas command is used to retrieve the names of the predefined

Description
schemas bundled with the server.

Retrieves a list of built-in asset schemas bundled with the CenterScape

server.

Command syntax and parameters:

l schemas

Command output:

GET A JSON-encoded array of strings where each string is the name of a

schema.

Minimum privilege level required:

System Administrator

Curl example:

url -i -u admin:admin [Link]

POST N/A

PUT N/A

DELETE N/A

CenterScape API Specification 112

5.19 Zone Manager Import

Zone Manager Import

Command <base-url>/zonemgrimport

The zonemgrimport command is used to import a Zone Manager’s con-

Description figuration. This allows Zone Manager users to quickly configure a Center-
Scape server based on their existing Zone Manager configuration.

GET N/A

Imports a zone manager configuration.

Command syntax and parameters:

l zonemgrimport

The POST is a multi-part form upload containing a Zone Man-

ager’s configuration files. Not every files is required but if present,
they must match the names of the saved Zone Manager con-
POST figuration files. The files names are, in order, “[Link]”, “read-
[Link]”, “[Link]”, and “[Link]”.

Command output:

If the command is successful, no output is returned from the command. If

the command is unsuccessful, an errors object is returned indicating the
reason or reasons why the object update failed.

CenterScape API Specification 113

 Zone Manager Import

Imports a zone manager configuration.

Command syntax and parameters:

Command output:

If the command is successful, no output is returned from the command. If

the command is unsuccessful, an errors object is returned indicating the
reason or reasons why the object update failed.

Minimum privilege level required:

System Administrator

Curl example:

curl -u admin:admin -F “filecontent=@<[Link]>” [Link]

port/api/zonemgrimport

PUT N/A

DELETE N/A

CenterScape API Specification 114

6.0 Command Examples

This section demonstrates how to perform common queries and asset updates using the CenterScape
command interface.

6.1 Exporting Assets By Filter - All Assets Attributes

This example exports all customer assets in CSV format. Dates and times
Description are exported using the ISO 8601 format. All asset attributes are exported
since the “attributeset” parameter has a value of “*”.

curl -i -u admin:admin '[Link]

GET filter=true&format=CSV&type=%24tAsset&attributeset=
*&sortorder=asc&showretired=no&dateformat=iso8601'

6.2 Exporting Assets By Filter – Specific Asset Attributes

This example exports all customer assets in CSV format. Dates and times
Description and exported using the ISO 8601 format. The assets attributes included are
most of the tag specific attributes.
curl -i -u admin:admin '[Link]
filter=true&format=CSV&type=%24tAsset&attributeset=
%24aName&attributeset=%24aAssetTag&attributeset=
type&attributeset=%24aAssetTemperature&attributeset=
GET %24aAssetPressure&attributeset=%24aAssetDoorOpen&
attributeset=%24aAssetMotion&attributeset=%24aAsset
Tamper&attributeset=%24aAssetPanic&attributeset=
%24aAssetLowBattery&sortorder=asc&showretired=no&
dateformat=iso8601'

CenterScape API Specification 115

6.3 Importing New Assets

Description This example imports new assets from a CSV file.

curl -i -u admin:admin -F 'filecontent=@[Link]' '[Link]

port/api/configimport'

The assets specified in the [Link] will be uploaded and created. The
assets specified in the uploaded file are subject to the same validation cri-
teria as assets created using the CenterScape Web UI.

Note: If the guid is not specified for the asset being created, a unique guid
GET
will be automatically generated. You can explictly specify the guid if you
so desire. If the guid for an asset already exists for an asset being imported,
the attributes for the asset will be considered an update to the existing
asset.

A sample CSV asset file would look like:

class,type,retired,deletable,$aName,COLOR,$aDescription entity,CAR,-
false,true,Chevrolet Volt,Green,Plugin Hybrid

6.4 Updating Existing Assets

This example is identical to creating assets. The sample asset file lists the
Description GUID for the assets that already exist. All the asset attribute value in the
file are used to update the existing attributes.

curl -i -u admin:admin -F 'filecontent=@[Link]' '[Link]

port/api/configimport'

GET A sample CSV asset file would look like:

class,guid,type,retired,deletable,$aName,COLOR,$aDescription
entity,CAR_fe986be7,CAR,false,true,Chevrolet Volt,Red,Plugin Hybrid

CenterScape API Specification 116

6.5 Querying a Specific Asset By GUID

This example queries a specific asset by its GUID. The format of the out-
Description put can be either CSV or JSON and is set using the “format” parameter.
This example is requesting the output in CSV.

url -i -u admin:admin '[Link]

GET
format=CSV'

6.6 Querying Assets By Location

This example queries all assets with the location 'DEPOT'. Like other
examples which use a filter, you can select the type of assets you want the
filter to match, the specific attributes to include in the response and the con-
Description ditions the asset must match to be included in the response. The conditions
in this example is the assets much be of '$tAsset' or a descendant of '$aAs-
set' and they must be in the location 'DEPOT' or a descendant of
'DEPOT'.

curl -i -u admin:admin '[Link]

%24tAsset&location=DEPOT&attributeset=%24aName
&attributeset=%24aAssetTag&attributeset=type&
attributeset=%24aAssetTemperature&attributeset=
GET %24aAssetPressure&attributeset=%24aAssetDoorOpen&
attributeset=%24aAssetMotion&attributeset=%24aAsset
Tamper&attributeset=%24aAssetPanic&attributeset=
%24aAssetLowBattery&sortorder=asc&showretired=
no&dateformat=iso8601'

CenterScape API Specification 117

6.7 Creating a Filter and Listening for Updates

The following example creates a filter and using the filterid parameter
instructs the CenterScape server to retain the filter information and start
accumulating change notifications to the filter specified.
Description
Note: The session cookie is specified using the jsessionid parameter. The
filterupdate command uses the same value for the session id. The server
will aggregate the change notifications for all filters created using the same
session id and return the results.

The following call creates the filter for all assets whose type inherits from
the root Asset type and whose location is 'DEPOT'.

curl -i -u admin:admin '[Link]

=SESSION_1?type=%24tAsset&location=DEPOT&attributeset=
%24aName&attributeset=%24aAssetTag&attributeset=
type&attributeset=%24aAssetTemperature&attributeset=
%24aAssetPressure&attributeset=%24aAssetDoorOpen&
attributeset=%24aAssetMotion&attributeset=%24aAsset
Tamper&attributeset=%24aAssetPanic&attributeset=
GET %24aAssetLowBattery&sortorder=asc&showretired=no&
dateformat=iso8601?filterid=DEPOTLOCATION'

The following call will query for the updates to all the filters that were cre-
ated using the sessionid = 'SESSION_1'. The command will return imme-
diately if there are change notifications pending to any of the filters created
using the same session id or wait the default time of 30 seconds before
returning if no changes are pending.

curl -i -u admin:admin '[Link]

jsessionid=SESSION_1'

CenterScape API Specification 118

6.8 Query All Unresolved Alerts

The following example creates a filter to query for all alerts which are not
Description
resolved or closed.

curl -i -u admin:admin '[Link]

'ALERT_SESSION'?type=$tAssetAlert&attributeset=
GET
*&sortorder=asc&attribute=
$aAlertState&operator=lt&value=3&filterid=ALERTS'

6.9 Create an Instant Report

The following example runs an instant report on motion for a specific

Description
entity and outputs the results in XML format.

curl -i -u admin:admin '[Link]

[Link]?attr=$aAssetMotion&entity=CAR_
GET
fe986be7&msecsAgo=21600000&name=Instant%20
Report%20Example'

CenterScape API Specification 119

6.10 Create a Report

Description The following example creates a new Report entity.

curl -i -X PUT -H 'content-type: application/json' -u admin:admin -d @up-

[Link] '[Link]

This update creates a new Reader Noise Report for the last day dis-
playing $aName, $zReaderNoiseA, and $zReaderNoiseB attributes for all
readers on the system, assuming the reader has been in the NoiseDetected
state during the last day using the JSON encoded object in the file
[Link]. The contents of the file are:

"type":"$tReaderNoiseReport"

,"$aName":"Reader Noise Example"

GET
,"$aReportEmailAddress":""

,"$aReportEmailAttachment":""

,"$aReportCreateOutputIfData":true

,"$aReportTime":"$tReportTimeRangeRelative"

,"$aReportTimeRangeRelative":3

,"$aReportSchedule":null

,"$aReportScheduleEnable":false

CenterScape API Specification 120

 ,"$aReportAttribute":""

,"$aReportAttributeValueOperator":""

,"$aReportFilterAttribute":""

,"$aReportFilterAttributeValueOperator":""

,"$aReportPostconditionAttribute":"$zReaderState"

,"$aReportPostconditionAttributeValueOperator":"eq"

,"$aReportPostconditionAttributeValue":10

,"$aReportChangeAttributes":null

,"$aReportAttributes":["$aName","$zRead-
erNoiseA","$zReaderNoiseB"]

CenterScape API Specification 121

7.0 Programming Tools

Java Jackson JSON parser:

[Link]

CenterScape API Specification 122