JSON Handling on the OAS Platform

The OAS Platform offers support for handling and manipulating JSON formatted data, which is crucial when integrating with many external systems such as cloud-based analytics platforms, and for working within common Industrial IoT scenarios. Specifically, data passed between systems using the MQTT protocol, data sent and received from REST APIs, and even records stored in many database engines all use JSON formatting for hierarchical data. For more information on JSON, see our article “What is JSON?” on how it is structured and compares to other similar data formats like XML.

JSON Data Type

Along with other standard Data Types such as Integer, String, Double Float, etc., OAS Tags can be assigned the JSON Data Type. This functions very much like a String Data Type except that internal JSON validation is performed whenever the value changes. This validation ensures that the value set on the Tag is properly formatted JSON. If the validation fails, the Tag will be marked as having Bad Quality. Your applications and other tags can be configured to respond to this state as needed, preventing invalid JSON from reaching other endpoints.

To set a Tag as a JSON Data Type, simply select JSON from the Data Type dropdown and click Apply Changes. Validation will immediately take effect. For all other operations such as Tag Calculations, you can reference a Tag of JSON Data Type just as you would with a String Tag. Values from JSON Tags can also be used in Text Calculations just as you would with String data.

Select JSON as a Data Type for Tag Configurations

JSON Data Source

In addition to setting the Data Type to JSON for automatic data validation, you can also set the Data Source as JSON for highly customizable generation of JSON data packets. This is especially useful for storing structured data or for crafting JSON data packets to be sent to external systems such as MQTT clients, or other 3rd party cloud applications. Using the JSON Data Source gives you the ability to define a base JSON structure, then use JSONPath syntax to locate nodes in the structure for replacement with OAS Tag data.

Learn more about the JSON Data Source, including some advanced usage and examples.

Setting the Data Source as JSON reveals additional properties

A Tag with a JSON Data Source can have a base Structure set directly as a valid JSON string, or it can be set using another Tag. This will allow you to dynamically modify the base structure, or use the same base structure for multiple tags. Below is an example of editing the JSON structure directly.

The JSON structure can be edited directly on the Tag

Assigning key/tag pairs are done in the by selecting Add in the table below the Structure property. This will open a Tag browser which allows you to pick a Tag from the local OAS instance or any reachable remote OAS instance. The key is a search parameter defining where to find the JSON node to fill with the Tag value. This key uses JSONPath syntax and can be either a direct path to the node or a dynamic query to find one or more nodes matching the criteria. For more information on JSONPath syntax, see this article.

This example illustrates injecting 3 Tag values using different JSONPath keys

JSON Data Visualization

You can access individual elements of JSON data for read and write access from any of the OAS client applications including WPF HMI, WinForm HMI, Web HMI, Excel, Calculations, Data Logging, Recipe, OPC UA client, OPC DA client, Data Route, and programmatic interface via .NET or REST API.

To access any individual element of an OAS tag with a Data Source of JSON use .JSON-<key name> as the tag variable. An example OAS_Tag.JSON-motors[0].current would provide read and write access of the current value of the first motor element of the array of motors.

The OAS Configuration Application also has the ability to recognize JSON data and will assist with visualization. For Tags of both String and JSON Data Type, clicking on the current value will display the value in text form. If the value can be parsed as valid JSON, it will be displayed using a hierarchical JSON visualizer allowing you to expand or collapse nodes and arrays, as well as see the data with syntax highlighting.

OPC UA Structures

OAS can read and write OPC UA values that are from flat or multi-level hierarchical structures. The element names and values will be parsed into JSON data as it is received from the OPC UA server. Values can also be written to the OPC UA server that represent structures.

JSON Calculations

The OAS Platform Calculation Engine provides powerful features for real time data transformations and logic. Additionally, the Calculation Engine supports a set of functions for generating, querying, and manipulating JSON data. For example, if you create a tag containing a JSON structure, you can use the JSON Calculations to locate data points within the structure, add other structures to the JSON, and even set values on a particular node. See our documentation on JSON Calculations for more information.

JSON and MQTT

The OAS Platform can act as an MQTT client as well as an MQTT broker. When used as an MQTT client with the MQTT Connector can publish and subscribe to any MQTT broker. This allows you to send OAS Tag data whenever values have changed. By default, OAS creates a simple JSON message that includes the current Tag value, and timestamp when it was updated in the OAS platform. If you prefer to craft your own custom message format, including more data and even data from multiple Tags, you can set the source Tag to the JSON data type or String data type containing valid JSON and the message published will be used instead of the default format. This includes using JSON Calculations to dynamically generate the Tag value as data changes. With this powerful feature you can guarantee the messages sent to remote systems comply with your requirements.

The OAS Platform built-in message payload for MQTT is simple and concise. The Tag’s current value, timestamp when the value changed, and the data quality of the tag are published as bare values in separate topics. For example, if your Tag name is MyTag, the topic of MyTag will contain the current value of the tag. In the configuration of a Tag with MQTT as the Data Source, you can also configure the topic name. Also, if you check “Include Timestamp” and/or “Include Quality”, an additional topic will be created for each.

While this is simple and easy to configure, there may be cases where you would like to send a custom payload containing the Tag’s value, timestamp, and quality in a single message published to a single topic. Or you may want to send values from multiple tags in a single payload. If you set the Tag Data Type to JSON or String containing a valid JSON structure, the payload will now contain the JSON structure. This means you can use a Calculation tag to construct your JSON, based on string literals or a segment derived from another larger JSON structure, or even combine multiple tags into a single JSON payload and you have the freedom to choose what gets sent to the MQTT Broker. For example, this JSON could be created from a JSON Calculation containing four tags in an array along with additional wrapper values:

{
  "title" : "MyTagData",
  "tags" : [
    {"n" : "Tag1", "v": true, "ts" : 1234567890, "q": "GOOD" },
    {"n" : "Tag2", "v": 99.12, "ts" : 1234567890, "q": "GOOD" },
    {"n" : "Tag3", "v": 14, "ts" : 1234567890, "q": "BAD" },
    {"n" : "Tag4", "v": "data", "ts" : 1234567890, "q": "GOOD" }
  ]
}

IoT Publish

OAS can publish any tag value to MQTT Brokers, AWS IoT Gateway, and Azure IoT Hub in bulk payload as one topic as JSON. View how to publish live data to AWS IoT Gateway, Azure IoT Hub, and MQTT Brokers. With these knowledge base articles you will see the structure created for bulk payload with multiple tags per topic and single topic payload for values from any OAS data source.

The tag IoT publish feature is built into each driver configuration to make setup extremely simple to define selected tags from the local OAS Engine or remote OAS Engine.

Knowledge Base