`"describeInputs"` (JSON Action)

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

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

Response examples

Minimal

{
    "result": {
        "data": [
            {
                "inputName": "modbusTCP",
                "serviceName": "modbus",
                "settings": {
                    "modbusProtocol": "TCP",
                    "modbusServer": "127.0.0.1",
                    "modbusServerPort": 1505,
                    "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": ""
}

Use the describeInputs JSON API action to returns all available information about each specified FairCom edge input

API actionsJSON hub APIJSON Actioninput actionsdescribe inputdescribeInputs

`"params"`

The "params" property is an object that contains an action's request parameters as defined by a set of properties. Each action defines its own required and optional properties. See System limits for a comprehensive overview of property requirements and limitations.

Table 1. describeInputs "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

dataFormat

(optional) specifies the format of data being sent to the server.

arrays

string enum

autoDetect

arrays

objects

inputNames

(optional) contains "inputName" strings.

[]

array

0 or more strings

`"dataFormat"`

The "dataFormat" property is a case-insensitive string enum that defines the format of the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

"dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
"dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
Possible values include:
- "arrays"
  This causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
- "autoDetect"
  This is the default, and the server automatically detects the format of the data in the "sourceData" property.
"dataFormat" in the response shows the client how the server formatted the "data" property.
Possible values include:
- "arrays"
  This is the default and causes the server to return results as an array of arrays, which is the most efficient.
- "objects"
  This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.

`"inputNames"`

The "inputNames" property is a required array of strings that specifies the names of the inputs you want to be described in the result.

  "params": {
    "inputNames": [
      "modbusTCP"
    ]
  },

`"result"`

Table 2. describeInputs "result" property summaries

Property

Description

Type

Contents

data

Describes each input that matches the request parameters.

Array of objects

One object for each input

databaseName

Contains the name of a database.

string

1 to 64 bytes

inputName

Specifies the unique name of an input.

string

1 to 64 bytes

metadata

Exists primarily for the user interface to find integration information.

object

May contain any number and type of user-defined properties

ownerName

Specifies the unique name of a schema in a database.

string

1 to 64 bytes

retentionPeriod

Specifies the number of retention units, which controls how long data is retained – see "retentionUnit".

integer

1 to 100

retentionPolicy

Specifies how messages persist.

string

"autoPurge"

"neverPurge"

retentionUnit

Purges expired messages each time this unit cycles – see "retentionPeriod".

string

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

serviceName

Specifies the name of a service that collects data from an external source and inserts it into an integration table.

string

1 to 64 bytes

settings

Contains properties needed to configure the data source of the specified plugin.

object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

tableName

Specifies the name of a table.

string

1 to 64 bytes

`"data"`

The "data" property is an array of objects that lists each input that matched the request parameters. Each input is returned in a separate object.

"data": [
      {
        "inputName": "modbusTCP",
        "serviceName": "modbus",
        "settings": {
          "modbusProtocol": "TCP",
          "modbusServer": "127.0.0.1",
          "modbusServerPort": 1505,
          "propertyMapList": [
            {
              "propertyPath": "temperature",
              "modbusDataAccess": "holdingregister",
              "modbusDataAddress": 1199,
              "modbusUnitId": 5,
              "modbusDataLen": 1
            }
          ]
        },
        "databaseName": "faircom",
        "ownerName": "admin",
        "tableName": "modbustabletcp",
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 4,
        "retentionUnit": "week"
      }
    ],

`"databaseName"`

The "databaseName" property is an optional string from 1 to 64 bytes that 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.

`"inputName"`

The "inputName" property is a required string that specifies the unique name of an input.

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

`"metadata"`

The "metadata" property is an optional JSON object. It exists primarily for the user interface to find integration information. By default, it is an empty JSON object.

It contains a flexible set of properties.
It typically contains tags and description properties.

Example

{
  "description": "",
  "tags": [""],
  "yourOwnProperties": "usage, purpose, notes, location, etc.",
}

`"ownerName"`

The "ownerName" property is an optional string from 1 to 64 bytes that identifies the user who owns an object (see Object owner). If it is omitted or set to "" or null, the server uses the default owner name supplied during the "createSession" action or uses the account's "username" as the owner name.

"params": {
  "ownerName": "SuperUser"
}

`"retentionPeriod"`

The "retentionPeriod" property specifies how many units of data to retain. It must be an integer value from 1 to 100. It refers to the unit of time specified by the "retentionUnit" property — for example, if "retentionPeriod" is 14 and "retentionUnit" is "day", then message data is retained for 14 days. This property is optional.

Periodically, the system increments the age of each table partition.
- "Minute" units are incremented at the zero second of each minute, whether the table partition was created 1 second before or 59 seconds before.
- "Day" units are incremented at midnight GMT, not midnight of the local UTC time zone. A table partition becomes one day old at midnight GMT, whether it was created one second before or 23 hours and 59 seconds before.
- "Week" units are incremented at midnight GMT on the last day of each week, even if the table partition was created one second before. The last day of the week is Saturday GMT.
- "Month" units are incremented at midnight GMT on the last day of each month.
- "Year" units are incremented at midnight GMT on Dec 31.
"retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.
If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.
If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

When partitions are auto-purged, some data are maintained "forever" in a global index. Auto-purge does not prevent these files from growing without bounds and filling up your hard drive.

If not specified, the default found in the services.json file is used. Initially, it is 4 (weeks).

Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.

Note

If the value is not an integer from 1 to 100, FairCom's servers set it to the default value.
Smaller numbers improve SQL performance.

Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.
The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".
The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.
The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time. In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.
For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.
The current calendar date affects purging.
FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.
For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.

`"retentionPolicy"`

The "retentionPolicy" property controls how messages are persisted. This property is optional.

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.

`"retentionUnit"`

Each time this unit cycles, FairCom purges 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".

`"serviceName"`

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

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.

`"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"

`"tableName"`

The "tableName" property contains the name of the table in the database where the event occurred. It is a non-zero-length string.

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

A table in DBnotify is defined by "databaseName", "ownerName" and "tableName" or by "dataFilePath".

"describeInputs" (JSON Action)

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

Note

Request examples

Minimal

Response examples

Minimal

Use the describeInputs JSON API action to returns all available information about each specified FairCom edge input

"params"

"dataFormat"

"inputNames"

"result"

"data"

"databaseName"

"inputName"

"metadata"

Example

"ownerName"

"retentionPeriod"

Note

"retentionPolicy"

"retentionUnit"

Note

"serviceName"

Note

Note

"settings"

"tableName"

`"describeInputs"` (JSON Action)

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

`"params"`

`"dataFormat"`

`"inputNames"`

`"result"`

`"data"`

`"databaseName"`

`"inputName"`

`"metadata"`

`"ownerName"`

`"retentionPeriod"`

`"retentionPolicy"`

`"retentionUnit"`

`"serviceName"`

`"settings"`

`"tableName"`