alterInput

JSON hub "alterInput" action modifies an existing FairCom Edge input

The "alterInput" action alters an existing input connector in FairCom Edge to collect tags automatically from a device or software system. Before you can alter an input, you must use "createInput" to create it.

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.

  • "alterInput" modifies how an input service collects data from a data source, transforms it, and inserts it into an integration table.
    • For example, an input can configure the OPC UA service to collect data from an external source and write that data to an integration table in FairCom Edge.
  • You can do the following:
    • You can change the settings of an input.
    • You can change the transforms applied to the data when it is inserted into the integration table.
    • You can change metadata about the input to make it easier to locate.
  • You cannot do the following:
    • You cannot change the mapping between the service and the integration table. To do this, you need to create a new input and delete the old one.
    • You cannot remap a connector service to a different integration table because this mapping is fundamental to the nature of the input. In the future, we may enhance this action to be able to remap the connector service to a different integration table, or we may provide a special action just for this purpose.
      • The action, "alterInput", is the only way to configure an existing input. If the specified value of "inputName" does not find an existing input, this action returns an error. To create an input, use the "createInput" action.

 

Request examples

Minimal

{
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "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 request

{
  "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 request

{
  "api": "hub",
  "action": "createInput",
  "params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus",
    "dataPersistenceStrategy": "onChange", 
    "dataCollectionIntervalMilliseconds": 5000,
    "immediatelyCollectDataOnStart": true,
    "dataCollectionBufferCount": 2,
    "settings": {
      "modbusProtocol": "TCP",
      "modbusServer": "127.0.0.1",
      "modbusServerPort": 502,
      "modbusDataAddressType": "zeroBased",
      "propertyMapList": [
        {
          "propertyPath": "temperature",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "holdingregister",
          "modbusUnitId": 5,
          "modbusDataLen": 1,
          "modbusDataType": "int16SignedAB"
        },
        {
          "propertyPath": "volume",
          "modbusDataAddress": 1299,
          "modbusDataAccess": "holdingregister",
          "modbusUnitId": 5,
          "modbusDataLen": 2,
          "modbusDataType": "ieeeFloat32ABCD"
        },
        {
          "propertyPath": "status",
          "modbusDataAddress": 1199,
          "modbusDataAccess": "coil",
          "modbusUnitId": 5,
          "modbusDataLen": 1,
          "modbusDataType": "int8Signed"
        }
      ]
    },
    "ownerName": "admin",
    "tableName": "modbusTableTCP",
    "metadata": {}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Turn on data collection

The following example turns on data collection for the specified input.

{
 "action": "alterInput",
 "params": {
   "inputName": "INPUT: PLC 74 & Modbus",
   "serviceName": "modbus",
   "enabled": true
 },
 "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 on data collection

{
 "result": {
   "data": [
     {
       "inputName": "INPUT: PLC 74 & Modbus",
       "serviceName": "modbus",
       "thingName": "PLC 74",
       "tableName": "temperature",
       "enabled": true,
       "running": true,
       "stopCode": 0,
       "stopReason": "",
       "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": ""
  }
 
 

 

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"

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

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

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

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.

Connector-specific "settings"

 Optional with default of {} object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

tableName

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

See table name in System limits for the table naming requirements and limitations.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value 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

.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

.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

.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

.inputName

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

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

.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

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

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.

See table name in System limits for the table naming requirements and limitations.

 string 1 to 64 bytes

data

.thingName

 The "thingName" property specifies the unique name of a thing.   string 1 to 64 bytes

 

Was this article helpful?

Give feedback about this article

Related Articles