"createInput"
createInput creates a new input.
The "createInput" action creates a new input. It configures a service to collect data from a data source and insert that data into an integration table.
An input is a service that collects data using a protocol to an integration table in the FairCom server.
For example, the OPC UA service can collect data from an external OPC UA source and write that data to an integration table in FairCom Edge.
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, has its own dedicated integration table, but multiple inputs may insert records into the same integration table.
An input can be mapped to only one integration table, however:
Different inputs can be created to map the same service to different integration tables.
A transform can optionally extract data from the integration table and write this data to another integration table.
When an input is created, if the specified integration table does not exist, FairCom Edge creates it.
An input can only insert records into an integration table because an integration table is designed to be a historical log of data collection events.
An input always and only writes data 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 request example
{
"authToken": "PPnssHDPSSoDlVGZGEYFNehVmI1R8jTvbwhv25DGbKORXETW0iUqPGZwmaW469Gc",
"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": "register",
"modbusSlave": 5,
"modbusDataLen": 1
},
{
"propertyPath": "volume",
"modbusDataAddress": 1299,
"modbusDataAccess": "register",
"modbusSlave": 5,
"modbusByteOrder": "ABCD",
"modbusDataLen": 2
},
{
"propertyPath": "status",
"modbusDataAddress": 1199,
"modbusDataAccess": "coil",
"modbusSlave": 5,
"modbusDataLen": 1
}
]
},
"ownerName": "admin"
},
"requestId": "00000007"
}
{
"authToken": "anAuthorizationTokenFromTheServer",
"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": "register",
"modbusSlave": 5,
"modbusDataLen": 1
},
{
"propertyPath": "volume",
"modbusDataAddress": 1299,
"modbusDataAccess": "register",
"modbusSlave": 5,
"modbusByteOrder": "ABCD",
"modbusDataLen": 2
},
{
"propertyPath": "status",
"modbusDataAddress": 1199,
"modbusDataAccess": "coil",
"modbusSlave": 5,
"modbusDataLen": 1
}
]
},
"ownerName": "admin",
"retentionPolicy": "autoPurge",
"retentionPeriod": 4,
"retentionUnit": "week",
"metadata": {}
},
"requestId": "00000007"
}Response examples
{
"result": {},
"requestId": "00000007",
"errorCode": 0,
"errorMessage": ""
}{
"result": {},
"requestId": "00000008",
"errorCode": 0,
"errorMessage": ""
}"params"
The "params" property is an object that contains an action's parameters. Each action defines its own required and optional properties.
"params" properties summaryProperty | Description | Default | Type | Limits (inclusive) | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
databaseName | contains the name of a database | Defaults to the | string |
| |||||||
inputName | specifies the unique name of an input. | Required - No default value | string |
| |||||||
exists primarily for the user interface to find integration information |
| object | May contain any number and type of user-defined properties | ||||||||
contains the unique name of a schema in a database | Defaults to the default Owner Name set during | string |
| ||||||||
sets the number of retention units, which controls how long data is retained – see |
| integer |
| ||||||||
controls how messages are persisted |
| string |
| ||||||||
purges expired messages each time this unit cycles – see |
| string |
| ||||||||
contains the name of a service that collects data from an external source and inserts it into an integration table | Required - No default value | string |
| ||||||||
contains properties needed to configure the data source of the specified plugin | {} | object |
| ||||||||
specifies the name of a table | Required - No default value | string |
|
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.",
}
The "ownerName" property is an optional string from 1 to 64 bytes that specifies the account that owns an object.
The
"ownerName"property is optional and has a dynamic default value.If the
"ownerName"property is omitted or set tonull, the server uses the value of the"defaultOwnerName"property supplied during the "createSession"action.If the
"defaultOwnerName"property is not defined, the server uses the"admin"as the owner name.The owner of an object has administrative rights over that object.
The
"ownerName"property is a namespace for an object. You can think of it as a container of objects.The
"ownerName"allows users to use any name for the objects they create — for example, a QA engineer may copy tables into their owner space to run a set of tests.It is common for a user to create their own copies of objects from other accounts for testing, troubleshooting, and fixing data. The copied objects can retain the same name because the
"ownerName"distinguishes between them.The fully qualified name of an object is the
"databaseName","ownerName", and the object's name, such as"tableName"meaning a FairCom server may contain many tables with the name"mytable"as long as each one is in a different database or in a different owner space.For example, an organization often creates different databases for different phases of the development lifecycle, such as dev, test, stage, ua, and prod. Each of these databases contains the same set of objects with the same names. Applications leave the
"databaseName"out of their JSON actions and use the"defaultDatabaseName"property to specify the target database.Queries and scripts are often written without specifying
"databaseName"and/or"ownerName", allowing queries and scripts to work properly when run in different databases or in different schemas.
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
1to100, 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 to14, 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 today, 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.
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.
"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.
"doNotPersist"This stores messages only in RAM, where they are transmitted more quickly. Undelivered messages are lost when FairCom's servers stop and restart. No transforms can be applied to the payload. Message data cannot be bridged across protocols.
Important
Changing the "retentionPolicy" property value to "doNotPersist" removes all existing message history for the topic because it changes how messages are stored on disk.
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"between5and30.When the
"retentionUnit"is set to"forever"the messages will never be purged.FairCom MQ only uses the
"retentionUnit"property when the"retentionPolicy"is"autoPurge".
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.
"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.
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"
The "tableName" property is an optional string that contains the name of an integration table or MQTT topic that holds the topic's messages. It defaults to an empty string.
You can use a topic name for an MQTT table because FairCom automatically generates a table name for each topic.
A
"tableName"cannot begin with a number.It refers to the name of the integration table that stores a topic’s messages and is used to rename that table or assign a new topic to an existing integration table.
MQTT automatically creates an integration table for each new topic it receives. Thus, when a message is sent to a topic, FairCom Edge automatically creates a table to hold it.
As you refine your integration processes, you may want to rename an integration table to better label the data it holds. You can use the
"tableName"property of the"configureTopic"action to rename an integration table.The
"alterIntegrationTable"action can also be used to rename an integration table, but it is less convenient because you must know the original name of the integration table.