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.

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.

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.

---

Advanced Usage

Set Structure with Tag

Selecting this option allows you to set the base JSON structure from another Tag. Doing this will separate the structure from the logic that fills the individual JSON nodes, and gives you the ability to reuse common JSON structures for multiple JSON Data Source Tags. Changing the structure in the referenced Tag will update every JSON Data Source Tag using it.

Arrays

When filling JSON nodes using the key/tag pairs, if the Tag Data Type is an array (string, integer, etc.), the value injected into the JSON structure will be represented by a JSON array. This makes filling array values of indeterminate length a simple operation.

JSON Object Values

If the referenced Tag uses the String or JSON Data Type, and that string is valid JSON, the value injected into the JSON structure will be a true JSON object, retaining its structure as well. Use this method when you wish to conditionally more complex nodes to the structure.

Export/Import CSV

If you are managing many key/tag mappings and would prefer to do this in Excel or any other CSV editor, you can export the mapping as a CSV, edit the contents, then import settings back in. This is extremely convenient for storing backups and versions of data mappings in external files, or for quickly configuring several similar tags.

MQTT and JSON

The OAS Server operates as an MQTT broker. So you can subscribe to any JSON Data Source Tag as a topic and receive the resulting JSON structure when any value is updated. See this article for information on the OAS MQTT Broker.

---

Examples

Advanced Keys for Dynamic Assignment

The key/tag mapping uses the JSONPath syntax for locating a node in the JSON structure and filling it with the value supplied by the Tag. The simplest usage of a key is selecting a specific node using dot-notation to reflect hierarchy. For example, take the following JSON structure:

{
  "value1" : null,
  "obj1" : {
    "subval1" : null,
    "subval2" : [
      {
        "name" : "sub01",
        "priority" : 0,
        "type" : "temp",
        "val" : null
      },
      {
        "name" : "sub02",
        "priority" : 1,
        "type" : "pressure",
        "val" : null
      },
      {
        "name" : "sub03",
        "priority" : 2,
        "type" : "pressure",
        "val" : null
      }
    ]
  }
} 

key	result
value1	This will set the value1 node to the mapped Tag value. Since this is at the root of the structure, it is the simplest form of mapping.
obj1.subval1	This will set the subval1 node within obj1 to the mapped Tag value. The dot notation indicates structure and hierarchy. If the tag is mapped to the key of just obj1, the entire obj1 node will be replaced by the Tag value and the original structure will be overwritten. If the Tag is a String or JSON Data Type containing a new structure, this will be attached in full as the value of obj1.
obj1.subval2[1].val	This example shows how to explicitly reference an array element. In this case, the 2nd object within the obj1.subval2 will be located, and the val node will receive the value of the mapped Tag.
obj1.subval2[*].val	Using a wildcard asterisk in the array portion of the key will locate all elements within the array, and set all val nodes to the value of the mapped Tag.
obj1.subval2[0,2].val	Specifying 0,2 in the array portion of the key will locate the first and third entries, and then the val will be set on each.
obj1.subval2[:2].val	Specifying :2 in the array portion of the key will locate the first two entries, and then the val will be set on each. You can als use 2: to locate the last two entries in the array.
obj1.subval2[?(@.type==’pressure’)].val	Specifying a search string in the array portion of the key will locate any entry with a type field set to “pressure”.
obj1.subval2[?(@.priority<2)].val	The search string can also do other logical comparisons. This examples shows how you can locate any element in the array with a priority value less than 2.

To access any individual element of an OAS tag with a Data Source of JSON use .JSON-<key name> as the tag variable in any OAS client application including Calculations, Data Logging, and visualization. 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.

For more information on JSONPath and other possible use cases, see this article.