(Optional)  A human-readable error description, if an error condition exists. If no error condition exists, the property is either set to null, or is not implemented.

The reported error always relates to the most recent action applied to the connection. When action A1 gives rise to error condition E1, E1 is reported. Subsequent successful execution of action A2 clears the error property even if error condition E1 still exists.

All errors are also reported through the error event channel using the IAP/MQ event reporting objects.  See Events.

implementation

string

(Optional)  Can be null. The edge server reports the connection’s implementation to describe how the connection was implemented within the segment. IAP does not define a finite list of possible values. The intention is to provide a short summary that is useful to someone familiar with the edge protocol.

For example, connection implementation can be described as “peer-to-peer, group 8” or “master/slave 15 min”.

state

string

(Optional)  Can be either “created”, “deleted”, “failed”, “provisioning”, “provisioned”, “unprovisioned”.

list of strings

(Required) Connections can specify local sources as topic strings. Sources must reference the feedback channel item.

Example:
[ "glp/0/DT-2/fb/dev/cm/12/if/occ/0/state/value"]

list of strings

string

(Optional) Either strict or smart.

A strict implementation policy requires a connection in the most efficient manner possible. For example, if an edge protocol supports true peer-to-peer connections, a strict peer-to-peer datapoint connection request fails if required resources are unavailable to implement the datapoint connection.

A smart implementation policy permits an automatic roll-over to a less efficient datapoint connection.  Typically to a point-to-point connection using the datapoint connection manager as an active relay agent in the data transfer.

object

(Optional) Guided transcoding of complex types is based on an optional map, which connects elements of a source properties to destination properties. This map can connect source and destination fields of different names, and provide simple explicit data transformations. See Type Translation for more information on maps.

There is one map for the connection.  Sources and destinations of peer-to-peer connections must all share the same datatype.  Sources and destinations in point-to-point connections only have to be assignment-compatible without a transformation map, or assignment-compatible after transformation with the map. 

Multiple distinct connections may be required to implement truly heterogenous datapoint connections.

The map is an associative array using destination property names for keys. The corresponding values are objects that describe the source property.

Example:
{ “$”: "value" }

(Optional) The datapoints presets are based on an optional presets map, which connects elements of a source properties to destination properties. A preset is a string that represents a specific native for a datapoint. The datapoint preset value can connect the source and the destinations fields.

There is one presets map definition for each datapoint source and destination. For additional information and examples, see Datapoint Presets.

{                                                          
 "source": {
   "$": {
     "transform": "$.value == 100 &&
       $.state == 1 ? \"ON\" : 
       $.value == 50 && $.state == 1 ?
       \"MID\" : $.value == 0 &&
       $.state == 0 ? \"OFF\" : \"INV\""
   }
 },
"destinations": [{
   "$": {
     "value": {
       "enumeration": {
         "source": "$",
         "map": {
           "ON": 90,
           "MID": 40,
           "OFF": 15
         }
        }
     },
     "state": {
       "enumeration": {
         "source": "$",
         "map": {
           "ON": 1,
           "MID": 1,
           "OFF": 0
         }
       }
     }
   },
   "onlyPreset": true
}],
 "repeatPresets": false 
}

(Optional) The datapoints localization is based on optional transformation rules, which connects elements of source properties to destination properties.  For additional information and examples, see Datapoint Localization. 

{                                                          
 "source": {
   "value": {
     "transform": "$.value * 0.5"
   },
   "state": {
     "transform": "$.state"
   }
},
 "destinations": [
   {
    "value": {
      "transform": "$.value * 0.5"
     },

    "state": {
      "transform": "$.state"
     }
   }
],
"repeatLoc": true
},

provision requires no arguments.  Once a connection is created, it can be provisioned. A provisioned connection is fully operational. Once a connection has been provisioned, it is active and data flow is possible across the connection.

Updates an existing connection.  Accepts the arguments listed below in the table Do Action Arguments, except all arguments are optional.

The update action can update parts of the connection.  For example, by submitting only the sources list with the update, leaves the destinations unchanged. 

Also, update might temporarily deprovision and re-provision the connection.

sources

list of strings

(Required) Connections can specify source items by referring to their feedback channel topics. See sources description in the connection configuration table above. 

destinations

list of strings

(Required) Connections can specify destinations by referring to their request channel topics.  See the destinations description in the Connection Configuration table above.

policy

string

(Optional) Either strict or smart. Defaults to “smart”

See the policy description in the Connection Configuration table above.

map

object

(Optional) See the map description in the Connection Configuration table above.

(Optional) Credentials for interchanges. 

Every interchange has a broker address and a subscription listed in the interchange object. Both are keys into the credentials object, using the broker address as the outer, the subscription as the inner key to username and password properties.

For example, consider an interface with broker mybroker.acme.com using the plain MQTT protocol on public port 1883 and subscription glp/0/&p21/# . The corresponding credentials object is shown here:

{
       "mqtt://mybroker.acme.com:1883": {
              "glp/0/&p21/#": {
                     username: "rosie",
                     password: "z21$8Kje",
              }
       }
}                                                         

The MQTT protocol is supported unsecured and secure (“mqtt” and “mqtts”, respectively). MQTT over secure Web Sockets is supported with the “wss” protocol identifier, MQTT over unsecured Web Sockets is supported with the “ws” protocol.  

The broker reference used with the interchange object always includes the protocol identifier and port number, even if the standard ports are used.  See the Interchange Object in the Connection Configuration Object table above.

Other protocol types may be added over time. Unsupported protocols yield an error and prevent the connection object from being provisioned successfully.

presets

See presets description in the Connection Configuration Properties table above.

Presets is available with SmartServer 2.8 and higher.

localization

See localization description in the Connection Configuration Properties table above.           

Localization is available with SmartServer 2.8 and higher.