Data Access Interface - RESTful API

General description

Format of the export template

General description

Data Access is intended as a powerful, highly configurable interface for accessing Entuity's internal data (like attribute values, stream data etc.)

The interface achieves this by processing the XML “templates” that describe sets of data to be exported. As these templates may be user-defined, this gives the customers an unprecedented level of control over the data itself, as well as their layout and format.

Currently, due to an extended set of possibilities in comparison to JSON, only XML template format is supported.

The interface consists of two parts (each described in detail later on): the “template management” which can be used to retrieve and modify templates residing on a server, and the “data access” part, which produces the output based on the early defined template.

Format of the export table

Example template:

The following example defines a template that would traverse the list of views (supplied by the user as a part of data output) and, based on the value of “selector” element, would traverse every device. For each device found, the element DEVICE_OBJECT will be created and populated with these element (in the order corresponding to their order in the template):

1. The element name, with a value of the name attribute of a device.
2. The attribute id, with a value of executing the simple;id statement on the current device.
3. The stream data v_unifiedDeviceCPU appearing as a CPU element, with all the underlying attributes.
4. The list of PORT_OBJECT elements, corresponding to the result of executing the simple;ref.ports statement on the current device. Each of these element would consist of:
   1. The attribute descr, with the value of simple;this.ifDescr statement for the current port.
   2. The element status, consisting of a list of samples, each containing two attributes: adminStatus (presented as an adm element) and operStatus, presented as an oper attribute.

An example XML Data Access Template

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataAccessTemplate name="Example template">
  <description>This is a test description</description>
  <object type="DeviceEx" tag="DEVICE_OBJECT">
    <selector>simple;ref.devices</selector>
    <filter></filter>
    <attribute asElement="true" expression="name"/>
    <attribute expression="simple;id" tag="id"/>
    <stream allAttributes="true" name="v_unifiedDeviceCPU" tag="CPU"/>
    <object type="PortEx" tag="PORT_OBJECT">
      <selector>simple;ref.ports</selector>
      <filter></filter>
      <attribute asElement="true" expression="simple;this.ifDescr" tag="Descr"/>
      <stream name="portStatus" tag="status">
        <attribute asElement="true" expression="adminStatus" tag="adm"/>
        <attribute expression="operStatus" tag="oper"/>
      </stream>
    </object>
  </object>
</dataAccessTemplate>

Export template syntax:

The following table describes all the XML nodes that can be a part of a Data Access Template. Unless stated otherwise, the order of elements is not important.
In the description below, some nodes have one of three symbols: ? (question mark), + (plus sign) or * (an asterisk) appended (in parenthesis) to their names.

These symbols are not part of the name itself, but serve to define how many times a node of this type may appear under the same parent:

?     – the node is optional and unique (i.e. may appear one or zero times)

*     – the node is optional and not unique (i.e. may appear any number of times)

+     – the node is mandatory and not unique (i.e. must appear one or more times)

Nodes without any such symbol are implied to be mandatory and unique.

Parameters can also be defined as templateParameters that can be used in expressions in the DataAccessTemplate. Any parameters passed in the URL that match an attribute name will be accessible in the statement language embedded in the template as 'templateParameter.<parameter value>'. Please see Data Access - Export Triggering: GET for further help and information on this.