JavaScript API
Connector functions JS API guide
In this javascript code, it is possible to use some defined functions to define the connector function. We will explain them below.
Input parameters
The main script will have access following main vars:
- entity: json with flattened operation target device entity representation.
- gateway: json with flattened gateway entity representation. It can be null.
- response: json with default response data (device identifier, request id (if known)…)
- collection: json with default collection data (device identifier if known)
- payload: it can be of different types: json object, binary content or flat text. It can contain different types of information: request or response information, collected data….
- contextParams: json object with execution context information. It can have some of this params:
- apiKey: device or user apikey.
- remoteIp: remote host when HTTP Rest Resource is invoked.
- uri: opened Websocket complete uri or invoked HTTP Rest Resource complete uri.
- path: opened Websocket relative path or invoked HTTP Rest Resource relative path. This is the path used as south criteria to filter CFs.
- topic: MQTT Topic where the message arrived.
- sessionIp: device session IP
- Protocol clients: clients such as mqtt, ssh, snmp… will be available for being used.
Here there is an example of entity or gateway:
entity = {
"provision.administration.channel": {
"_value": {
"_current": {
"value": "battery_channel",
"date": "2017-12-01T08:52:37.563Z",
"at": "2017-12-01T08:52:37.563Z"
}
}
},
"provision.administration.identifier": {
"_value": {
"_current": {
"value": "device_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.57Z",
"at": "2017-12-01T08:52:37.57Z"
}
}
},
"provision.administration.organization": {
"_value": {
"_current": {
"value": "battery_organization",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.566Z",
"at": "2017-12-01T08:52:37.566Z"
}
}
},
"provision.administration.plan": {
"_value": {
"_current": {
"value": "FLOW_RATE_100",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.565Z",
"at": "2017-12-01T08:52:37.565Z"
}
}
},
"provision.administration.serviceGroup": {
"_value": {
"_current": {
"value": "emptyServiceGroup",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.561Z",
"at": "2017-12-01T08:52:37.561Z"
}
}
},
"provision.device.communicationModules[].identifier": [
{
"_index": {
"path": "provision.device.communicationModules[].identifier",
"value": {
"_current": {
"value": "commsMod_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
},
"_value": {
"_current": {
"value": "commsMod_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
}
],
"provision.device.communicationModules[].subscription.address": [
{
"_index": {
"path": "provision.device.communicationModules[].identifier",
"value": {
"_current": {
"value": "commsMod_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
},
"_value": {
"_current": {
"value": {
"type": "IPV4",
"value": "99.1.1.71",
"apn": "myapnprov.es"
},
"provType": "REFERENCE",
"date": "2017-12-01T08:52:37.624Z",
"at": "2017-12-01T08:52:37.624Z"
}
}
}
],
"provision.device.communicationModules[].subscription.identifier": [
{
"_index": {
"path": "provision.device.communicationModules[].identifier",
"value": {
"_current": {
"value": "commsMod_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
},
"_value": {
"_current": {
"value": "subscription_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.626Z",
"at": "2017-12-01T08:52:37.626Z"
}
}
}
],
"provision.device.identifier": {
"_value": {
"_current": {
"value": "device_battery_id",
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.636Z",
"at": "2017-12-01T08:52:37.636Z"
}
}
},
"provision.device.location": {
"_value": {
"_current": {
"value": {
"position": {
"type": "Point",
"coordinates": [
-3.7028,
40.41675
]
},
"postal": "28013"
},
"provType": "MONITORING",
"date": "2017-12-01T08:52:37.64Z",
"at": "2017-12-01T08:52:37.64Z"
}
}
},
"resourceType": {
"_value": {
"_current": {
"value": "entity.device",
"provType": "IDENTIFIER",
"date": "2017-12-01T08:52:37.643Z",
"at": "2017-12-01T08:52:37.643Z"
}
}
},
"device.communicationModules[].identifier": [
{
"_index": {
"path": "device.communicationModules[].identifier",
"value": {
"_current": {
"value": "commsMod_battery_id",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
},
"_value": {
"_current": {
"value": "commsMod_battery_id",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
}
],
"device.communicationModules[].subscription.address": [
{
"_index": {
"path": "device.communicationModules[].identifier",
"value": {
"_current": {
"value": "commsMod_battery_id",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
},
"_value": {
"_current": {
"value": {
"type": "IPV4",
"value": "99.1.1.71",
"apn": "myapn.es"
},
"date": "2017-12-01T08:52:37.624Z",
"at": "2017-12-01T08:52:37.624Z",
"source": "DEVICE_OPENGATE_HTTP",
"sourceInfo": "IoT Data Message Received"
}
}
}
],
"device.communicationModules[].subscription.identifier": [
{
"_index": {
"path": "device.communicationModules[].identifier",
"value": {
"_current": {
"value": "commsMod_battery_id",
"date": "2017-12-01T08:52:37.577Z",
"at": "2017-12-01T08:52:37.577Z"
}
}
},
"_value": {
"_current": {
"value": "subscription_battery_id",
"date": "2017-12-01T08:52:37.626Z",
"at": "2017-12-01T08:52:37.626Z",
"source": "DEVICE_OPENGATE_HTTP",
"sourceInfo": "IoT Data Message Received"
}
}
}
],
"device.identifier": {
"_value": {
"_current": {
"value": "device_battery_id",
"date": "2017-12-01T08:52:37.636Z",
"at": "2017-12-01T08:52:37.636Z",
"source": "DEVICE_OPENGATE_HTTP",
"sourceInfo": "IoT Data Message Received"
}
}
},
"device.temperature.value": {
"_value": {
"_current": {
"value": 25.3,
"date": "2017-12-01T08:52:37.64Z",
"at": "2017-12-01T08:52:37.64Z",
"source": "DEVICE_OPENGATE_HTTP",
"sourceInfo": "IoT Data Message Received"
}
}
}
}
contextParams some examples:
REQUEST Connector function:
{
"apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
"sessionIp": "127.0.0.1",
}
COLLECTION or RESPONSE Connector function for MQTT connector:
{
"apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
"topic": "some/topic"
}
COLLECTION or RESPONSE Connector function for HTTP Rest endpoints:
{
"apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
"path": "context/path",
"uri": "http://http_url/device_id/context/path",
"remoteIp": "remote_device_ip"
}
COLLECTION or RESPONSE Connector function for Websocket connection:
{
"apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
"path": "context/path",
"uri": "ws://ws_url/device/context/path"
}
COLLECTION or RESPONSE Connector function for SNMP connector:
{
"apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
"uri": "snmp://oid"
}
COLLECTION Connector function for DLMS connection:
{
"apiKey": "97c9ceae-c4ee-49ea-ad50-e499bb55ac63",
"obisCode": "0.1.2.3.3.5",
}
Connector function script output
Depending on the type of CF, the script must have different outputs (regardless of whether other calls are concatenated).
REQUEST CF
Althought return statement is not mandatory,
No output is mandatory, so return null; can be used or directly not define any return statement. In this case the operation will not be finished until response event is processed.
Althought the return statement is not mandatory, it is possible to return response object. If returned it will be processed and the operation can be finalized directly.
RESPONSE CF
In this case, OpenGate Standard Response object must be returned. If nothing or null is returned, then no operation update will be done.
response object functions can be used to complete full data.
COLLECTION CF
In this case, OpenGate Standard Iot Data Collection object must be returned. If nothing or null is returned, then no collection will be done.
collection object functions can be used to complete full data.
Connector function execution concatenation
In some cases, it is possible invoke the execution of other CFs once the current CF execution is finished.
These are allowed cases:
- From REQUEST CF:
- Invoke RESPONSE CF
- Invoke COLLECTION CF
- Invoke RESPONSE CF and COLLECTION CF
- From RESPONSE CF:
- Invoke COLLECTION CF
Other invocations will be ignored (for example, invoke RESPONSE CF from COLLECTION CF).
There are two help functions for this:
- cf.response
- cf.collection
JS API
httpRequest(request, payload) ⇒ Object
Executes specified request with specified payload.
Kind: global function
Returns: Object - JSON with response. It will have two fields: ‘statusCode’ with http result code and ‘body’ with response body content.
| Param | Type | Description |
|---|---|---|
| request | Object | Object with requests parameters: ‘method’, ‘uri’ and ‘headers’. - ‘method’: GET, POST, PUT, DELETE. - ‘uri’: request uri. - ‘headers’: json with http request headers. |
| payload | * | data to be sent. It can be null. |
webSocketMsg(payload, deviceId)
Send message to opened websocket
Kind: global function
| Param | Type | Description |
|---|---|---|
| payload | * | data to be published. It will be converted to string. |
| deviceId | String | Device identifier with the opened websocket |
entityValue(}, datastream, index) ⇒ *
Extract from entity specified datastream “value” field value.
Kind: global function
Returns: * - Specified datastream “value” field. It can be complex object. null if datastream does not exist.
| Param | Type | Description |
|---|---|---|
| } | Object | entity Object with flattened entity. |
| datastream | String | Datastream name, for example: ‘provision.device.identifier’. |
| index | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |
entitiesValue(entities, datastream, index) ⇒ *
Extract from the first entity of entities array specified datastream “value” field value.
Kind: global function
Returns: * - Specified datastream “value” field. It can be complex object. null if datastream does not exist.
| Param | Type | Description |
|---|---|---|
| entities | Array | Array of objects with flattened entity. |
| datastream | String | Datastream name, for example: ‘provision.device.identifier’. |
| index | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |
entityAt(entity, datastream, index) ⇒
Extract from entity specified datastream “at” field value.
Kind: global function
Returns: Specified datastream “at” field. It can be complex object. null if datastream does not exist.
| Param | Type | Description |
|---|---|---|
| entity | Object | entity Object with flattened entity. |
| datastream | String | Datastream name, for example: ‘provision.device.identifier’. |
| index | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |
entityDate(entity, datastream, index) ⇒
Extract from entity specified datastream “at” field value.
Kind: global function
Returns: Specified datastream “date” field. It can be complex object. null if datastream does not exist.
| Param | Type | Description |
|---|---|---|
| entity | Object | entity Object with flattened entity. |
| datastream | String | Datastream name, for example: ‘provision.device.identifier’. |
| index | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |
entitySource(entity, datastream, index) ⇒
Extract from entity specified datastream “source” field value.
Kind: global function
Returns: Specified datastream “date” field. It can be complex object. null if datastream does not exist.
| Param | Type | Description |
|---|---|---|
| entity | Object | entity Object with flattened entity. |
| datastream | String | Datastream name, for example: ‘provision.device.identifier’. |
| index | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |
entitySourceInfo(entity, datastream, index) ⇒
Extract from entity specified datastream “sourceInfo” field value.
Kind: global function
Returns: Specified datastream “date” field. It can be complex object. null if datastream does not exist.
| Param | Type | Description |
|---|---|---|
| entity | Object | entity Object with flattened entity. |
| datastream | String | Datastream name, for example: ‘provision.device.identifier’. |
| index | number | Array Index. If provided datastream is an array (i.e. comm module), element index must be specified. |
operationParameters(operationObj) ⇒ *
Extract from operationObj parameters field. This function could be used in REQUEST CFs, when the payload is Operation Request json.
Kind: global function
Returns: * - Returns parameters field. It can complex object. If operationObj is not correct Request object, null will be returned.
| Param | Type |
|---|---|
| operationObj | Object |
operationTimestamp(operationObj) ⇒ number
Extract from operationObj timestamp field. This function could be used in REQUEST CFs, when the payload is Operation Request json.
Kind: global function
Returns: number - Returns timestamp field. If operationObj is not correct Request object, null will be returned.
| Param | Type |
|---|---|
| operationObj | Object |
operationName(operationObj) ⇒ String
Extract from operationObj name field. This function could be used in REQUEST CFs, when the payload is Operation Request json.
Kind: global function
Returns: String - Returns name field. If operationObj is not correct Request object, null will be returned.
| Param | Type |
|---|---|
| operationObj | Object |
operationId(operationObj) ⇒ String
Extract from operationObj id field. This function could be used in REQUEST CFs, when the payload is Operation Request json.
Kind: global function
Returns: String - Returns id field. If operationObj is not correct Request object, null will be returned.
| Param | Type |
|---|---|
| operationObj | Object |
operationDeviceId(operationObj) ⇒ String
Extract from operationObj deviceId field. This function could be used in REQUEST CFs, when the payload is Operation Request json.
Kind: global function
Returns: String - Returns deviceId field. If operationObj is not correct Request object, null will be returned.
| Param | Type |
|---|---|
| operationObj | Object |
log(…msg)
Creates Info level logging messages. It concatenates msg parameters in the final string to logged.
Kind: global function
| Param | Type | Description |
|---|---|---|
| …msg | any | The function takes as parameters a list of elements to be concatenated to generate the string message to be printed. |
encryptString(originalValue, datastreamConfiguration, organizationName)
Encrypt an original string with the configuration established by the datastream of the organization
Kind: global function
Returns: The originalValue encrypted
| Param | Type | Description |
|---|---|---|
| originalValue | string | The value to encrypt. |
| datastreamConfiguration | string | The datastream of provision type, of the datamodel that define this value. This datastream has the configuration of encryption. |
| organizationName | string | The organization name to wich belongs to the datamodel. |
decryptString(encryptedValue, datastreamConfiguration, organizationName)
Decrypt an encrypted string with the configuration established by the datastream of the organization
Kind: global function
Returns: The encryptedValue decrypted
| Param | Type | Description |
|---|---|---|
| encryptedValue | string | The encrypted value to decrypt. |
| datastreamConfiguration | string | The datastream of provision type, of the datamodel that define this value. This datastream has the configuration of encryption. |
| organizationName | string | The organization name to wich belongs to the datamodel. |
getAddressTypeFromAddress(address)
Calculates the address type from a given address
Kind: global function
Returns: The address type
| Param | Type | Description |
|---|---|---|
| address | string | The address which the type will be calculated for. |
JS API - Dreprecated functions
responseCF(responseData, responseFunctionCriteria)
Used in Request connector functions to define a concatenated Response action.
Kind: global function
| Param | Type | Description |
|---|---|---|
| responseData | * | data to be used as payload in Response Connector Function. |
| responseFunctionCriteria | String | the criteria to be used to search response connector function. |
collectCF(collectionData, collectionFunctionCriteria)
Used in Request or Response connector functions to define a concatenated Collection action.
Kind: global function
| Param | Type | Description |
|---|---|---|
| collectionData | * | data to be used as payload in Collection Connector Function. |
| collectionFunctionCriteria | String | the criteria to be used to search collection connector function. |
publishOnTopic(payload, topic, deviceId)
Publish specified payload for specified topic and device.
Kind: global function
| Param | Type | Description |
|---|---|---|
| payload | * | Data to be published. It will be converted to string. |
| topic | String | topic uri. |
| deviceId | String | device id. |
ogCollection(datastreams, device, version) ⇒ Object
Creates OG collection main object.
Kind: global function
Returns: Object - Json with Opengate Data Collection object.
| Param | Type | Description |
|---|---|---|
| datastreams | Array | Array of datastreams objects. If not specified empty array will be set. |
| device | String | String with deviceId. If not defined null will be set. |
| version | String | String with version. If not specified, “1.0.0” value will be used. |
ogCollectionDs(datastreamId, feed, datapoints) ⇒ Object
Creates OG collection datastream object.
Kind: global function
Returns: Object - Json with Opengate Data Collection Datastream object.
| Param | Type | Description |
|---|---|---|
| datastreamId | String | String with datastreamid. If not provided null will be set. |
| feed | String | String with feed name. If not provided null will be set. |
| datapoints | Array | Array of datapoints objects. If not provided empty array will be set. |
ogCollectionDp(value, at, source, sourceInfo)
Creates OG collection datapoint object.
Kind: global function
| Param | Type | Description |
|---|---|---|
| value | * | collected value. If not provided null will be set. |
| at | number | Number with collection timestamp. If not provided null will be set. |
| source | String | String with source name. If not provided null will be set. |
| sourceInfo | String | String with source description. If not provided null will be set. |
addOgCollectionDp(datapoint, ogCollection, datastreamId, feed)
Adds datapoint to specified datastream in the collection object, if datastream does not exist, it creates the datastream.
Kind: global function
| Param | Type | Description |
|---|---|---|
| datapoint | Object | Datapoint object to be added. |
| ogCollection | Object | Opengate collection object with current collection data. |
| datastreamId | String | Datastream object identifier in collection object. If not exist, it will be created. |
| feed | String | feed name, only used if the datastream must be created. |
ogResponse(id, name, deviceId, resultCode, resultDescription, steps, timestamp, trustedBoot, version) ⇒ Object
Creates OG response object
Kind: global function
Returns: Object - OG response object
| Param | Type | Description |
|---|---|---|
| id | String | operation request id. If not provided null will be set. |
| name | String | launched operation name. If not provided null will be set. |
| deviceId | String | operation request device id. If not provided null will be set. |
| resultCode | String | operation result code. If not provided null will be set. |
| resultDescription | String | operation result code. If not provided null will be set. |
| steps | Array | If not defined, empty array will be defined. |
| timestamp | String | Operation response timestamp. If not provided current timestamp will be set. |
| trustedBoot | String | Trusted boot value. If not provided null will be set. |
| version | String | If not specified “8.0” will be set. |
ogStep(name, result, description, stepResponseList) ⇒
Creates OG step object used in opengate response object.
Kind: global function
Returns: OG step object
| Param | Type | Description |
|---|---|---|
| name | String | step name. If not provided null will be set. |
| result | String | step result. If not provided null will be set. |
| description | String | description string. If not provided, null will be assigned. |
| stepResponseList | String | array of stepResponse objects. If not provided, empty array will be assigned. |
ogStepResponse(name, value) ⇒
Creates OG step response object, used in step object.
Kind: global function
Returns: OG step response object
| Param | Type | Description |
|---|---|---|
| name | * | step name. If not provided null will be set. |
| value | Object | object with value. If not provided empty object will be assigned. |