OPC UA API reference

OPC UA connector programming specifications for FairCom Edge

FairCom provides special API actions for OPC UA connectors and transforms. The OPC UA service must be enabled in order to complete FairCom OPC UA actions.

Request examples

Note

The FairCom createInput JSON action is used to define the specifics of a connector device and the desired data.

Minimal example

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "opcDS1",
    "serviceName": "opcua",
    "settings": {
      "opcServerUrl": "opc.tcp://MyOPCDevice.com:4840",
      "propertyMapList": [
        {
          "propertyPath": "the_answer",
          "opcNamespace": 1,
          "opcNodeName": "the.answer"
        }
      ]
    },
    "tableName": "opcTable1"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal example

{
  "requestId": "19",
  "api": "hub",
  "apiVersion": "1.0",
  "action": "createInput",
  "params": {
    "inputName": "opcDS2",
    "serviceName": "opcua",
    "dataPersistenceStrategy": "onChange", 
    "dataCollectionIntervalMilliseconds": 5000,
    "immediatelyCollectDataOnStart": true,
    "dataCollectionBufferCount": 2,
    "settings": {
      "opcServerUrl": "opc.tcp://MyOPCDevice.com:4840",
      "opcServerUser": "MyUser",
      "opcServerPassword": "MyPassword",
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "opcNamespace": 1,
          "opcNodeName": "OPC-temperature-datasource"
        },
        {
          "propertyPath": "humidity",
          "opcNamespace": 1,
          "opcNodeName": "OPC-humidity-datasource"
        },
        {
          "propertyPath": "pressure",
          "opcNamespace": 1,
          "opcNodeName": "OPC-pressure-datasource"
        },
        {
          "propertyPath": "quality",
          "opcNamespace": 1,
          "opcNodeName": "OPC-quality-datasource"
        }
      ]
    },
    "ownerName": "admin",
    "tableName": "opcTable2",
    "databaseName": "faircom",
    "retentionPolicy": "autoPurge",
    "retentionPeriod": 30,
    "retentionUnit": "day",
    "metadata": {
    }
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

OPC UA connector programming specifications for FairCom Edge

API referenceJSON Hub APIOPC UAOPC UA connectorOPC UA API reference

`"params"`

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties. See System limits for a comprehensive look at property requirements and limitations.

Note

See createInput for "params" properties that are common to all connectors.

Table 1. OPC UA specific connector "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

dataCollectionBufferCount

(optional) specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table

1

integer

1 to 65535

dataCollectionIntervalMilliseconds

(optional) specifies the number of milliseconds to wait until reading PLC data again. For example, 15000 means 15 seconds

10000

integer

0 and negative values are invalid

dataPersistenceStrategy

(optional) specifies when the connector writes collected data to the specified table

"onSchedule"

string

"onSchedule"

"onChange"

immediatelyCollectDataOnStart

(optional) configures the input to collect data immediately when the server or connector starts. This occurs even if the data persistence strategy is to collect data changes

false

Boolean

true

false

serviceName

specifies which type of input to create

string

"opcua"

settings

specifies properties needed to configure the data source of the input

array of objects

settings

.opcServerUrl

specifies the IP or URL to your OPC UA device, including the port

string

settings

.opcServerUser

(optional) specifies the username for your OPC UA device

""

string

settings

.opcServerPassword

(optional) specifies the password for your OPC UA device

""

string

settings

.propertyMapList

specifies properties that represent the data being requested

array of objects

settings

.propertyMapList

.propertyPath

specifies the JSON path in the JSON document where the connector puts the data it collects. It is the tag name of the data being collected

string

JSON path

settings

.propertyMapList

.opcNamespace

specifies the OPC UA namespace that this variable exists in

int16

0 to 32767

settings

.propertyMapList

.opcNodeName

specifies the name of the OPC UA variable for this data

string

`"dataCollectionBufferCount"`

The "dataCollectionBufferCount" property specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table.

This option combines multiple data collection events and inserts them into the integration table as one MQTT message.

If this value is more than 1, the connector converts each set of collected data into a JSON object and adds the object to an array inside a JSON document. When the count is reached, the connector writes the JSON document to the source_payload field of a record it inserts into the integration table.

`"dataCollectionIntervalMilliseconds"`

The "dataCollectionIntervalMilliseconds" property schedules the connector to collect data periodically using the specified number of milliseconds. It defaults to 10000, which is ten seconds. It must be an integer number >= 1.

`"dataPersistenceStrategy"`

The "dataPersistenceStrategy" property controls when a connector writes collected data to a record in the input table specified by "tableName". It is an optional string enum property with two values: "onSchedule" and "onChange". The default value when the property is omitted or set to null is "onSchedule".

The "onSchedule" setting causes the connector to persist each collected value, which occurs on the schedule set by the "dataCollectionIntervalMilliseconds" property. This setting is useful for continuously collecting device data for trend analysis and machine learning.
The "onChange" setting causes the connector to collect data on the schedule set by the "dataCollectionIntervalMilliseconds" property, but it only persists data when it changes. This allows the connector to detect and store data changes as events, such as alerts and status updates. This setting greatly reduces data storage for infrequently changing telemetry, such as changes to a temperature sensor.
Note
The connector misses events when its data collection schedule is not frequent enough to see data changes. Thus, the "onChange" setting makes a polling protocol, such as Modbus, behave like a push protocol, but it is not a push protocol like MQTT.

`"immediatelyCollectDataOnStart"`

The "immediatelyCollectDataOnStart" property controls how a connector first collects data after being started.

When true, it immediately collects and stores data and thereafter collects data according to the strategy specified in "dataPersistenceStrategy". In other words, it ignores the "dataPersistenceStrategy" for the initial data collection event and unconditionally stores the first set of data it collects. This setting allows subscribers to receive an initial data collection message each time the server or connector starts, which is useful for systems that display live status information.
When false, which is the default, it collects data according to the strategy specified in "dataPersistenceStrategy". For example, when the "dataPersistenceStrategy" is "onChange", the connector collects data on a schedule and persists it only when the data changes - even after a restart.

`"propertyPath"`

The "propertyPath" property is a required string that specifies the JSON Path in the JSON document where the connector puts the data it collects. It is the tag name of the data being collected. You can use this property to take collected data and store it in any location in the JSON document generated by the connector. For example, the setting "propertyPath": "temperature" causes the server to take a value it collects, such as 20.1, and store it in a "temperature" property, such as { "temperature": 20.1 }.

`"settings"`

The "settings" property is an array of objects that contains properties needed to configure the data source of the input. It is required and has no default.

Property summary

Table 2. "settings" property summaries

Property	Description	Default	Type	Limits
opcServerUrl	contains the IP or URL to your OPC UA device, including the port	Required - No default value	string
opcServerUser	contains the username for your OPC UA device	""	string
opcServerPassword	contains the password for your OPC UA device	""	string
opcDataCollectionIntervalMilliseconds	specifies how often the data should be requested in milliseconds. Setting it to `0` causes the data to be requested only when data values change	Required - No default value	int32	`0` to `2147483647`
propertyMapList	contains properties that represent the data being requested	Required - No default value	array of objects

`"propertyMapList"`

The "propertyMapList" property is an array of objects that contains properties that represent the data being requested. It is required and has no default.

Property summary

Table 3. "propertyMapList" property summaries

Property	Description	Default	Type	Limits
propertyPath	specifies the JSON property that this data will be identified by	Required - No default value	string
opcNamespace	specifies the OPC UA namespace that this variable exists in	Required - No default value	int16	`0` to `32767`
opcNodeName	specifies the name of the OPC UA variable for this data	Required - No default value	string