describeInputs

JSON hub "describeInputs" action returns all available information about each specified FairCom Edge input

The "describeInputs" action returns all available information about each specified input. Inputs collect tags from a data source and insert them 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.

 

Request examples

Minimal

{
    "apiVersion": "1.0",
    "requestId": "00000027",
    "action": "describeInputs",
    "params": {
        "inputNames": [
            "modbusTCP"
        ]
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Minimal

{
    "result": {
        "data": [
            {
                "inputName": "modbusTCP",
                "serviceName": "modbus",
                "thingName": "PLC 74",
                "enabled": true,
                "running": false,
                "stopCode": 138,
                "disconnectReason": "Modbus timeout(138)",
                "dataCollectionIntervalMilliseconds": 1000,
                "settings": {
                    "modbusProtocol": "TCP",
                    "modbusServer": "127.0.0.1",
                    "modbusServerPort": 502,
                    "modbusDataCollectionIntervalMilliseconds": 15000,
                    "propertyMapList": [
                        {
                            "propertyPath": "temperature",
                            "modbusDataAddress": 1199,
                            "modbusDataAccess": "register",
                            "modbusUnitId": 5,
                            "modbusDataLen": 1
                        },
                        {
                            "propertyPath": "volume",
                            "modbusDataAddress": 1299,
                            "modbusDataAccess": "register",
                            "modbusUnitId": 5,
                            "modbusByteOrder": "ABCD",
                            "modbusDataLen": 2
                        },
                        {
                            "propertyPath": "status",
                            "modbusDataAddress": 1199,
                            "modbusDataAccess": "coil",
                            "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)

inputNames

 The "inputNames" property specifies the names of the inputs you want to be described in the result. Optional with default of [] array 0 or more strings

 

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

.disconnectReason

 The "disconnectReason" property details the reason why the connector disconnected. string No limit

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. A FairCom generated name follows the pattern "Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>".

"params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus"
}
 string 1 to 100 bytes

data

.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. object 0 or more key/value pairs

data

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

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.

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

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

Connector-specific "settings"

 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

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