IAP Names

FOR SMARTSERVER 3.3 AND PRIOR RELEASES, THE DATAPOINTS WIDGET IS CALLED THE DATAPOINT BROWSER WIDGET.

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

Datapoint path:

Datapoint Instance path:

Datapoint XIF path:

The datapoint instance names are what you see in the CMS Datapoints 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 Datapoints 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.

IAP/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. 

IAP/MQ API

The IAP/MQ API uses device id and XIF names to subscribe and publish 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

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

The following API changes apply to SmartServer 3.2 and higher:

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

   1. Most request now use instance names – prior to SmartServer 3.2, most requests used XIF name.
      REST Examples:

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

      • SmartServer 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. SmartServer 3.2: /iap/devs/*+name==Sensor1/if/*+xifName=Lamp/0/*+xifName=nviValue/value

      2. SmartServer 3.1: Not supported
         
         

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

   1. Upgrading (using glpo file) from a SmartServer prior to 3.2 to SmartServer 3.2 and higher may change the datapoint XIF names previously stored in the SmartServer which may affect SmartServer 3.1 custom web pages or applications.