createInput

JSON hub "createInput" action creates a new FairCom Edge input

The "createInput" action creates a new input. It configures a service to collect tags from a data source and insert those tags into an integration table.

Note A tag is a piece of named data with an associated value. For example, the tag temperature 70 includes both the named data temperature and the value 70. In JSON, a tag is a JSON property, such as "temperature": 70. In a SQL table, a tag is a data field, such as a field named temperature with a value of 70.

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

  • An input configures a connector to collect data tags periodically from a device and store them in an integration table. For example, an input can configure the OPC UA connector to collect and store data from an OPC UA device.
  • An input is a mapping from a service to an integration table.
    • The action "createInput" is the only way to create this mapping. If the mapping already exists, this action returns an error. To modify an existing input, use the "alterInput" action.
  • Each input typically configures a connector to store data in its own dedicated integration table.
  • You may create multiple inputs that configure a variety of connectors to collect data from different devices for storage in the same integration table. This is useful when different devices collect the same type of data, such as temperature, and you want all temperature data to be stored in one table.
  • When you want the same collected data to exist in multiple integration tables, to publish the data to multiple MQTT topics for example, you can create a "jsonToDifferentTableFields" transform to replicate data from one integration table to another.
  • If the specified integration table does not exist when an input is created, FairCom Edge creates it.
  • A connector inserts records into an integration table, which is a historical log of data collection events. If your account has permissions, you may also update or delete collected records.
  • A connector typically converts the data tags it collects into JSON and writes them to the "source_payload" field of a newly inserted record.
  • Transforms can take data from the "source_payload" field (or from other fields in the table), transform it, and place the results in other fields, such as user-defined fields.

 

Request examples

The following examples are for the Modbus connector. For examples of other connectors, visit the Allen-Bradley, OPC UA, or Siemens S7 API references.

Minimal

{
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "thingName": "PLC 74",
    "settings": {
      "modbusProtocol": "TCP",
      "modbusServer": "127.0.0.1",
      "modbusServerPort": 502,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAccess": "holdingregister",
          "modbusDataAddress": 1199,
          "modbusUnitId": 5,
          "modbusDataLen": 1
        }
      ]
    },
    "tableName": "modbusTableTCP"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

RTU

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "modbusRTU",
    "serviceName": "modbus",
    "dataPersistenceStrategy": "onChange", 
    "dataCollectionIntervalMilliseconds": 5000,
    "immediatelyCollectDataOnStart": true,
    "dataCollectionBufferCount": 2,
    "settings": {
      "modbusProtocol": "RTU",
      "modbusSerialPort": "COM2",
      "modbusBaudRate": 19200,
      "modbusParity": "None",
      "modbusDataBits": 8,
      "modbusStopBits": 2,
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAccess": "holdingregister",
          "modbusDataAddress": 1199,
          "modbusUnitId": 5,
          "modbusDataLen": 1
        }
      ]
    },
    "tableName": "modbusTableRTU"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
    "api": "hub",
    "action": "createInput",
    "params": {
        "inputName": "INPUT: PLC 74 & Modbus",
        "serviceName": "modbus",
        "thingName": "PLC 74",
        "databaseName": "faircom",
        "ownerName": "admin",
        "tableName": "temperature",
        "status": "userError",
        "stopCode": 16384,
        "stopReason": "Putting device in an uncertain error state while verifying data collection.",
        "purpose": "Track Celsius Temperatures from devices",
        "description": "My input connector's description",
        "labels": ["temperature", "celsius"],
        "dataPersistenceStrategy": "onChange",
        "immediatelyCollectDataOnStart": true,
        "dataCollectionBufferCount": 2,
        "dataCollectionIntervalMilliseconds": 15000,
        "settings": {
            "modbusProtocol": "TCP",
            "modbusServer": "127.0.0.1",
            "modbusServerPort": 502,
            "propertyMapList": [
                {
                    "propertyPath": "status",  //Deprecated
                    "modbusDataAddress": 1000,
                    "modbusDataAccess": "inputRegister",
                    "modbusUnitId": 5,
                    "modbusDataLen": 1
                },
                {
                    "tagName": "device1_modbus_stamper_temperature",
                    "modbusDataAddress": 2000,
                    "modbusDataAccess": "inputRegister",
                    "modbusUnitId": 5,
                    "modbusByteOrder": "ABCD",
                    "modbusDataLen": 2
                },
                {
                    "tagId": 18,
                    "modbusDataAddress": 3000,
                    "modbusDataAccess": "inputRegister",
                    "modbusUnitId": 5,
                    "modbusDataLen": 2
                }
            ]
        },
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 4,
        "retentionUnit": "week",
        "metadata": {}
    },
    "requestId": "00000007",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Conditional Data Persistence Code Example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   
   "dataCollectionIntervalMilliseconds": 1000,
   
   "dataPersistenceStrategy": "onChange",
   "onChangeScope": "saveSpecificTags", 
   "onChangeScopeTags": ["t1"],
   "onChangeTrigger": "saveWhenAnySpecifiedTagHasChanged",
   "onChangeTriggerTags": ["t1"],
   "maxUnsavedEvents": 360,
   
   "databaseName": "faircom",
   "ownerName": "admin",
   "tableName": "modbusTableTCP",
   "retentionPolicy": "autoPurge",
   "retentionPeriod": 30,
   "retentionUnit": "day",
   
   "dataCollectionBufferCount": 1,
   "immediatelyCollectDataOnStart": false,

   "metadata": {},
   
   "settings": {
     
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed",
         
         "normalLowerLimit": 10,
         "normalUpperLimit": 30,
         "deadbandLowerLimit": 17,
         "deadbandUpperLimit": 19,
         "significantMagnitude": 0.3
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Turn off data collection

The following example creates an input connector with data collection turned off, which is not the default behavior.

{
 "action": "createInput",
 "params": {
   "inputName": "INPUT: PLC 74 & Modbus",
   "serviceName": "modbus",
   "thingName": "PLC 74",
   "tableName": "temperature",
   "enabled": false,
   "dataCollectionIntervalMilliseconds": 1000,
   "settings": {
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     "propertyMapList": [
       {
         "propertyPath":"temperature",
         "tagName": "plc74_modbus_temperature",
         "modbusDataAddress": 2000,
         "modbusDataAccess": "inputRegister",
         "modbusUnitId": 5,
         "modbusDataLen": 1
       }
     ]
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

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

Success

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

Failure

{
  "result": {},
  "requestId": "00000011",
  "debugInfo": {
    "request": {
      "api": "hub",
      "action": "createInput",
      "params": {
        "inputName": "modbusTCP",
        "serviceName": "modbus",
        "settings": {
          "modbusProtocol": "TCP",
          "modbusServer": "127.0.0.1",
          "modbusServerPort": 502,
          "propertyMapList": [
            {
              "propertyPath": "temperature",
              "modbusDataAddress": "holdingregister",
              "modbusDataAddress": 1199,
              "modbusUnitId": 5,
              "modbusDataLen": 1
            }
          ]
        },
        "tableName": "modbusTableTCP"
      },
      "requestId": "00000011",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    }
  },
  "errorCode": 12012,
  "errorMessage": "There is already an integration with name of [modbusTCP].",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Turn off data collection

See the API reference for each connector for more details on connector specific properties.

{
 "result": {
   "data": [
     {
       "inputName": "INPUT: PLC 74 & Modbus",
       "serviceName": "modbus",
       "thingName": "PLC 74",
       "tableName": "temperature",
       "enabled": false,
       "running": false,
       "stopCode": 14400,
       "stopReason": "Connector is disabled. Enable it to continue.",
       "dataCollectionIntervalMilliseconds": 1000,
       "settings": {
         "modbusProtocol": "TCP",
         "modbusServer": "127.0.0.1",
         "modbusServerPort": 502,
         "propertyMapList": [
           {
             "tagName": "plc74_modbus_temperature",
             "sourceFieldName": "temperature_celsius",
             "sourcePayloadPath": "celsius",
             "propertyPath": "celsius",
             "modbusDataAddress": 2000,
             "modbusDataAccess": "inputRegister",
             "modbusUnitId": 5,
             "modbusDataLen": 1
           }
         ]
       },
       "databaseName": "ctreeSQL",
       "ownerName": "admin",
       "tableName": "modbustabletcp",
       "metadata": {
       },
       "retentionPolicy": "autoPurge",
       "retentionPeriod": 30,
       "retentionUnit": "day"
     }
   ]
 },
 "requestId": "00000027",
 "errorCode": 0,
 "errorMessage": ""
}
 
 

Maximal

{
  "result": {
    "data": [
      {
        "id": 18,
        "inputName": "modbusTCP",
        "serviceName": "modbus",
        "databaseName": "faircom",
        "ownerName": "admin",
        "tableName": "modbustabletcp",


        "status": "userError",
        "stopCode": 16384,
        "stopReason": "Putting device in an uncertain error state while verifying data collection.",


        "purpose": "Track Celsius Temperatures from devices",
        "description": "My input connector's description",
        "labels": ["temperature", "celsius"],
        "metadata": { "myProperty": "myValue" },
        
        "createdTimestamp": "2025-08-28T10:47:13.041",
        "updatedTimestamp": "2025-08-28T10:47:13.041",
        "inactiveTimestamp": null,
        "lastCollectedTimestamp": null,
        "lastConnectedTimestamp": null,
        "lastDisconnectedTimestamp": null,
        
        "dataPersistenceStrategy": "onChange", 
        "dataCollectionIntervalMilliseconds": 5000,
        "immediatelyCollectDataOnStart": true,
        "dataCollectionBufferCount": 2,    
    
        "settings": {
          "modbusProtocol": "TCP",
          "modbusServer": "127.0.0.1",
          "modbusServerPort": 502,
          "propertyMapList": [
            {
              "propertyPath": "temperature",
              "modbusDataAccess": "holdingregister",
              "modbusDataAddress": 1199,
              "modbusUnitId": 5,
              "modbusDataLen": 1
            }
          ]
        },
        
        "fields": [],
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 4,
        "retentionUnit": "week",
        "disableTransformSteps": false,
        "logTransformOverwrites": false
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties 

Request properties ("params")

Property Description Default Type Limits (inclusive)

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. Your session's account must have the appropriate privileges to access the code package.

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

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"

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

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

labels

 The "labels" property assigns zero or more labels to a connector. You can use it to do lookups and filtering. You can display a list of existing labels, add new ones, rename them, and deprecate them.
When you use the "alterInput" or "alterOutput" actions, omit the "labels" property to leave existing labels unchanged, or specify a complete set of new labels. These actions do not allow you to change one label at a time.
You can use the "labelsFilter" property to lookup and filter connectors. 
The input and output connector actions implement the "labels" property using the Label API. 
The API stores and manages labels in the label group, "faircom/edge/labels", which allows labels to be used through FairCom Edge's APIs.
An API client can retrieve a list of all lifecycle labels by using the "listLabels" action with "partialGroupFilter": "faircom/edge/labels".
An API client should use the connector API's "labels" property to manage the labels assigned to a connector. It should not use the Label API to rename, link, or unlink connectors.		 Optional with default of [] string 1 to 64 bytes

maxUnsavedEvents

The "maxUnsavedEvents" property requires a connector to periodically write all collected tags to the integration table – even if their values have not changed. It specifies the maximum number of collection events before the connector unconditionally saves collected tags. 
Lower values are appropriate for infrequently collected tags and higher values for frequently collected tags. The default value is "disabled", which disables the feature. 
This property ensures the connector periodically saves infrequently changing data values. Because "onChange" rules can prevent collected data from being saved, the "maxUnsavedEvents" property is particularly important when you want to ensure values are periodically saved. 
The following chart shows a deadband covering the entire range of values, which normally prevents values from being saved. The Maximum Unsaved Events rule overrides the deadband (and all other rules) to ensure the connector saves values periodically. Because "maxUnsavedEvents" is set to 4, the connector ensures no more than 4 data collection events go unsaved. 

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The "dataCollectionIntervalMilliseconds" property specifies the number of milliseconds between each data collection cycle.
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • "normalLowerLimit"
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude"
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 Optional with default of "disabled" integer 1 to 4294967296

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

onChangeScope

 The "onChangeScope" property specifies which tags the connector saves to an integration table. For more details, see "onChangeScope". Optional with default of "saveAllTags" string enum

"saveAllTags"

"saveOnlyChangedTags"

"saveSpecificTags"

onChangeScopeTags

 The "onChangeScopeTags" property specifies which tags the connector should save to the integration table when a save event occurs. Each "propertyPath" value is the connector's unique identifier to a collected data item, which is commonly called a "tag". For more details, see "onChangeScopeTags". Required when the "onChangeScope" property is set to "saveSpecificTags". array of strings 1 or more strings

onChangeTrigger

 The "onChangeTrigger" property specifies when the connector saves collected tags to an integration table. For more details, see "onChangeTrigger". Optional with default of "saveWhenAnyTagHasChanged" string enum "saveWhenAnyTagHasChanged"
"saveWhenAllTagsHaveChanged"
"saveWhenAnySpecifiedTagHasChanged"
"saveWhenAllSpecifiedTagsHaveChanged"

onChangeTriggerTags

 The "onChangeTriggerTags" property specifies tags to work with the "onChangeTrigger" property to control when a connector saves collected data to an integration table. Each "propertyPath" value is the connector's unique identifier to a collected data item, which is commonly called a "tag". For more details, see "onChangeTriggerTags". Required when the "onChangeTrigger" property has one of the following values: "saveWhenAnySpecifiedTagHasChanged" or "saveWhenAllSpecifiedTagsHaveChanged". array of strings 1 or more strings

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

purpose

The "purpose" property specifies the purpose of the thing. You can use it for fast partial lookups and filtering. This API uses the Label API to manage purposes.

  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listInputs" or "listOutputs" actions with the "purposeFilter" property to ensure the label is unused.
 Optional with default of "unknown"  string

1 to 64 bytes

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

retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It refers to the unit of time specified by the "retentionUnit" property. For more details, see "retentionPeriod".

Optional with default of 30

 integer 1 to 100

retentionPolicy

The "retentionPolicy" property controls how messages are persisted. 

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

 

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.

Optional with default of "autoPurge"

 string

"autoPurge"

"neverPurge"

retentionUnit

The "retentionUnit" property specifies a unit of time that the server will use to purge expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

Optional with default of "day"

string

"minute"

"hour"

"day"

"week"

"month"

"year"

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

See these pages for connector specific properties:

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

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

See these pages for connector specific properties:

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

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. See "status" for more information.   Optional with default of "active" string enum

"active"

"connectorError"

"deviceError"

"userError"

"paused"

"inactive"

stopCode

The "stopCode" property contains the primary numeric code identifying why the connector is not collecting or delivering data. It is an integer number from 0 to 2147483647 inclusive. 0 means the connector is collecting or delivering data without error. The server sets this property when a connector encounters a problem that affects the quality of the data it collects or that prevents it from collecting or delivering data. The "createInput", "createOutput", "alterInput",  or "alterOutput" actions can also set this value when the "status" property is set to "userError".

  • It is non-zero when the connector is disconnected.
  • It is 14400 (PLUGIN_CONNECTOR_DISABLED) if "status" is "inactive".

Tip Users can use the API to set the state of a connector to "userError" and set the "stopCode" and "stopReason" properties to explain the cause of the user-specified error. 

FairCom uses the following list of OPC UA quality codes as the basis for stop codes between 0 and 65536. FairCom reserves stop codes from 1048576 to 16777215 for its own purposes. Users may use stop codes from 16777216 to 2147483647 for their own purposes.

 Conditional - No default value integer 0 to 2147483647

stopReason

The "stopReason" property contains the primary reason why the connector is not collecting or delivering data. It is "" when there is no data collection or delivery issues. The server sets this property when a connector encounters an error that prevents it from collecting or delivering data. The "createInput", "createOutput", "alterInput",  or "alterOutput" actions can also set this value when the "status" property is set to "userError".


Tip Users can use the API to set the state of a connector to "userError" and set the "stopCode" and "stopReason" properties to explain the cause of the user-specified error. 

FairCom uses the following list of OPC UA quality codes as a guide for its stop reasons and stop codes between 0 and 65536. FairCom reserves stop codes from 1048576 to 16777215 for its own purposes. Users may use stop codes from 16777216 to 2147483647 for their own purposes.

 Conditional - No default value string 0 to 64 bytes

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. 

 array of objects The action determines its contents.

data

.createdTimestamp

 The "createdTimestamp" property is the date and time when the connector was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

data

.databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

data

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

 integer 1 to 65535

data

.dataCollectionIntervalMilliseconds

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

 integer 0 and negative values are invalid.

data

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

 string

"onSchedule"

"onChange"

data

.description

 The "description" property assigns a description to a connector. string 1 to 512 bytes

data

.disableTransformSteps

The "disableTransformSteps" property determines if the transform steps are active without removing them from the integration table. When true, it prevents the server from running an integration table's transform steps on newly inserted records. When false, the transform steps run normally. It is useful to quickly stop a broken transform process.

 Boolelan

true

false

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

.fields

The "fields" property is an array of objects. Each object in the array defines a field by specifying its properties.

 

"fields": [
  {
    "autoValue": "none",
    "name": "name",
    "type": "varchar",
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false,
    "primaryKey": 0, 
    "autoValue": "none"
  }
]
 array

"autoTimestamp"

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

"primaryKey"

"autoValue"

data

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

true

false

data

.inactiveTimestamp

 The "inactiveTimestamp" property is the date and time when the connector was last made inactive. It is null when the connector is active. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

data

.inputName

 The "inputName" property specifies the unique name of an input. string 1 to 64 bytes

data

.labels

 The "labels" property assigns zero or more labels to a connector. You can use it to do lookups and filtering. You can display a list of existing labels, add new ones, rename them, and deprecate them.
When you use the "alterInput" or "alterOutput" actions, omit the "labels" property to leave existing labels unchanged, or specify a complete set of new labels. These actions do not allow you to change one label at a time.
You can use the "labelsFilter" property to lookup and filter connectors. 
The input and output connector actions implement the "labels" property using the Label API. 
The API stores and manages labels in the label group, "faircom/edge/labels", which allows labels to be used through FairCom Edge's APIs.
An API client can retrieve a list of all lifecycle labels by using the "listLabels" action with "partialGroupFilter": "faircom/edge/labels".
An API client should use the connector API's "labels" property to manage the labels assigned to a connector. It should not use the Label API to rename, link, or unlink connectors.		 string 1 to 64 bytes

data

.lastCollectedTimestamp

 The "lastCollectedTimestamp" property is optionally returned from the "describeInputs", "alterInput" actions. 
It returns the ISO 8601 date and time of the last data collected by the input connector. If no data has been collected, the value is null. The following string is an example of an ISO 8601 timestamp: "2025-08-28T10:47:13.041".		 ISO 8601 timestamp The ISO 8601 date and time of the last data collected by the input connector.

data

.lastConnectedTimestamp

 The "lastConnectedTimestamp" property is optionally returned from the "describeInputs", "alterInput", "describeOutputs", "alterOutput" actions. 
It returns the ISO 8601 date and time of the last time the connector was connected to its device. If it has never been connected, the value is null. The following string is an example of an ISO 8601 timestamp: "2025-08-28T10:47:13.041".		 ISO 8601 timestamp The last ISO 8601 date and time the input connector was connected to its device.

data

.lastDisconnectedTimestamp

 The "lastDisconnectedTimestamp" property is optionally returned from the "describeInputs", "alterInput", "describeOutputs", "alterOutput" actions. 
It returns the ISO 8601 date and time of the last time the connector disconnected from a device or software. If it has never disconnected, the value is null. The following string is an example of an ISO 8601 timestamp: "2025-08-28T10:47:13.041".		 ISO 8601 timestamp The last ISO 8601 date and time the input connector was disconnected from its device.

data

.logTransformOverwrites

The "logTransformOverwrites" property specifies whether or not the server will add a log entry to the log field when a transform step overwrites a field. When true and a record is inserted into the integration table, the server adds log entries to the log field when a transform step overwrites a field that already contains a value. When true, it protects fields, such as source_payload, from being overwritten accidentally. 

You typically set "logTransformOverwrites" to true when testing transform steps. Once they are working as expected, you can set it to false.

If multiple "recordPath" properties write to the same JSON properties in a "tableFieldsToJson" transform, the server will return an error because "recordPath" cannot overwrite. Multiple occurrences of the "recordPath" property may reference the same property as long as the property is in different fields/tables.

Additionally, non-JavaScript transform steps cannot overwrite protected fields or the source_payload field. The only exception is that a single "tableFieldsToJson" transform step may write to the source_payload field.

You may create transform steps to take the value of one JSON property and store it in multiple fields as long as no previous transform steps have already put values in these fields. Conversely, you may take the value of one field and store it in multiple JSON properties.

Tip Ensure JavaScript transform steps do not overwrite fields updated by other transform steps. 

Do not use the "tableFieldsToJson" transform method to overwrite the source_payload field; instead, use "tableFieldsToJson" to write to a different field and use the "configureTopic" action with the "outputPayloadField" property to configure the MQTT topic to deliver that field's value to subscribers. 

Ensure SQL, JSON DB, and other APIs set the value of the source_payload field and do not set field values that transform steps update.

 Boolean

true

false

data

.metadata

The "metadata" field allows a customer to add a JSON value to an object such as a label or thing. It is typically a JSON object, but may be any JSON value. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

data

.ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

data

.purpose

The "purpose" property specifies the purpose of the thing. You can use it for fast partial lookups and filtering. This API uses the Label API to manage purposes.

  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listInputs" or "listOutputs" actions with the "purposeFilter" property to ensure the label is unused.
 string

1 to 64 bytes

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

data

.retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It refers to the unit of time specified by the "retentionUnit" property. For more details, see "retentionPeriod".

 integer 1 to 100

data

.retentionPolicy

The "retentionPolicy" property controls how messages are persisted. 

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

 

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.
 string

"autoPurge"

"neverPurge"

data

.retentionUnit

The "retentionUnit" property specifies a unit of time that the server will use to purge expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

string

"minute"

"hour"

"day"

"week"

"month"

"year"

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

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

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

 string A service name between 1 and 64 bytes.

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

.status

 The "status" property assigns an active or inactive status to a thing. An inactive status is like a soft delete. See "status" for more information.   string enum

"active"

"connectorError"

"deviceError"

"userError"

"paused"

"inactive"

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

.tableName

The "tableName" property is a string containing the 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.

 string 1 to 64 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

data

.updatedTimestamp

 The "updatedTimestamp" property is the date and time when the connector was last updated. It is the same as the "createdTimestamp" property when the connector has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

 

Was this article helpful?

Give feedback about this article

Related Articles