jsonToolkit

Copyright 2019 Tridium, Inc. All Rights Reserved.

Contents

Introduction

The jsonToolkit module adds functionality to Tridium’s Niagara Framework enabling json payloads to be exported from a Niagara station, or when imported, to influence the station in some way. A Schema generates a payload for export, whilst a Handler is used to process imported json.

json, or JavaScript Object Notation, is a simple, lightweight, data encoding format. Used since 2002 to communicate between web browser and server for the Javascript language, it has gained in popularity and as of 2019 is used in many scenarios beyond.

The json format itself is relatively simple, organised into “key” : “value” pairs, with support for data types (Numeric/Boolean/String) much like Niagara points, and 2 data structures: Objects and Arrays. Complexity emerges from these simple constructs mainly due to the variation in expected payload between different pieces of software, and their expected encoding of non-primitive types like date or time. This is where the demand for a flexible solution to marshall Niagara’s rich object model to/from the json format arises.

Quick Json Example

The example below illustrates:

{
    "temperature": [
      {
        "Timestamp": "28-Jun-18 4:42 PM BST",
        "Value": 21.83
      }
    ]
}

Such a simple example could be constructed using StringConcat components from the Niagara kitControl palette, however it does not require many points before this approach becomes limiting, and a set of tools such as this module are required in order to scale.

Typical use cases

Transport protocols

The jsonToolkit itself does not mandate the transport protocol used however potential options include:

Note: These options may be valid for both incoming and outgoing json payloads.

Note: When linking to a publish or subscribe Control Point it may be necessary to use an Engine Cycle Message Queue to ensure all messages are processed.

Feature Summary

Comparison to alternatives

In contrast to the above options - the jsonToolkit does not dictate the protocol, or layout, used to exchange data. This could be an advantage when dealing with charting libraries or cloud service providers expecting to send or receive data in a specific format.

License Requirements

Any host where the json Toolkit is to be used will require the DR-JSON or DR-S-JSON feature added to the license. Production (non-demo) licenses will also require active SMA for the toolkit to function.

SMA Expiration Monitor

Given the jsonToolkit’s requirement for active Maintenance (SMA) on non demo licenses, this monitor increases notifications to the user as expiration approaches. It run on startup, then every 24 hours since the last check to establish if the expiration date is within the warning period, or expired, and will generate an offNormal or Fault alarm accordingly.

Although the alarms are likely the most accessibly notification type, the SMA Monitor will also log to the Station console, and expose the days remaining as a slot which could be shown on a dashboard, for example.

The Station itself has a SMA Notification Setting beneath the user service which will also alert users at the web login screen.

As extension of SMA currently requires a reboot to install the new license, no further checks are performed once expiration is detected, until the Station starts again.

The Json Schema Service

The JsonSchemaService is added to the Stations Services Container and provides some Station global filtering - for example the Global Cov Slot Filter is used to denote which slots should be ignored when subscribed to bound values. The default list of slots include a good example of why this function is necessary in that changes to a components wsAnnotation property (which detail the position and size of a Component glyph on the Wiresheet) should generally be excluded from the changes of value reported to any upstream consumer of data.

Service

Another important property provided by the JsonSchemaService is the Run As User which specifies the user account that should be assumed in the event an incoming change is processed by a Router. This is mandatory when using the SetPointHandler for example, so that any changes triggered by a Cloud Platform can be limited to areas where that platform should have write access within the station. This setting is also optionally used for Json Schema export data.

RunAsUser

Operation Optional? How it works
SetPoint Handler for incoming json No The set operation will only succeed if the RunAsUser is a real user who has Operator Write permission on the slot
Exporting json with a schema Yes When set, the data value of the exported slot shall default to an empty string unless the RunAsUser is a real user who has Operator Read permission on the slot

Note: Run As User is important for security. The property may only be set by a superuser.

The Spy page for the service also has a registry of the export markers contained within the station which might prove useful when debugging issues with Relative Schema, used in conjunction with the Export Marker Paradigm. The central register aids finding the marked points in the event that setpoint changes are received.

Supervisors

The most convenient deployment of the JSON Toolkit in cloud connectivity use cases is connecting directly from the controller schema to the remote transport. However for cases where controllers do not have remote connectivity and so a supervisor is required there are a few options to consider: