Skip to main content

"createInput" (jsonAction)

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.

Essential information

  • 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, say, to publish the data to multiple MQTT topics. 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 example

Minimal

{
    "api": "hub",
    "action": "createInput",
    "params": {
        "inputName": "modbusTCPOne",
        "serviceName": "modbus",
        "tableName": "modbusTableTCP",
        "settings": {
            "modbusProtocol": "TCP",
            "modbusServer": "127.0.0.1",
            "modbusServerPort": 1505,
            "modbusDataCollectionIntervalMilliseconds": 15000,
            "propertyMapList": [
                {
                    "propertyPath": "temperature",
                    "modbusDataAddress": 1199,
                    "modbusDataAccess": "holdingregister",
                    "modbusUnitId": 5,
                    "modbusDataLen": 1
                },
                {
                    "propertyPath": "volume",
                    "modbusDataAddress": 1299,
                    "modbusDataAccess": "holdingregister",
                    "modbusUnitId": 5,
                    "modbusByteOrder": "ABCD",
                    "modbusDataLen": 2
                },
                {
                    "propertyPath": "status",
                    "modbusDataAddress": 1199,
                    "modbusDataAccess": "coil",
                    "modbusUnitId": 5,
                    "modbusDataLen": 1
                }
            ]
        },
        "ownerName": "admin"
    },
    "requestId": "00000007",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
    "api": "hub",
    "action": "createInput",
    "params": {
        "database": "ctreeSQL",
        "inputName": "modbusTCP",
        "serviceName": "modbus",
        "tableName": "modbusTableTCP",
        "settings": {
            "modbusProtocol": "TCP",
            "modbusServer": "127.0.0.1",
            "modbusServerPort": 1505,
            "modbusDataCollectionIntervalMilliseconds": 15000,
            "propertyMapList": [
                {
                    "propertyPath": "temperature",
                    "modbusDataAddress": 1199,
                    "modbusDataAccess": "holdingregister",
                    "modbusUnitId": 5,
                    "modbusDataLen": 1
                },
                {
                    "propertyPath": "volume",
                    "modbusDataAddress": 1299,
                    "modbusDataAccess": "holdingregister",
                    "modbusUnitId": 5,
                    "modbusByteOrder": "ABCD",
                    "modbusDataLen": 2
                },
                {
                    "propertyPath": "status",
                    "modbusDataAddress": 1199,
                    "modbusDataAccess": "coil",
                    "modbusUnitId": 5,
                    "modbusDataLen": 1
                }
            ]
        },
        "ownerName": "admin",
        "retentionPolicy": "autoPurge",
        "retentionPeriod": 4,
        "retentionUnit": "week",
        "metadata": {}
    },
    "requestId": "00000007",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Minimal

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

Maximal

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

Use the createInput JSON API action to create a new FairCom Edge input

API actionsJSON hub APIjsonActioninput actionscreate inputcreateInput

"params"

The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.

Table 1. "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

databaseName

(optional) contains the name of a database

Defaults to the "defaultDatabaseName" value that is set during "createSession". If no default is set during "createSession", then "faircom" is used.

string

1 to 64 bytes

dataCollectionIntervalMilliseconds

(optional) specifies the number of milliseconds to wait until reading PLC data again. For example, 15000 means 15 seconds

10000

integer

0 and negative values are invalid

dataCollectionBufferCount

(optional) specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table

1

integer

1 to 65535

dataPersistenceStrategy

(optional) specifies when the connector writes collected data to the specified table

"onSchedule"

string

"onSchedule"
"onChange"

immediatelyCollectDataOnStart

(optional) configures the input to collect data immediately when the server or connector starts. This occurs even if the data persistence strategy is to collect data changes

false

Boolean

true
false

inputName

specifies the unique name of an input.

Required - No default value

string

1 to 64 bytes

metadata

(optional) exists primarily for the user interface to find integration information

{}

object

May contain any number and type of user-defined properties

ownerName

(optional) specifies the unique name of a schema in a database

Defaults to the default Owner Name set during "createSession".

string

1 to 64 bytes

retentionPeriod

(optional) specifies the number of retention units, which controls how long data is retained – see "retentionUnit"

4

integer

1 to 100

retentionPolicy

(optional) specifies how messages persist

"autoPurge"

string

"autoPurge"
"neverPurge"

retentionUnit

(optional) purges expired messages each time this unit cycles – see "retentionPeriod"

"week"

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

Required - No default value

string

1 to 64 bytes

settings

(optional) contains properties needed to configure the data source of the specified plugin

{}

object

Allen-Bradley "params"
Modbus "params"
OPC UA "settings"
Siemens S7 "params"

sourcePayloadFormat

(optional) specifies the variant type format of the "source_payload" field

"binary"

string

"json"
"xml"
"binary"
"jpeg"
"siemensUdt"
"utf8"

tableName

(optional) specifies the name of a table

""

string

1 to 64 bytes

transformName

(optional) specifies the name of a transform process you have created. See the "createTransform" and "alterTransform" actions

""

string

1 to 64 bytes



"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 specifies the account that owns an object.

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

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.

  • 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 does not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".

  • FairCom MQ only uses the "retentionUnit" property when the "retentionPolicy" is "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"

"sourcePayloadFormat"

The "sourcePayloadFormat" property is an optional string that defines the variant type format of the "source_payload" field. When omitted or set to null, it defaults to "binary".

  • This property is a string containing the following enumerated values:

    •  "binary"

    • "json"

    • "utf8"

    • "siemensUDT"

    • "jpeg"

    • "xml"

  • This property is a hint to the server about the format and type of the MQTT message payload.

  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, if you set the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.

  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.

  • The transform engine may use the value of this property to help it transform the source payload.

"tableName"

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

A table name may contain up to 64 ASCII characters and must not start with a number.

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

"transformName"

The "transformName" property is an optional string that contains the unique name of a transform process, which consists of one or more transform steps.

The value of "transformName" must be the name of a transform process you created. It cannot be the name of a FairCom-provided transform method.

You must create a transform before you can assign it to an integration table. See the "createTransform" and "alterTransform" actions.

  • A transform is a process that works like a pipeline where the output of one transformation can become the input for another transformation.

  • The following actions use the "transformName" property to assign a transform to an integration table:

    • "configureTopic"

    • "createInput"

    • "alterInput"

    • "createIntegrationTable"

    • "alterIntegrationTable"

JavaScript Object Notation (JSON) is a simple format for representing data. It requires very little markup and is flexible enough to represent the majority of data structures. It is self-describing, which makes it ideal for schemaless applications and search. It can optionally be paired with a schema to define an expected structure.

Would you like to provide feedback?