testInput

The "testInput" action is useful for testing a newly created or altered input to ensure it returns expected values. You can call this action any time to get a device's most recent values. It takes an existing input, tests if it can connect to the device, optionally collects device information, optionally collects its current values, and returns this information. It does not write data to the input's integration table. You can create an inactive input, test it, and if you are satisfied with the results, you can activate it.

If "includeDeviceInformation":true, the action returns the "deviceInformation" property if it successfully connects to the device. This information describes the device, which helps a user confirm that they are connected to the correct device.

If "collectValues":true, the action returns the "collectedValues" property if it successfully connects to the device. If the input's "propertyMapList" property is omitted, the "collectedValues" property is an empty array [].

If the action cannot connect to the device, it returns the device disconnected error to indicate the device is disconnected.

 

Request examples

S7 and OPC

These protocols do not need additional information to return connection status and device information.

The Siemens S7 protocol uses the "rack" and "slot" properties to specify a specific child PLC module. These properties must be defined when creating the connector; thus, they are not required for the "testInput" and "testOutput" actions.

The OPC UA and MTConnect protocols do not specify child devices.

{
  "api": "hub",
  "action": "testInput",
  "params": {
    "inputName": "someInputName",
    "includeDeviceInformation": true,
    "collectValues":true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

EtherNet/IP

The EtherNet/IP protocol optionally allows a device to aggregate other EtherNet/IP devices. If this is the case, you can use the optional "eipTagPath" property to identify a specific device and return its connection status and device information.

{
  "api": "hub",
  "action": "testInput",
  "params": {
    "inputName": "someEtherNetIpInputName",
    "includeDeviceInformation": true,
    "collectValues":true,
    "eipTagPath":"1,0"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Modbus

The Modbus protocol optionally allows a device to aggregate other Modbus devices. If this is the case, you can use the optional "modbusUnitId" property to identify a specific device and return its connection status and device information. If "modbusUnitId" is omitted, the action first tries using a value of 1. If that fails, it tries with a value of 255. If that fails, it returns the error indicating the device is disconnected.

{
  "api": "hub",
  "action": "testInput",
  "params": {
    "inputName": "someModbusInputName",
    "includeDeviceInformation": true,
    "collectValues":true,
    "modbusUnitId": 1
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

MTConnect

The MTConnect aggregates one or more MTConnect devices. Use the required "mtconnectDeviceUuid" property to identify a specific device and return its connection status and device information.

{
  "api": "hub",
  "action": "testInput",
  "params": {
    "inputName": "someMTConnectInputName",
    "includeDeviceInformation": true,
    "collectValues":true,
    "mtconnectDeviceUuid": "16ac1535-3574-509c-8fb2-c536984015fe"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Condensed

{
  "result": {
    "data": [
      {
        "inputName": "someModbusInputName",
        "settings": {          
          "propertyMapList": [
            {
              "propertyPath": "t1"
            },
            {
              "propertyPath": "t2"
            }
          ]
        },

        "collectedValues" : {
           "create_ts": "2026-07-31T17:41:13.468000000Z",
           "t1": 22,
           "t2": 78 
        } 
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Maximal

{
  "result": {
    "data": [
      {
        "id": 1,
        "inputName": "someModbusInputName",
        "serviceName": "modbus",
        "databaseName": "faircom",
        "ownerName": "admin",
        "tableName": "mod1",
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 4,
        "retentionUnit": "week",
        "settings": {
          "modbusProtocol": "TCP",
          "modbusServer": "127.0.0.1",
          "modbusServerPort": 502,
          "dataCollectionIntervalMilliseconds": 5000,
          "dataPersistenceStrategy": "onSchedule",
          "immediatelyCollectDataOnStart": false,
          "propertyMapList": [
            {
              "modbusDataAccess": "holdingregister",
              "modbusDataAddress": "4003",
              "modbusDataLen": null,
              "modbusDataType": "int8Signed",
              "modbusUnitId": "1",
              "propertyPath": "t1"
            },
            {
              "modbusDataAccess": "holdingregister",
              "modbusDataAddress": "4005",
              "modbusDataLen": null,
              "modbusDataType": "int8Signed",
              "modbusUnitId": "1",
              "propertyPath": "t2"
            }
          ]
        },

        "deviceInformation": {
          "productUri": "",
          "deviceType": "",
          "manufacturerName": "",
          "productName": "",
          "model": "",
          "serialNumber": "",
          "softwareVersion": "",
          "buildNumber": "",
          "buildDate": "",
          "userApplicationName": "",
          "deviceState": "",
          "heartbeatTime": "",
          "assetId": ""
        },
        
        "collectedValues" : {
           "create_ts": "2026-07-31T17:41:13.468000000Z",
           "t1": 22,
           "t2": 78 
        } 
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "00000004",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

collectValues

 When true, the "collectValues" property causes the response to include "collectedValues". Optional with default of true Boolean

true

false

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, or 2.

 Optional, not used if not provided.  string String with the format "p,s"

id

 The "id" property specifies the unique identifier of an input connector. Conditional - Required if "inputName" property is omitted. - No default value number or string 1 to 9223372036854770000

includeDeviceInformation

 When true, the "includeDeviceInformation" property tests the connections and returns device information.  Optional with default of false Boolean

true

false

inputName

 The "inputName" property specifies he unique name of an input connector. Conditional - Required if "id" property is omitted. - No default value string 1 to 64 bytes

modbusUnitId

The "modbusUnitId" property specifies a device unit number that uniquely identifies a device. Modbus communicates to ta device or gateway on one IP addresss and port. A device or gateway may proxy Modbus communications across multiple Modbus devices. 

The unit number uniquely identifies each of these devices. This property also applies to serial communications. 

For serial communication, the range is 1 to 255.

Note The original Modbus specification called this feature a slave address.

 Optional with default of 1 int16 0 to 255

mtconnectDeviceUuid

 The "mtconnectDeviceUuid" property specifies the identifier of the device. In an MTConnectStreams XML document, the device identifier is located in the uuid attribute of the <DeviceStream> element.  Required if "includeDeviceInformation" is true. string No limit

 

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

.collectedValues

 The "collectedValues" property contains the values returned by the connector for the properties in the "propertyMapList". It is exactly the value that is normally saved in the source_payload field.  object No limits

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

.deviceInformation

 The "deviceInformation" property contains a standard set of properties that describe the device.  object No limits

data

.id

The "id" property is the unique identifier of an object. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property.

 integer 0 to 2147483647

data

.inputName

 The "inputName" property specifies the unique name of an input. string 1 to 64 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

.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

.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

 

Was this article helpful?

Give feedback about this article

Related Articles