Each datapoint can be specified using instance names or XIF names. A datapoint can be specified by a path, such as:

Datapoint path:

{device id or name}/{block name}/{block index}/{datapoint name}

Datapoint Instance path:

{device id or name}/{block instance name}/{block index}/{datapoint instance name}

Datapoint XIF path:

{device id or name}/{block XIF name}/{block index}/{datapoint XIF name}


The datapoint instance names are what you see in the CMS Datapoint Browser widget default view, and are changeable. The datapoint XIF names are what is specified in the device XIF file (e.g., XIF, MOD, BAC files), and what is seen in the Datapoint Properties widget (and exported DLA file). The datapoint XIF name does not change, so it is usually used when developing custom Web pages. You can also see the datapoint XIF names in the CMS Datapoint Browser widget using the Details view. In most cases, the datapoint instance name is the same as the datapoint XIF name, and the block instance name is the same as the block XIF name.

MQ API uses XIF names. The REST API and WS API allow you specify requests using the datapoint instance names or datapoint XIF name. Most REST API and WS API requests use instance names, to use XIF name you will need to add “*+xifName={xif name}” to the path parameter or query parameter.

Currently there is only one Block Name parameter in IAP which means the Block Instance Name and the Block XIF Name are the same. 

MQ API

The MQ API uses device did and and XIF names for subscribing and publishing topics and data.

Datapoint XIF path:

{device DID = 5}/lamp/0/nviValue
glp/0/+/rq/dev/lon/5/if/lamp/0 {"nviValue":{"value":{"value":75,"state":1}}}

REST API

The REST API allows you specify requests using the datapoint instance names or datapoint XIF name. You can also use the device Id or device name to specify the device. Most request use instance names, to use XIF name you will need to add “*+xifName={xif name}” to the path parameter or query parameter.

For example, to read “Sensor1” device datapoint value which has “nviLamp” as the datapoint instance name, “nviValue” as the datapoint XIF name, and block instance name and block XIF name are the same:


Datapoint Instance path
:

Sensor1/Lamp/0/nviLamp1/value


Datapoint XIF path
:

Sensor1/Lamp/0/nviValue/value


REST Request Format
:

/iap/devs/{device id or device name}/if/{block name}/{block index}/{datapoint name}/value


Reading using datapoint instance name

/iap/devs/*+name==Sensor1/if/Lamp/0/nviLamp/value

     or

/iap/devs/*+name==Sensor1/if/*+name==Lamp/0/*+name==nviLamp/value


Reading using datapoint XIF name

/iap/devs/*+name==Sensor1/if/*+xifName=Lamp/0/*+xifName=nviValue/value

WS API

The WebSocket WS API allows you specify requests using the datapoint instance names or datapoint XIF name. You can also use the device id or device name to specify the device. Most request use instance names, to use XIF name you will need to add “*+xifName={xif name}” to the path parameter or query parameter.



3.20 API Changes

  1. Names used in REST API (like GET request) and WS API requests have changed.

    1. Most request now use instance names - prior to 3.20 most requests used XIF name.
      REST Examples:

      • 3.2: /iap/devs/*+name==Sensor1/if/Lamp/0/nviLamp/value – NEW: uses instance names

      • 3.1: /iap/devs/*+name==Sensor1/if/Lamp/0/nviValue/value – OLD: uses XIF names

    2. “xifName” has been added for path and query parameters so you can use XIF name in a request
      REST Example:

      1. 3.2: /iap/devs/*+name==Sensor1/if/*+xifName=Lamp/0/*+xifName=nviValue/value

      2. 3.1: Not supported

  2. Datapoint XIF names created from XIF files (XIF, BAC, MOD) has changed

    1. Upgrading (using glpo file) from a pre-3.2 SmartServer to SmartServer 3.2+ may change the datapoint XIF names previously stored in the SmartServer which may affect 3.1 custom Web pages or applications.