The JSON Action API provides actions to manage data as tags. A tag adds information to each piece of data stored in FairCom Edge, including its name, data type, purpose, description, and metadata to help you manage it. A tag also adds information about where it is used, such as the tables it is stored in, what devices collect it, where it is delivered, etc.
Tags track the flow and provenance of data from devices and software through FairCom Edge to other devices and software. Each tag contains metadata about one specific piece of data so users can find, organize, and standardize the data FairCom Edge collects, transforms, and delivers – no matter what device, equipment, or software it comes from or goes to.
FairCom Edge can collect, store, transform, and deliver data without understanding it, but with tags, you can identify specific data values, track them through processes, and standardize their names, types, and usage. Each tag tracks the provenance of a specific data value as it is transformed, mapped to and from table fields, and delivered to devices and software.
FairCom Edge stores data in enhanced tables called integration tables. Each integration table has a source_payload field that stores the table's data. FairCom's connectors collect data from devices and store that data as JSON properties in the source_payload field. MQTT, SQL, and JSON DB also store JSON properties in the source_payload field. SQL and JSON DB can also store and retrieve data in table fields.
A tag associates a value to a JSON property in the source_payload field and an optional user-defined field in an integration table.
- You can assign the same tag to a specific data value to track its provenance through multiple processes.
- A value being collected from a device by an input connector.
- A value being delivered to a device by an output connector.
- A value persisted in a table's user-defined field.
- A value being transformed.
Devices, equipment, and software are things
In FairCom's JSON API, a device or software application is called a thing, and you can create, alter, delete, list, and describe things.
Tags connect everything
The places where a tag is used can be returned from the tag actions:
- Connectors - List of input and output connectors that use a specific tag.
- Things - List of devices and software that use a specific tag, including when the tag is being collected and/or delivered.
- MQTT topic - List of topics that use a specific tag.
The input, output, thing, and MQTT API actions can return a list of tags that are related to them:
- Connector - List of tags used by a specific connector.
- Thing - List of tags used by a specific device or software.
- MQTT topic - List of tags used by a specific topic.
Each thing may have many input and output connectors
A thing may have many input and output connectors that collect data items and store them in tables. Each data item is a tag.
Connectors are directional
An input connector reads data from a device or software and writes it to one table. An output connector reads data from one table and writes it to a device or software. You can assign many input and output connectors to the same table.
Each connector associates one thing to one table
An input connector collects tags from one device/software and stores them in one table. An input connector associates a tag with each data item it collects into one table. Because many input connectors can write to the same tag, each tag can be associated with multiple input connectors.
An output connector retrieves tags from one table and delivers them to one device/software. An output connector associates a tag with each data item it delivers. Because many output connectors can read from the same tag, each tag can be associated with multiple output connectors.
When you want one input connector to write to multiple tables, use the "jsonToDifferentTableFields" transform to copy tags to additional tables.
A tag's value is collected into a table
Each tag represents a data value that is collected into a specific location in the source_payload field of a table. It can also be copied to a user-defined field in the table.
A table is a group of tags that are stored together during a data collection event and are read during a data delivery event.
The API tracks the tags associated with each connector and unions them together to return the tags associated with a thing.
In a table, a tag exists as a JSON property in the source_payload field, as a user-defined field, or both. A tag is typically stored in both because MQTT works best with the source_payload field and SQL works best with user-defined fields. A tag tracks its location in the source_payload field as a JSON property, and it tracks which user-defined table contains the tag, if any.
Tags in the source_payload field
A connector always stores a tag as a JSON property in the source_payload field. This approach allows MQTT to automatically publish the contents of the source_payload field as a message when a connector writes data to a table. This approach also makes it easy for FairCom's JavaScript engine to transform contents of the source_payload field, such as adding calculated values, looking up values and adding them to the payload, renaming properties, moving properties, writing properties to user-defined fields, and so forth.
SQL and the JSON API can also create a JSON object and insert it into the source_payload field of a new record.
Tags in user-defined fields
Storing a tag as a user-defined field in the integration table is optional.
- It is useful for SQL to perform data analytics and training machine learning.
- Because a tag typically starts as a JSON property in the
source_payloadfield, a user can optionally create a"jsonToTableFields"transform to extract JSON properties from thesource_payloadfield and store them as user-defined fields in the table. The server automatically runs this transform each time a record is inserted. The GUI automatically creates a"jsonToTableFields"transform when the user assigns a tag to a field. - When you want to use SQL to insert records, it may be more convenient to insert data in the user-defined fields rather than the
source_payloadfield.- If you want to synchronize the user-defined field values with the
source_payloadfield, you can create a"javascript"transform to read user-defined fields and add their values to thesource_payloadfield. - Alternatively, you can create a
"jsonToTableFields"transform to read user-defined fields, create a JSON object, and store the result in another user-defined JSON field in the table. You can use the"configureTopic"action to configure MQTT to use this new user-defined field when it sends messages to subscribers.
- If you want to synchronize the user-defined field values with the
Transforming tag data
In addition to the built-in synchronization of a tag's property in the source_payload field and the tag's field, you can create transform steps in the integration table to calculate new values, look up records to add data to the results, rename properties, reshape JSON structure, and populate additional fields with data.
The "jsonToDifferentTableFields" transform can create new tags
The "jsonToDifferentTableFields" transform creates a new tag in a different table. When a record is inserted into the original table, the transform copies the tag's data from the original table to the other table. This operation is one-directional and only works on inserts; thus, it does not synchronize updates or deletes in the original table to the other table and it does not synchronize changes in the other table back to the original table.
Because a "jsonToDifferentTableFields" transform step inserts records in another integration table, it can trigger MQTT messages to be delivered to a different MQTT topic and trigger output connectors to deliver data to REST endpoints and IoT devices.
JavaScript transforms can create new tags
The "javascript" transform can create new tags when it calculates new values and adds new properties in the source_payload field and new fields in the table.
It also changes tag provenance when it renames and moves properties.