API Reference

Allen-Bradley connector programming specifications

FairCom provides specific API actions to configure the EtherNet/IP connector. Be sure to enable the Allen-Bradley service before requesting data from an Allen-Bradley service.

Note A connector is a bridge between a device/software and an integration table. 

 

Request examples

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

Minimal

{
   "action":"createInput",
   "params":{
      "inputName":"abTest1",
      "serviceName":"ab",
      "thingName": "PLC 74",
      "tableName":"abTable1",
      "settings":{
         "dataCollectionIntervalMilliseconds":5000,
         "dataReadingTimeoutMilliseconds":5000,
         "plcAddress":"192.142.100.22",
         "plcType":"controllogix",
         "propertyMapList":[
            {
               "eipTagPath":"1,0",
               "eipTagName":"temperature",
               "eipTagType":"float32",
               "propertyPath":"temperature"
            }
         ]
      }
   },
   "requestId":"00000004",
   "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
   "api":"hub",
   "action":"createInput",
   "params":{
      "inputName":"abTest1",
      "serviceName":"ab",
      "thingName": "PLC 74",
      "dataPersistenceStrategy": "onChange", 
      "dataCollectionIntervalMilliseconds": 500,
      "dataReadingTimeoutMilliseconds": 1000,
      "dataWritingTimeoutMilliseconds": 1000,
      "immediatelyCollectDataOnStart": true,
      "dataCollectionBufferCount": 2,
      "tableName":"abTable1",
      "settings":{
         "plcAddress":"192.142.100.22",
         "plcType":"controllogix",
         "propertyMapList":[
            {
               "eipTagPath":"1,0",
               "eipTagName":"scada",
               "eipTagElementCount":10,
               "eipTagType":"int32",
               "propertyPath":"scada"  //Deprecated
            },
            {
               "eipTagPath":"1,0",
               "eipTagName":"temperature",
               "eipTagType":"float32",
               "tagName":"temperature"
            },
            {
               "eipTagPath":"1,0",
               "eipTagName":"message",
               "eipTagType":"string",
               "eipTagSize":20,
               "tagId": 18
            }
         ]
      }
   },
   "requestId":"00000004",
   "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

A response to a request is "0" when successful. A non-zero value response indicates an error occurred.

Collected JSON data

{
  "create_ts":"2023-09-19T20:37:12.678Z",
  "scada0":10,
  "scada1":20,
  "scada2":30,
  "scada3":40,
  "scada4":50,
  "scada5":60,
  "scada6":70,
  "scada7":80,
  "scada8":90,
  "scada9":100,
  "temperature":86.230003356933594,
  "message":"AB rocks            "
}

The Maximal request configures the Allen-Bradley connector to collect data from a ControlLogix PLC at address 192.142.100.22 every 5 seconds. It collects data from 3 tag addresses named "scada", "temperature", and "message". If it cannot read the tags within 1 second, it returns a timeout error. 

In this example, the connector retrieved ten 32-bit integers from the PLC starting at the "scada" tag address and added each integer to the generated JSON as a separate property named "scadaN" where N is the zero-based array index number. In the PLC, the "scada" tag had an array containing the following ten integer values: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]. The generated JSON included the corresponding ten properties: "scada0":10, "scada1":20, "scada2":30, "scada3":40, "scada4":50, "scada5":60, "scada6":70, "scada7":80, "scada8":90, "scada9":100.

The connector also retrieved one Floating point number from the PLC starting at the tag address "temperature" and added it to the generated JSON as a property named "temperature". Because the connector retrieved only one value, it did not append an index number to the end of the "temperature" property name. In the PLC, the "temperature" tag was a floating-point number 86.230003356933594. The generated JSON included the corresponding property "temperature":86.230003356933594.

The connector then retrieved a 20-byte string from the PLC starting at the tag address "message" and added it to the generated JSON as a property named "message". Because the connector retrieved only one value, it did not append an index number to the end of the "message" property name. In the PLC, the "message" tag was the 20-byte string "AB rocks            ". The generated JSON included the corresponding property "message":"AB rocks            ".

The connector receives the collected JSON data in the source_payload field of a JSON document, and inserts it in a record in the "abTable1" table.

"eipTagName" options

If you want to read an array starting in the middle, add the first position inside square brackets as part of the tag name.

For example, the following request values would generate the following retrieved data.

Request values

{
  "eipTagPath":"1,0",
  "eipTagName":"scada[4]",
  "eipTagElementCount":3,
  "eipTagType":"int32",
  "propertyPath":"scada"
}

 

Retrieved data

{
  "create_ts":"2023-09-26T19:01:39.714Z",
  "scada0":50,
  "scada1":60,
  "scada2":70
}

In this example, the "scada" tag represents an array in the PLC containing the following ten integer values: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]. The tag array is zero-based.

The first element is [0] so "eipTagName": "scada[4]" collects data at the 5th item in the array, which has the value of 50. Specifying "eipTagElementCount": 3 collects 3 items from the array.

The connector generates JSON containing the properties "scada0":50, "scada1":60, and "scada2":70. These properties correspond to the properties named "scada4":50, "scada5":60, and "scada6":70 in the results from the Maximal example.

 

 
 

Success

{
    "result": {},
    "requestId": "00000007",
    "errorCode": 0,
    "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

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.

 Optional with default of 1 integer 1 to 65535

dataCollectionIntervalMilliseconds

The "dataCollectionIntervalMilliseconds" property schedules the connector to collect data periodically using the specified number of milliseconds. 

 Optional with default of 10000 (10 seconds). integer 0 and negative values are invalid.

dataPersistenceStrategy

The "dataPersistenceStrategy" property controls when a connector writes collected data to a record in the input table specified by "tableName". 

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

 Optional with default of "onSchedule" string

"onSchedule"

"onChange"

dataReadingTimeoutMilliseconds

 The "dataReadingTimeoutMilliseconds" property specifies the timeout in milliseconds while connecting and reading data from the PLC. Optional with default of 1000 int32 0 and negative values are invalid.

dataWritingTimeoutMilliseconds

 The "dataWritingTimeoutMilliseconds" property specifies the timeout in milliseconds while connecting and writing data to the PLC.  Optional with default of 1000 int32 0 and negative values are invalid.

description

 The "description" property assigns a description to a connector. Optional with default of "" string 1 to 512 bytes

enabled

 The "enabled" property turns on or off an input or output connector. Thus, it pauses or starts data collection or delivery. Optional with default of true Boolean

true

false

enabledFilter

 The "enabledFilter" property returns input connections that are enabled or not. Omit or set to null to match all connections. Optional with default of null Boolean

true

false

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.
 Optional with default of false Boolean

true

false

inputName

The "inputName" property specifies the unique name of an input. A FairCom generated name follows the pattern "Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>".

"params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus"
}

Required - No default value

 string 1 to 100 bytes

purpose

 The "purpose" property specifies the purpose of the thing. You can use it for fast partial lookups and filtering.  Optional with default of "unknown"  string

1 to 64 bytes

Values are managed in the Label API with the group "faircom/edge/purpose".

runningFilter

 The "runningFilter" property returns input connections that are running or not. Omit or set to null to match all connections. Optional with default of null Boolean

true

false

serviceName

The "serviceName" property contains the name of a FairCom input or output service. 

See the "params" topic of each specific service for the requirements of this property.

The following services are available as of the V5 release:
  • "MODBUS"
  • "SIEMENSUDT2JSON"
  • "OPCUA"

Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration.

MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.

 Required - No default value string 1 to 64 bytes

settings

The "settings" property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference "params" property of each connector for details of the "settings" property for that connector.

 Optional with default of {} object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

settings

.plcAddress

 The "plcAddress" property specifies the IP address or hostname and optional port from the PLC, in the format IPaddress:Port, with Port being optional.  Required - No default value string

Examples:

172.16.0.1

172.16.0.1:4401

settings

.plcType

The "plcType" property specifies the type of the PLC. 

  • "controllogix" - The tag is in a Control Logix-class PLC. Includes Logix, CompactLogix, Contrologix.
  • "plc5" - The tag is in a PLC/5 PLC.
  • "slc500" - The tag is in a SLC 500 PLC.
  • "logixpccc" - The tag is in a Control Logix-class PLC using the PLC/5 protocol.
  • "micro800" - The tag is in a Micro800-class PLC.
  • "micrologix" - The tag is in a Micrologix PLC.
  • "omron-njnx" - The tag is in an Omron NJ/NX PLC.
 Required - No default value string

"controllogix"

"plc5"

"slc500"

"logixpccc"

"micro800"

"micrologix"

"omron-njnx"

settings

.propertyMapList

 The "propertyMapList" property specifies which data the connector requests and where to put it in the generated JSON. Required - No default value array of objects

Zero or more objects containing zero or more of the following properties:

"eipTagElementCount"

"eipTagName"

"eipTagPath"

"eipTagSize"

"eipTagType"

"propertyPath"

settings

.propertyMapList

.eipTagElementCount

 The "eipTagElementCount" property specifies the number of elements in the tag. All tags are treated as arrays. Tags that are not arrays are considered to have a length of one element. Optional with default of 1 int32 0 and negative values are invalid.

settings

.propertyMapList

.eipTagName

The "eipTagName" property specifies the full name of a tag, such as MyTag[10,42] for CIP-based PLCs.

For CIP-based PLCs, use the format Program:<program name>.<tag>.

<program name> is the program name in which the tag is created
<tag> is the name in the program.
Examples: Program:MyProgram.MyTag accesses the tag MyTag in the program MyProgram.

PCCC-based PLC examples include N7:4, ST18:26, L20:2, MG14:6.en, B3:4/2, and so forth. Many common field name abbreviations are supported.

 Required - No default value string No limit

settings

.propertyMapList

.eipTagPath

The "eipTagPath" property specifies additional connection information with the format "p,s"

p is the communication Port Type

1 for Backplane
2 for Control Net/Ethernet, DH+ Channel A, or DH+ Channel B
3 for Serial
s is the slot number where the PLC is installed, such as 0, 1, 2.

 Optional with default of "1,0" string String with the format "p,s"

settings

.propertyMapList

.eipTagSize

 The "eipTagSize" property specifies the binary format of the PLC data represented by the tag. Required - No default value string "bit"
"int8"
"uint8"
"int16"
"uint16"
"int32"
"uint32"
"int64"
"uint64"
"float32"
"float64"
"byte"
"string"

settings

.propertyMapList

.eipTagType

The "eipTagType" property specifies the buffer size in bytes to handle tag data.

If not specified, the buffer size is defined based on the tagType. For example, 1 for int8 and 4 for int64.

For string tagType, the default value is 0 which will set the buffer to the maximum string size for the device.

Let the server define this property. and set it yourself only when necessary.

 Optional - depending on the dataType value Integer 0, 1, 2, 4, or 8

settings

.propertyMapList

.propertyPath

 The "propertyPath" property specifies the JSON path in the JSON document where the connector puts the data it collects. It is mutually exclusive with the "tagName" and "tagId" properties. Required - No default value string JSON path

settings

propertyMapList

.tagId

 The "tagId" property associates a tag with a value being collected by a connector. It is mutually exclusive with the "tagName" and "propertyPath" properties. See tagId for more details. Conditional - No default value integer If present, it must contain the ID of an existing tag, which is an integer from 0 to 9223372036854770000.
Note FairCom recommends using this property instead of "propertyPath".

settings

propertyMapList

.tagName

 The "tagName" property associates a tag with a value being collected by a connector. It is mutually exclusive with the "tagId" and "propertyPath" properties. See tagName for more details.  Conditional - No default value string

If present, it must contain the name of an existing tag. 

Note FairCom recommends using this property instead of "propertyPath".

status

 The "status" property assigns an active or inactive status to a thing. An inactive status is like a soft delete.  Optional with default of "active" string enum

"active"

"inactive"

tableName

The "tableName" property contains the unique, user-defined name of a table.

The table name must start with an upper or lowercase letter, must not contain special characters other than underscore "_", and can include a mix of upper-lower case characters, but are treated as case-insensitive.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

thingId

 The "thingId" property associates a connector with a device or software application. It is mutually exclusive with the "thingName" property. See thingId for more details.  Optional with default of null integer If present, it must contain the ID of an existing thing, which is an integer form 0 to 9223372036854770000.

thingName

 The "thingName" property associates a connector with a device or software application. It is mutually exclusive with the "thingId" property. See thingName for more details. Optional with default of null string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

data

.enabled


The "enabled" property is true when a connector is allowed to connect to a device. It is false when a connector will not attempt to connect to the device.

 

 boolean true
false

data

.running

 The "running" property is true when an input connector is collecting data or an output connector is delivering data; otherwise, it is false. A disabled connector will never be running. An enabled connector may or may not be running. Boolean

true

false

data

.settings

The "settings" property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference "params" property of each connector for details of the "settings" property for that connector.

 object

See these pages for connector specific properties:

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

data

settings

.propertyMapList

 The "propertyMapList" property specifies which data the connector requests and where to put it in the generated JSON. array of objects

See these pages for connector specific properties:

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

data

settings

propertyMapList

.propertyPath

 The "propertyPath" property specifies the JSON path in the JSON document where the connector puts the data it collects. It is mutually exclusive with the "tagName" and "tagId" properties. string JSON path

data

settings

propertyMapList

.tagId

 The "tagId" property associates a tag with a value being collected by a connector. It is mutually exclusive with the "tagName" and "propertyPath" properties. See tagId for more details. integer If present, it must contain the ID of an existing tag, which is an integer from 0 to 9223372036854770000.
Note FairCom recommends using this property instead of "propertyPath".

data

settings

propertyMapList

.tagName

 The "tagName" property associates a tag with a value being collected by a connector. It is mutually exclusive with the "tagId" and "propertyPath" properties. See tagName for more details.  string

If present, it must contain the name of an existing tag. 

Note FairCom recommends using this property instead of "propertyPath".

data

.stopCode

 The "stopCode" property is 0 when the connector is successfully connected to its device or software; otherwise, it is non-zero. integer -2147483648 to 2147483647

data

.stopReason

 The "stopReason" property is "" when the input connector is collecting data; otherwise, it is a non-empty string. string 0 to 256 bytes

data

.thingId

 The "thingId" property associates a connector with a device or software application. It is mutually exclusive with the "thingName" property. See thingId for more details.  integer If present, it must contain the ID of an existing thing, which is an integer form 0 to 9223372036854770000.

data

.thingName

 The "thingName" property associates a connector with a device or software application. It is mutually exclusive with the "thingId" property. See thingName for more details. string 1 to 64 bytes

 

documentation interface

Was this article helpful?

Give feedback about this article

Related Articles