DR-JSON Manual

Technical Document
Niagara JSON Toolkit Guide
December 9, 2019
Niagara JSON Toolkit Guide
Tridium, Inc.
3951 Westerre Parkway, Suite 350
Richmond, Virginia 23233
U.S.A.
Confidentiality
The information contained in this document is confidential information of Tridium, Inc., a Delaware
corporation (“Tridium”). Such information and the software described herein, is furnished under a license
agreement and may be used only in accordance with that agreement.
The information contained in this document is provided solely for use by Tridium employees, licensees, and
system owners; and, except as permitted under the below copyright notice, is not to be released to, or
reproduced for, anyone else.
While every effort has been made to assure the accuracy of this document, Tridium is not responsible for
damages of any kind, including without limitation consequential damages, arising from the application of the
information contained herein. Information and specifications published here are current as of the date of this
publication and are subject to change without notice. The latest product specifications can be found by
contacting our corporate headquarters, Richmond, Virginia.
Trademark notice
BACnet and ASHRAE are registered trademarks of American Society of Heating, Refrigerating and Air-
Conditioning Engineers. Microsoft, Excel, Internet Explorer, Windows, Windows Vista, Windows Server, and
SQL Server are registered trademarks of Microsoft Corporation. Oracle and Java are registered trademarks
of Oracle and/or its affiliates. Mozilla and Firefox are trademarks of the Mozilla Foundation. Echelon, LON,
LonMark, LonTalk, and LonWorks are registered trademarks of Echelon Corporation. Tridium, JACE,
Niagara Framework, and Sedona Framework are registered trademarks, and Workbench are trademarks of
Tridium Inc. All other product names and services mentioned in this publication that are known to be
trademarks, registered trademarks, or service marks are the property of their respective owners.
Copyright and patent notice

This document may be copied by parties who are authorized to distribute Tridium products in connection
with distribution of those products, subject to the contracts that authorize such distribution. It may not
otherwise, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic
medium or machine-readable form without prior written consent from Tridium, Inc.
Copyright © 2020 Tridium, Inc. All rights reserved.
The product(s) described herein may be covered by one or more U.S. or foreign patents of Tridium.
Contents
About this guide .................................................................................................7
Document change log ................................................................................7
Related documentation ..............................................................................7
Chapter 1 Introduction .....................................................................................9

Quick JSON example ...............................................................................11
JSON Toolkit use cases ............................................................................11
Transport protocols..................................................................................12
Feature summary .....................................................................................12
Comparison to alternatives .......................................................................12
License requirements ...............................................................................13
JSON schema service ...............................................................................13
Supervisor................................................................................................14
Chapter 2 Exporting with a JSON schema ......................................................17

Config folder............................................................................................18
Tuning policy ...........................................................................................19
Overrides.................................................................................................19
Debugging errors (Schema History Debug)................................................20
JSON schema metrics...............................................................................20
Schema construction ................................................................................21
Entities ..........................................................................................22
Creating a regular schema ..............................................................25
Relative schema construction..........................................................27
Export markers ..............................................................................28
Queries....................................................................................................30
Setting up queries ..........................................................................33
Alarms .....................................................................................................35
Exporting alarm records to the JsonAlarmRecipient.........................36
Exporting schema output (JsonExporter) ..................................................38
Exploring the examples ............................................................................38
Connecting a device .......................................................................40
Visualization...................................................................................41
Chapter 3 Importing JSON .............................................................................43

Routing complete incoming messages ......................................................43
Routing part of a message ........................................................................44
About the Json Path selector ....................................................................46
Applying a jsonPath selector...........................................................46
Handlers and alarm acknowledgments ......................................................47
Setpoint handler and writing to points ......................................................48
Export setpoint handler and export registration ........................................48
Chapter 4 Developer guide ............................................................................51

JSON schema types .................................................................................51
Relative topic builder................................................................................53
December 9, 2019 3
Contents Niagara JSON Toolkit Guide
Type Override example ............................................................................53

Inline JSON Writer ...................................................................................54
Custom query style ..................................................................................55
Builder class / API.....................................................................................57
Useful methods ........................................................................................57
How schema generation works .................................................................58
Working with Apache Velocity...................................................................61
Subscription examples with bajascript.......................................................62
Inbound components ...............................................................................64
Chapter 5 Components...................................................................................65
JsonSchema (Json Schema).......................................................................66
Config (Json Schema Config Folder)..........................................................67
Tuning Policy (Json Schema Tuning Policy).......................................69
Overrides (Json Schema Overrides Folder) ......................................70
Debug (Json Schema Debug Folder) .........................................................70
Schema Output History Debug (Schema History Debug) ..................71
Metrics (Json Schema Metrics) ........................................................71
Queries (Json Schema Query Folder).........................................................73
Query (Json Schema Query)............................................................73
RelativeHistoryQuery (Relative History Query).................................74
BoundQueryResult (Json Schema Bound Query Result) ....................74
Base Query (Base Query) ................................................................75
RelativeJsonSchema (Relative Json Schema) ..............................................75
JsonSchemaService (Json Schema Service) ................................................76
S M A Expiration Monitor (S M A Expiration Monitor).......................77
Global Cov Slot Filter (Subscription Slot Blacklist) ............................78
Object (Json Schema Object) ....................................................................78
BoundObject (Json Schema Bound Object) ...............................................79
Array (Json Schema Array) ........................................................................80
BoundArray (Json Schema Bound Array.....................................................80
FixedString (Json Schema String Property) ................................................81
FixedNumeric (Json Schema Numeric Property) ........................................81
FixedBoolean (Json Schema Boolean Property)..........................................82
Count (Json Schema Count Property) ........................................................82
CurrentTime (Json Schema Current Time Property)....................................82
UnixTime (Json Schema Unix Time Property) .............................................83
BoundProperty (Json Schema Bound Property)..........................................83
BoundCSVProperty (Json Schema Bound Csv Property) .............................84
Facet (Json Schema Facet Property)..........................................................85
FacetList (Json Schema Facet List).............................................................85
Tag (Json Schema Tag Property) ...............................................................86
TagList (Json Schema Tag List)..................................................................87
Query (Json Schema Query)......................................................................87
RelativeHistoryQuery (Relative History Query)...........................................88
BoundQueryResult (Json Schema Bound Query Result) ..............................88
JsonAlarmRecipient (Json Alarm Recipient) ...............................................89
4 December 9, 2019
Niagara JSON Toolkit Guide Contents
AlarmRecordProperty (Json Schema Alarm Record Property) .....................89

BFormatProperty (B Format String) ...........................................................90
ExportMarker (Json Export Marker) ..........................................................90
AlarmExportMarkerFilter (Alarm Export Marker Filter)...............................92
HistoryExportMarkerFilter (History Export Marker Filter)...........................92
JsonExportSetpointHandler (Json Export Setpoint Handler) ......................94
JsonExportRegistrationHandler (Json Export Registration Handler) ...........95
JsonExportDeregistrationHandler (Json Export Deregistration
Handler)..............................................................................................96
JsonMessageRouter (Json Message Router) ..............................................98
JsonDemuxRouter (Json Dmux Router) .....................................................99
JsonPath (Json Path)............................................................................... 100
JsonAtArrayIndex (Json At Array Index) .................................................. 101
JsonContainsKey (Json Contains Key) ..................................................... 101
JsonIndexOf (Json Index Of Key Selector) ............................................... 102
JsonSum (Json Sum Selector).................................................................. 102
JsonLength (Json Length Selector).......................................................... 103
JsonFindAll (Json Find All Selector) ......................................................... 104
AlarmUuidAckHandler (Alarm Uuid Ack Handler) ..................................... 104
SetPointHandler (Json Set Point Handler) ................................................ 105
EngineCycleMessageQueue (Engine Cycle Message Queue).................... 106
EngineCycleMessageAndBaseQueue (Engine Cycle Pair Queue) .............. 107
InlineJsonWriter (Inline Json Writer) ........................................................ 107
TypeOverride (Type Override) ................................................................. 108
relativeTopicBuilder (Program)................................................................ 109
Index...............................................................................................................111
Glossary ..........................................................................................................113
December 9, 2019 5
Contents Niagara JSON Toolkit Guide
6 December 9, 2019
About this guide
The JSON Toolkit provides a way to easily extract data from a station as well as a way to input information
to control connected devices.
The beginning chapters introduce data output and input. The Developer Guide chapter explains how to ex-
tend toolkit features.
Document change log

Changes to this document are listed in this topic.
December 9, 2019
Initial document release
Related documentation
These documents provide additional information about how to construct data models using the Niagara
Framework.
In te r n al resou rce s
• Niagara Developer Guide
• Niagara Drivers Guide
• Niagara Graphics Guide
• Bajadoc (accessed through the Workbench Help system)
Ex t er n al re sourc es
• Java Platform Standard Edition 7 Documentation: https://docs.oracle.com/javase/7/docs/
• Unix time: https://en.wikipedia.org/wiki/Unix_time
• Chart.js, JavaScript charting for designers and developers: https://www.chartjs.org/
• Google Chart: https://developers.google.com/chart
Chapter 1 Introd ucti on
Topics covered in this chapter
♦ Quick JSON example
♦ JSON Toolkit use cases
♦ Transport protocols
♦ Feature summary
♦ Comparison to alternatives
♦ License requirements
♦ JSON schema service
♦ Supervisor
The JSON Toolkit module adds functionality to the Niagara Framework®, enabling you to export JSON
data (payloads) from a station, or, when importing data, to influence the station in some way. A schema
generates a payload for export, whilst a handler processes imported JSON. The Toolkit is intended to give
you the power to adapt as needed.
JSON (JavaScript Object Notation) is a simple, lightweight, data encoded string. Used for data interchange
since 2002 to communicate between a web browser and a server for the Javascript language, it has gained
popularity and is used in many scenarios beyond those implemented in 2002. Many IoT devices can easily
receive a JSON payload.
December 9, 2019 9
Chapter 1 Introduction Niagara JSON Toolkit Guide
Fi gu re 1 Logical JSON flow
On the left is the universe of data available to a Niagara Station. The station database provides some data;
other data can come from outside the station. The Schema contains configuration properties, which set up
its functions. A schema updates when a CoV triggers a generation action from a bound entity or a person
invokes the generate action on a schema Property Sheet. This causes any linked properties of the JSON
Object payload to create the Output string, which retrieves and routes the data onward through a Transport
Point and Handler to an alarm recipient, the cloud or other destination, and back to the device for asset
control, such as to control the lighting in a home or acknowledge an alarm.
The format of the JSON output string is relatively simple, organised into a list of key:value pairs, with
support for data types: Numeric, Boolean, Enum and String much like Niagara points. JSON messages can
use any sequence of objects, arrays and key/value pairs. The JSON Toolkit is flexible. You, as a developer
can extend the Toolkit or use APIs to access station data. You can drag schema elements around and change
the order of the messages.
JSON supports two 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 also their
expected encoding of non-primitive types, such as date and time. This is where the demand arises for a
flexible solution to marshal Niagara’s rich object model to and from the JSON format.
You can extend the Toolkit or use APIs to access a station’s data. JSON can post data to APIs for data
transmission. For example, using the inbound components of the JSON Toolkit, external systems can send a
JSON-encoded message to a Niagara station to change a setpoint or acknowledge an alarm.
As the data manipulator, you set up data retrieval and use by creating links between JSON objects. Each
schema contains a single root object, which itself contains the JSON objects that establish the links.
10 December 9, 2019
Niagara JSON Toolkit Guide Chapter 1 Introduction
F ig ure 2 JSON workflow
From the station to the destination, you link the output string, typically via MQTT, to a string-publish point,
which sends the payload to a topic in the broker that forwards (transports) it to the destination system. The
schema itself is transport agnostic. Linking produces the desired result.
For example, just as an external oBIX client can poll a station for data, the JSON output can be retrieved via
an HTTP GET request to a URL that exposes its contents as a web servlet. Using JSON, you can have the
same rich data that oBIX provides without the pre-defined oBIX format. Using JSON, you choose the format
of the data, which affords total flexibility.
MQTT brokers can link the output of a JSON schema to a cloud platform, such as Bluemix, Google Cloud,
and AWS.
Quick JSON example

This is a simple example with JSON objects and arrays.
{
"temperature": [
{
"Timestamp":"28-Jun-18 4:42 PM BST",
"Value":21.83
}
]
}
In this example:
• A root object encloses the whole payload with open and close braces { }. A JSON schema object is a
named container that holds other schema entities. By itself an object has no properties or additional
containers.
• A JSON array named “temperature”. An array is a named container represented by brackets [ ] that holds
other schema entities.
• An object, in braces { }, is contained by the “temperature” array.
• The object contains a string “Timestamp” and a numeric “Value.” Each appears as a key/value pair inside
the object.
You could construct this simple example using StringConcat components from the kitControl module,
however, if you have many points it would take a lot of work to create this construct for every point. A JSON
schema can work across many points without extra effort.
JSON Toolkit use cases

The following information includes a summary of typical JSON use cases, transport protocols and a summary
of the toolkit features.
Ty p i c a l u s e c a s e s
Following are some possible use cases for the JSON Toolkit:
• Cloud connectivity (IoT)
• Visualization
• Device connectivity
December 9, 2019 11
• Machine learning
• Analytics
• Data archival
Tr ans po r t pro to c o ls
The JSON Toolkit itself does not mandate the transport protocol used.
Potential transport protocols include:
• MQTT (by linking the JSON schema output to an Mqtt String Publish Point)
• HTTP(s)
• Box (bajaux widget)
• File
These options may be valid for both incoming and outgoing JSON payloads. When linking to a publish or
subscribe control point, you may need to use an Engine Cycle Message Queue component to ensure that
the schema outputs all messages to the linked transport.
Fea ture s um m ar y
The JSON Toolkit supports a significant list of features and options to aid the engineering effort.
• Customer-definable JSON payloads
• Payloads for types other than points, such as, tags and facets
• Payloads for histories, series transform, and alarms
• Data selection using either bindings (ords), bql, or the addition of markers that directly identify points
• Support for encoding alarm events via a JsonAlarmRecipient
• The ability to respond to incoming requests to change a setpoint or acknowledge an alarm by uuid
• On-demand payloads generated by a CoV
• Topic generation for a relative schema (for example, mqtt publish topic)
• Tuning policies to throttle output
• Program object-based overrides
• The ability for developers to extend the toolkit
Comparison to alternatives
JSON Toolkit alternatives include oBIX and bajaScript.
• oBIX (obix.org) provides a comprehensive connectivity option for Niagara, the JSON Toolkit differs by of-
fering a flexible, user-defined payload, and support for publish-on-change.
• bajaScript (bajascript.com) provides a means to access the Niagara component model with convenient
support for complex objects, subscription, action invocation, and querying.
• Project Haystack (project-haystack.org) offers both a common semantic model and a protocol to enable
the exchange of data. These tags can be included in the payloads generated by the JSON Toolkit.
In contrast to the above options, the JSON Toolkit does not dictate the protocol or layout used to exchange
data. This could be an advantage when dealing with charting libraries and cloud service providers who ex-
pect to send or receive data in a specific format.
12 December 9, 2019
Li c ens e req uirem e nts

To use the JSON Toolkit, your host requires the DR-JSON or DR-S-JSON feature added to the host’s license.
Production (non-demo) licenses also require an active Software Maintenance Agreement (SMA) for the tool-
kit to function. Engineering or Demo licenses should have this feature added by default.
SMA Expiration Monitor
In addition to the licensed feature requirement, the toolkit requires an active SMA in order to run. The Expi-
ration Monitor increases notifications as expiration of this agreement approaches. It runs on startup, the
monitor (of the JsonSchemaService) checks every 24 hours to establish if the expiration date is within the
warning period, or expired, and generates an offNormal or fault alarm accordingly. Although the alarms
are likely the most accessible type of notification, the SMA Monitor also logs the days remaining to the sta-
tion console, which, for example, could be shown on a dashboard. The station’s UserService also has an
SMA Notification property, which alerts users at the web login screen.
As the extension of the SMA currently requires a reboot to install the new license, once the monitor detects
that the agreement has expired it performs no further checks until the station starts again.
JSON schema service

To use the toolkit, you first need to set up the JsonSchemaService by adding it to the station S e r v i c e s
container.
Adding the JsonSchemaService component to the S e r v i c e s container can provide some station global fil-
tering as well as the ability to restrict user access when handling inbound messages.
F ig ure 3 JsonSchemaService properties
The Spy page for the service maintains a registry of the export markers contained within the station. This
registry might prove useful when debugging issues with relative schema used in conjunction with the export
marker paradigm. In the event that setpoint changes are received, the register aids in finding the marked
points.
Global Cov Slot Filter

The Global Cov Slot Filter can denote which slots to ignore when subscribing to bound values. The de-
fault list of slots includes a good example of why this function is necessary in that changes to a component’s
wsAnnotation property (which defines the position and size of a component glyph on the wire sheet)
should generally be excluded from the changes of value reported to any upstream consumer of data.
Run As User
Another important property provided by the JsonSchemaService is Run As User. This property specifies
the user account to assume in the event that a router processes an incoming change. For example, this as-
sumption is mandatory when using the SetpointHandler, so that any changes triggered by a cloud plat-
form are limited to areas in the station where the platform has write access. JSON schema export data also
optionally use this property.
December 9, 2019 13
Operation Optional? How it works
Configuring a setpoint handler for incoming JSON No The set operation only succeeds if the Run As User is a real
user who has operator write permission on the slot target.
Defining a schema for exporting JSON Yes When set, the data value of the exported slot defaults to an
empty string unless the Run As User is a real user who has
operator read permission on the slot.
N O T E : Run As User is important for security. This property may only be set by a super user.
Debugging with Spy page

The Spy page for the JsonSchemaService also has a registry of the export markers (refer to the Export
Marker topic) contained within the station, which might prove useful when debugging relative schema issues
that are used in conjunction with the export marker paradigm. The central register aids finding the marked
points in the event that setpoint changes are received.
Fi gu re 4 JsonSchmaService Spy page link
Supervisor
The most convenient deployment of the jsonToolkit in cloud connectivity is to connect directly from the con-
troller schema to the remote transport. However, if a controller does not have remote connectivity, a Super-
visor is required. There are a few options to consider.
NiagaraNetwork point export

You import points from subordinate controllers into a Supervisor under the NiagaraNetwork and create
Supervisor schemata.
• Schema queries and bindings may target points under the N i a g a r a N e t w o r k and subscription (change of
value) will work ok.
• Some information, such as the parent name and original slot path of the points, may not be available in
the schemata.
• Tag data and permissions may need to be redefined at the Supervisor level.
• Alarms and histories need to be imported to the Supervisor if you require these data for your schema.
• This approach requires the most configuration overhead and may not be desirable to import all the
points to the Supervisor.
System database
Use the system database to index subordinate controllers and sys: ords for queries within a Supervisor
schema.
• Example schema query: station:|sys:|neql:n:point|bql:select name, out.value, out.
status
14 December 9, 2019
• Example schema base query: station:|sys:|neql:n:point|bql:select *

• Subscription to the remote points works so that change of value is available, as is the parent name and
original slot path of the points.
• You cannot use a system database ord for a specific point binding.
• This option is not suitable for export of alarms and histories.
NiagaraNetwork schema export

The schema runs locally on each controller and is linked to a StringWritable. This writable point is then
imported into the Supervisor and linked to remote transport.
• It makes sense to do the processing at the data source where full point fidelity is available.
• The framework deals with permissions locally at each station.
• You have full alarm and history support.
• Linking the imported StringWritable to a transport, such as MQTT, keeps the point subscribed.
Proxy
If you are using MQTT as your transport, you may set up an intermediary broker to proxy messages to the
remote broker. This solution requires extra IT overhead and support.
December 9, 2019 15
16 December 9, 2019
Chapter 2 Exporting with a JSON
schema
♦ Config folder
♦ Tuning policy
♦ Overrides
♦ Debugging errors (Schema History Debug)
♦ JSON schema metrics
♦ Schema construction
♦ Queries
♦ Alarms
♦ Exporting schema output (JsonExporter)
♦ Exploring the examples
Adding a JsonSchema component to your station allows for the construction of a JSON payload to suit the
requirements of your particular application.
Overview
There are examples in the j s o n T o o l k i t palette, which may help with learning how to construct a schema. You
can simply drag the JsonExampleComponents and Schemas folders into a running station to work with
them.
F ig ure 5 Schema parts
You construct a schema by placing “entities” from the j s o n T o o l k i t palette below a JsonSchema in the
station and then use configuration properties and queries to get the output you want. Use the numbers in
the screen capture to learn about schema elements:
1. You can give each schema a unique name.
2. The Output property contains the resulting JSON payload (message or string).
December 9, 2019 17
Chapter 2 Exporting with a JSON schema Niagara JSON Toolkit Guide
N O T E : The format of this black box (with new lines and spacing) is purely for presentation. The actual
string output is minified and does not contain extra spaces.
3. The Enabled property turns the generation of output, execution of queries and subscription to bound
values on and off. The Config folder contains properties that configure general schema attributes.
4. The Queries folder can contain query entities to insert bql, historical or alarm database content into a
payload.
5. A { } root object or an [ ] array contains JSON entities that structure the Output message. Some
entities may be simple—for example braces { } represent a simple JSON object, while other entities
represent Niagara bql queries (refer to the Niagara Developer Guide) and, therefore, have the potential
to be more complex.
6. Actions build and manage schema contents. The Generate action builds and updates schema output.
For relative schemata, Generate evaluates the base query and publishes the results for each resolved
base item.
What can a Schema contain?
The schema supports a nested structure of child entities. These can be Objects, Arrays, or Properties of
various types. Niagara alarm, history or point data may populate these entities, which include:
Entity Type Output

Object “objectName” :{"name” : value, “name2” : value2….}
Array “arrayName” :[value, value2….]
Property “key”: value
Property List “key”: value, “key2”: value2
All entities (minus Property) support nested child entities. This lets you build a schema using a tree structure
with entities found in the j s o n T o o l k i t palette.
Wha t st ru c tu re is al lo we d?
Every schema requires a root member that is allowed by the JSON standard: this means an object { } or an
array [ ].
Fi gu re 6 root Json Schema Object
The screen capture shows how Niagara represents a JSON root object in a standard P r o p e r t y S h e e t view.
Config folder
The JSON Toolkit provides several options to help you create consistent naming and formatting. The root
properties in each schema’s C o n f i g folder provide these consistency properties.
The schema C o n f i g folder is separate from the station C o n f i g folder and applies only to the parent schema.
18 December 9, 2019
Niagara JSON Toolkit Guide Chapter 2 Exporting with a JSON schema
F ig ure 7 Config properties
• Name Casing Rule conforms names to camel case or another style.

• Name Spacing Rule defines a character to insert between words in a name, such as a space, hyphen,
underscore, etc.
• Date Format Pattern configures dates.
• Numeric Precision configures the number of decimal digits to show on exported floating point num-
bers, values are rounded. Point facets are not used.
• Use Escape Characters turns on and off the use of escape characters around symbols that otherwise
would have special meaning. For example, when false, $20 becomes a space character.
The “Components” chapter documents the options for these properties.
Tuning policy
Most tuning policies properties are explained by the Niagara Drivers Guide.
Tuning properties provide rules for evaluating when JSON outputs data and for indicating an update strat-
egy. Configuring this policy can affect system performance. They are located in the Schema C o n f i g folder.
F ig ure 8 Tuning policy properties
Update Strategy determines when JSON string generation occurs: at change-of-value or on demand.
There is a built-in Min Write Time to ensure that hundreds of concurrent CoV changes over a short time do
not result in a deluge of JSON messages. For example, when set to five (5) seconds and a change-of-value
occurs within five seconds of the last change of value, schema generation defers for a full five seconds. How-
ever, if this amount of time exceeds the Max Write Time setting, the system forces schema generation. In
contrast, Max Write forces an update after the specified interval.
N O T E : A Force Generate Json action overrides all tuning policy settings.
Export markers applied to numeric points also have a CoV Tolerance property which can be used to throt-
tle output.
The Write On Start and Write On Enabled properties provide other ways to invoke schema generation,
for example, when the station starts.
Overrides
An O v e r r i d e s folder is a standard container under the JSON C o n f i g folder.
December 9, 2019 19
This folder adds a TypeOverride component to the schema, should it be necessary to override how the
schema converts specific datatypes to JSON. The override applies to anywhere the system encounters the
data type in the entire schema. Examples might be:
• replacing Facets with a locally-understood value, such as ‘degC’ to ‘Celsius’
• defining a different format for simple types, such as Color and RelTime
• managing expectations for +/- INF in a target platform
For further information, refer to the “Type Override Example” in the “Developer Guide” chapter of this
document.
Deb u gg i ng er ror s ( Sc he m a H i st or y D eb ug )
When output updates rapidly, such as when a link calls a generate JSON action in quick succession or a rela-
tive schema quickly changes output once per base item, it may be useful to view the most recent output his-
tory. This task describes how to view the output history.
P r e r e q u i s i t e s : You are viewing the Property Sheet for the schema.
Step 1 Do one of the following:
• Click the O u t p u t H i s t o r y button to the right of the Output property on the schema.
• Expand the schema’s C o n f i g → D e b u g folder, right-click the S c h e m a O u t p u t H i s t o r y D e b u g
slot, and click V i e w s → S p y R e m o t e .
The S c h e m a O u t p u t H i s t o r y D e b u g view opens.
The History Size allows you to store more but be careful not to fill memory with JSON strings.
Step 2 To configure the amount of debug data stored in the station, expand the S c h e m a O u t p u t H i s t o r y
D e b u g folder and configure the History Max Size property.
It is a good idea to reduce this value once you have finished debugging.
JSON schema metrics

Metrics expose schema generation, query execution and CoV subscription data. You can log this informa-
tion, link it, and use it to generate alarms.
Fi gu re 9 Schema metrics
These help with sizing and provisioning capacity from a cloud platform by estimating the traffic a station is
likely to generate with a given JSON schema. They may also assist in identifying performance problems. De-
bugging can be assisted by using the reset action.
The metrics provide three categories of performance information: query performance, generate perform-
ance, and subscription performance.
20 December 9, 2019
Queries Generation Subscription
Query Folder Executions Request Schema Generations Subscribes
Individual Query Executions Schema Generations Unsubscribes
Query Fails Schema Generation Fails Subscription Events
Last Query Fail Reason Last Schema Generation Fail Reason Subscription Events Ignored
Last Query Execution Millis Output Changes Cache Hits
Query Execution Millis Total Last Output Size Cache Misses
Query Execution Millis Max Output Size Total
Query Execution Millis Avg Output Size Max
Output Size Avg
Resolve Errors
Schema construction
Setting up a schema involves binding station data to JSON entities.
Binding configuration, about binding

Bound properties, objects and arrays are JSON entities, which can use the current values of an ord target to
render their values. Fixed variants do not support binding.
Slot selection
When picking a bound object or array, you may choose which slots from the target to include in the resultant
JSON container. Currently the options are:
F ig ure 10 Slots to include
• All slots
• All visible slots (hidden slots excluded)
• Summary slots—only those with a summary flag
• Selected slots—manually-selected slots from a list
T a rg e t t y p e s
N O T E : When choosing the bind target for a binding you could select any type of slot, from devices to con-
trol points to out slots to simple values, there are no restrictions.
Bound arrays and objects output the value of each of the selected slots (refer to Slot Selection, page 21).
The default behaviour for each encountered slot type is as follows:
Selection Output
Strings The string value is unchanged
Booleans A JSON Boolean
December 9, 2019 21
Selection Output
Integer/Long A JSON number
Double and float decimals A JSON number rounded to use the schema’s decimal places config
Enum value A JSON String that represents the Enum value
AbsTime A String representation of the date formatted as per the schema config
Control Point A JSON String, Numeric, Boolean, or Enum to represent the out slot’s value
Status Value A JSON String, Numeric, Boolean, or Enum to represent the value
Status A JSON string to represent the value, for example, {ok}
Anything else The string representation of the value as returned from the framework. This is often the
type display name.
N O T E : Bound objects and arrays do not recurse. Only direct child slots are included. These behaviours make
a few assumptions about the most-expected case, for example, excluding the status string from certain
types. Program overrides may override all these behaviours.
Naming
For binding results you may choose what the key is in the key/value pair:
Selection Output
Display Name The name of the bound property, object or array
Target Name The name of the ord target
Target Display Name The display name of the ord target
Target Parent Name The name of the ord target’s parent
Target Path The absolute path of the target from the root of the component tree
T I P : You may use a Tag property with the name n:name to include point names. This property inserts a sin-
gle tag value from the bound component in the output. If the SearchParents property is true, the frame-
work searches up the hierarchy for the closest component with a matching tag id (if the tag not found on
binding target.
Entities
Entities are objects, arrays, properties and bound properties.
Objects
Objects are entities used to create containers in the JSON message and identify slots in a target ord.
• A JSON schema Object inserts into the schema an empty named container ({ }) for holding other sche-
ma entities.
• A BoundObject is a named JSON object whose child name and value pairs are the slots within a target
ord.
22 December 9, 2019
F ig ure 11 A Json Schema Bound Object
Arrays
Arrays contain a list of values. They do not include names.
• A JSON schema Array inserts into a schema an empty named container ([ ]) for the purpose of holding
other schema entities.
• A JSON schema BoundArray is a named JSON object that renders values as a list.
Fi xe d prope r ti e s
Fixed Properties are hard-coded name and value pairs, which you always want to appear as constants in
the JSON string. You can link to these if the value is expected to vary. The next generation event, triggered
by a CoV on a bound entity or by the invocation of the Generate action, includes the current value. A
change in the value of any fixed property does not trigger a CoV generation event in the same way that a
bound equivalent does.
• A FixedString property inserts a string value.
• A FixedNumeric property inserts a numeric value.
• A FixedBoolean property inserts a Boolean value.
Bou nd prope r t ie s
A bound property inserts the current value of the object specified in the binding.
December 9, 2019 23
Fi gu re 12 Bound properties
BoundProperties include:
• A BoundCSVProperty is a named JSON string that renders child slots as a string, comma–separated list
with no surrounding [ ] or { }.
• A Tag property is a list of name and value properties based upon selected tags found on a binding tar-
get. If the tag is not found on the binding target, andSearchParents is true, the framework searches
up the hierarchy for the closest component with a matching tag id.
• A TagList is a list of name and value property pairs that are based upon selected tags found on a bind-
ing target. A comma-separated list specified in the Tag Id List Filter property can limit the tags to
be included in the output. Example: n:name, n:type or * for all. If Include Namespace is true, the
tag dictionary prefix is added to the key (for example, the hs: is added to hvac to give: hs:hvac).
NOTE:
Facet and Tag properties are not bound like the other bindings, in that changes of value do not prompt
schema generation. The current value is retrieved from the station when the schema generates.
Fi gu re 13 Json Schema Tag List
• A Facet property inserts a single facet value from a bound component into the schema output, for ex-
ample, the units of the current point.
• A FacetList inserts a list of name and value facet properties based on a comma-separated list or * for
all. Add facet keys as follows: units, mix, max
• Message properties
24 December 9, 2019
F ig ure 14 Message properties
• A Count property is a named numeric value, which increments by 1 on each schema generation. Could
be used for message IDs.
• A CurrentTime property inserts the current time as set up in the C o n f i g folder’s Time Format
property.
• UnixTime property inserts the current time in Unix time as seconds from January 1, 1970.
Crea tin g a reg ul ar sc hem a

You construct a schema by placing objects from the jsonToolkit palette in a JsonSchema.
P re re q u i s i t e s : The station is running.
Step 1 Open the jsonToolkit palette from the workbench palette sidebar.
Step 2 Drag a JsonSchema to the C o n f i g node or another desired folder location and type a unique
name for the schema when prompted.
Step 3 To view the schema P r o p e r t y S h e e t , double-click the schema glyph in the Nav tree.
The P ro p e r t y S h e e t opens.
December 9, 2019 25
When you initially view the P r o p e r t y S h e e t for a new schema, the Output property is an empty
black box. JSON strings appear here when you generate output.
Step 4 In the P r o p e r t y S h e e t view, ensure that the Enabled property is set to true.
Setting Enabled to false prevents the generation of output, the execution of queries and the
subscription to bound values.
Step 5 To begin setting up the message, expand the O b j e c t s folder in the palette, drag an O b j e c t to the
P r o p e r t y S h e e t and name it, for example, root.
Braces { } represent this object in the Output. This single top-level object serves as the JSON pa-
rent container for other JSON objects that make up the message. Each JSON object requires a pair
of braces ({ }) and arrays require brackets ([ ]).
Step 6 Drag an object, array, or property from the palette to the P r o p e r t y S h e e t root container.
Some objects may be simple and other objects may yield the more complex results of Niagara bql
queries. The objects that you choose to add depend on your unique requirements.
• Empty braces { } icons represent a JSON object. A bound object is a named object whose child
name and value pairs are the slots within an ord target.
• Bracket [ ] icons represent an array, which is an empty named container of other schema enti-
ties. A bound array is a named object that renders values as a list.
• Other icons represent properties, which may be fixed or bound.
Step 7 To update the schema Output based on the current values retrieved from the station, click G e n e r-
a t e , or right-click the schema name and click A c t i o n s → G e n e r a t e J s o n .
This action causes a regular schema to re-evaluate any query and populate the Output box with
JSON.
Step 8 To set up some actual station data, drag in a BoundObject, name it appropriately, expand the
bound object and click the Select Source finder to the right of the Binding property.
This object requires a binding similar to the way components on Px pages require bindings to ac-
tual points in a station.
The C h o o s e c o m p o n e n t / s l o t f o r J S O N window opens.
Step 9 Navigate to and select the source component, click O K and then click S a v e .
26 December 9, 2019
When choosing the target for a binding, you can select any type of slot, from devices to control
points to out slots to simple values. There is no restriction. Due to subscription, saving the schema
also generates the JSON message (output).
If your logic contains one or more points whose values change periodically, the schema generates a
new JSON message every time a CoV occurs. If the schema is connected to MQTT, the schema can
send each new message to the web.
Step 10 To change the Json Name (a read-only property) to the name of the bound input slot on your W i r e
S h e e t , change Json Name Source property to Target Name, and, from the Slots To Include
property, choose Summary Slots.
To include specific slots, use the Slots to Include properties, identify and pick individual slots
for more fine-grained control.
You may link the output slot to an EngineCycleMessageQueue, if required, which buffers output sent to
the onward transport. These could be MQTT or HTTP depending on the onward linked point.
Relative schema construction

A relative schema enables the scaling of JSON payload generation and much faster engineering than abso-
lute object binding.
The type of schema discussed thus far uses only absolute ords. In situations with many points, absolute ords
could limit scalability. One schema per point or device would not be an efficient way to proceed. In the same
way that relative ords in graphics enable efficient engineering with the Niagara framework, a relative schema
provides easier scaling for an existing station and also requires no changes to the JSON when adding new
components and points.
A base query feeds base components to the schema, which the query resolves against the schema one at a
time. In this manner it is possible to select, for example, all BACnet points in a station and output their name,
status and present value for export to the cloud. If an engineer adds an extra device to the BACnet network
in the future, the base query can automatically include it in the data exposed by the station, if the query
allows.
Alone, a relative schema can select data to export or, when combined with an Export Marker, it can send on-
ly recent history or publish only when a set tolerance value is exceeded. Further still, you can move points
between schema based on their status. You might have one schema that sends verbose point data and an-
other with simple latest values once you add an export marker.
December 9, 2019 27
N O T E : A best practice is to limit the scope of the base query to a subset of points in the station and limit
the frequency of JSON message generation. Very frequent payload generation could degrade station
performance.
Base query examples

This base query would return all the overridden points beneath the D r i v e r s container:
slot:/Drivers|bql:select * from control:ControlPoint where status.overridden = 'true'
This query returns all points with the Haystack marker tag, hvac:
slot:/|neql:n:point and hs:hvac
The base query’s Publish Interval causes the base query to be re-executed periodically and triggers a
complete publish output (of every returned component) at the interval selected.
Invoking the Generate action on a relative schema evaluates the base query again.
C A U T I O N : Do not include the schema output itself in the base query. This will quickly consume available
Java heap memory!
Export markers
Export markers on points and other entities set up efficient data retrieval.
Exp ort ma r ke r : se le ct i ng co nt rol poi nt s

You select control points to export using:
• Absolute ord bindings in a standard schema
• Bql or neql in a relative schema
• by adding an export marker to a component.
JSON export markers offer several benefits beyond just marking points to include in a relative schema. For
example, you can use it to limit the export of alarm or history data related only to points with an export
marker present. It can also store a unique identifier supplied by a third party platform. This can allow you to
differentiate among registered points with an ID and unregistered points without an ID. An example use
case is sending different payloads prior to registration including more detailed information (units, min/max,
descriptive tags) than should be sent upon every change of value. When applied to a numeric point an ex-
port marker introduces a CovTolerance property to reduce unwanted updates from the station if a value
changes only slightly. You can also use an export marker with incoming JSON payloads.
Here are some examples of relative schema configuration.
• Base Query: station:|slot:/|bql:select * from jsonToolkit:JsonExportMarker
• Example bound property binding ord: slot:.. (References the parent of the JsonExportMarker
base)
Export marker filters
Both filters below have a Send Since action, which allows alarms or histories since a given date to be ex-
ported. This feature might be useful following network disruption or during initial commissioning of a
system.
The Send Since action allows you to specify a start time. The linked schema considers only records stored
on or since this time for output.
Two common filter properties are:
• Current Export Id includes a description of the export marker if it is linked to a fixed string in the
schema.
• Count reports how many export-marked points were processed in the last invocation. It resets when the
station restarts.
28 December 9, 2019
Alarm export marker filter

This filter selects specific alarms a station generates before the station passes them to a recipient. Typically,
the recipient would be a JSON alarm recipient, but it could be SNMP, BACnet, etc. with the source alarm
class linked to the In slot of the filter.
In the context of alarming the filtering occurs normally on alarms passed from the alarm class as they are
generated.
F ig ure 15 Wire Sheet showing the use of an export marker filter
Filter mode Outputs alarms
Marked With Id If the source has an export marker present, with Id set
Marked If the source has an export marker present
Pass All All alarms
Block All No alarms
In the context of alarming, the filtering occurs normally on alarms passed from the alarm class as they are
generated.
The Send Since action queries the alarm database and passes existing records in to this filter (inclusive of
the supplied timestamp) so that they can be checked for a suitable export marker and then passed to the re-
ceiving schema as required to create a new record for each alarm. The timestamp, being in the past, should
help identify when this mode is active.
NOTE:
To prevent an accidental data deluge, Send Since does not function if the filter is in Pass All mode. A bql
query on the alarm database could be used if this is a requirement.
History export marker filter
This filter exports history data for points with an export marker.
The filter overlaps somewhat with the relative history query, which can select history for points using many
different selection criteria, or an appropriate base query may also be used to generate history for each ex-
port marked point. The HistoryExportMarkerFilter allows updating of the timestamp stored on each
export marker so that only recent history records are sent to the remote system (typically, records added
since the last export).
The schema nested under the filter determines the payload format. To complete the export, link the output
from that schema to a target transport point.
If one does not exist already, the HistoryExportMarkerFilter adds a new query to the Queries folder
of the schema. This query needs to be referenced by a BoundQueryResult.
In the event that an export-marked point has more than one history extension beneath it, the schema ex-
ports each extension in turn.
In most cases, it is likely the Current Export Id property needs to be linked into the schema output to
provide identifying information, or even the query used to select data may be included if the target system
could infer useful data from it.
N O T E : Because the export marker relies on being added to a local control point in the station, it is not pos-
sible to match histories imported over BACnet or NiagaraNetwork using this method. Use a relative schema
instead.
December 9, 2019 29
Use the Send Since Last Export action to send only unsent history data using the timestamp stored on
each export marker.
These are some important filter properties:
• History Export Filter is the schema that produces the output.
• Current Query identifies the query fed into the schema below. The first query in the Q u e r i e s folder is
linked on start, does not have to be the only query, and is output first by the schema.
• Columns sets up comma-separated values, for example, timestamp, value, status.
• Update Send Since Time determines if the schema updates most recent send time when the schema
generates data and enables sending only changed records on the next run. If true, every time the sche-
ma exports history it updates the timestamp stored on each export marker.
Queries
Queries search the station database for the data to include in a schema.
Query folder
The Q u e r i e s folder of a JSON schema stores queries whose results are available to be used in the schema.
This allows JSON content to be generated from the results of bql or neql queries. For example, to name just
a few, you can generate a report of overridden points, active alarms, or history logs for a given point.
Query Interval is an important property of the queries folder. It determines how often queries execute,
and, therefore, how up-to-date any data exported by the schema will be when an update strategy of CoV is
used.
N O T E : If multiple queries exist, the station runs each query in parallel each time the schema executes.
Queries do not execute each time a schema generates in change-of-value mode, otherwise a query could
run every time a point value changes, which could have a negative impact on the performance of the control
strategy running in a station. Instead, a BoundQueryResult caches the results and adds them to the
schema.
Schemata in on-demand mode and relative schemata do execute each query every time a schema
generates.
It is possible to manually invoke query execution using the Execute Queries action of the schema, which
could also be linked to some appropriate logic to trigger execution when needed.
IMP O RTAN T:
When executing queries against your station, bear in mind the potential performance implications of running
queries frequently. To reduce the scope of the query, focus the first part of the ord to the location where the
data are likely to be found, or by using the stop keyword to prevent depth recursion.
Query
You add queries below the Q u e r i e s folder found at the top level of the schema.
Fi gu re 16 Query properties
A query can be any valid transform, neql or bql statement which returns a BITable.
Here are some useful examples to include in a schema:
30 December 9, 2019
D a t a t o re t u r n Query
BACnet points currently in {override} status slot:/Drivers/BacnetNetwork|bql:select name, out.value from

control:ControlPoint where status.overridden = 'true'
History records history:/Newhaven/waveHeight|bql:select timestamp, value
Output from a series transform station:|transform:slot:/VelocityServlet/lineChart/

TransformGraph
Alarm database contents alarm:|bql:select timestamp, uuid, ackState, source as

'origin'
NOTE:
You may rename the columns using the ‘as’ keyword, which the resultant
JSON reflects.
Relative history query

Used in conjunction with a relative schema, the query Pattern Property pre–appends the current base
item to a bql query, so that query data can be included in the payload for a given set of points or devices:
%baseHistoryOrd%?period=today|bql:select timestamp, value
You may use this in conjunction with a base query that returns a HistoryConfig or a HistoryExt (or the parent
of these types):
station:|slot:/JsonExampleComponents|bql:select * from history:HistoryConfig
Consider the effect on performance that running many queries on an embedded controller may have.
BoundQueryResult
Once you define a query, use the BoundQueryResult to determine where and how to insert the results into
the payload.
You can mix query results, such as bound properties or other query results with all other schema member
types in the same payload. For example, if required by the target platform, you could construct a floor sum-
mary with historical data and current alarms.
The JSON Toolkit provides various output formats as the following examples demonstrate, and a developer
can create new output formats.
The following examples use two columns for the sake of brevity. You may add more columns.
You can format the timestamp returned by a query using the format options in the schema’s C o n f i g folder.
REMEMBER:
Executing a bql query does not trigger subscription of the component in question. The values used are the
last values known to the station.
December 9, 2019 31
Example JSON
Row array with header

"data": [
[
"timestamp", "value"
], [
"2019-02-07 23:27:42.116+0000",
45
], [
"2019-02-07 23:28:03.157+0000",
15
], [
"2019-02-07 23:28:24.197+0000",
85
], [
"2019-02-07 23:28:45.222+0000",
55
], [
"2019-02-07 23:29:06.247+0000",
25
]
]
Row array
"data": [
[
"2019-02-07 23:27:42.116+0000",
45
], [
"2019-02-07 23:28:03.157+0000",
15
], [
"2019-02-07 23:28:24.197+0000",
85
], [
"2019-02-07 23:28:45.222+0000",
55
], [
"2019-02-07 23:29:06.247+0000",
25
]
]
Objects array
"data": [
{
"timestamp": "2019-02-07 23:27:42.116+0000",
"value": 45
},
{
"timestamp": "2019-02-07 23:28:03.157+0000",
"value": 15
},
{
"timestamp": "2019-02-07 23:28:24.197+0000",
"value": 85
},
{
"timestamp": "2019-02-07 23:28:45.222+0000",
"value": 55
},
{
"timestamp": "2019-02-07 23:29:06.247+0000",
"value": 25
}
]
Named objects (The first column is as-

sumed to represent the object name.) "data": [
"2019-02-07 23:27:42.116+0000": {
"value": 45
},
"2019-02-07 23:28:03.157+0000": {
32 December 9, 2019
Example JS ON
"value": 15
},
"2019-02-07 23:28:24.197+0000": {
"value": 85
},
"2019-02-07 23:28:45.222+0000": {
"value": 55
},
"2019-02-07 23:29:06.247+0000": {
"value": 25
}
]
Column array with header

"data": [
[
"timestamp",
"2019-02-07 23:27:42.116+0000",
"2019-02-07 23:28:03.157+0000",
"2019-02-07 23:28:24.197+0000",
"2019-02-07 23:28:45.222+0000",
"2019-02-07 23:29:06.247+0000"
], [
"value", 45,
15,
85,
55,
25
]
]
Column array
"data": [
[
"2019-02-07 23:27:42.116+0000",
"2019-02-07 23:28:03.157+0000",
"2019-02-07 23:28:24.197+0000",
"2019-02-07 23:28:45.222+0000",
"2019-02-07 23:29:06.247+0000"
], [
45,
15,
85,
55,
25
]
]
Single column array

"data": [
N O T E : The query used to populate the 45,
BoundQueryResult should only return 15,
one column. It would be wasteful to se- 85,
lect data that are not expected to 55,
emerge in the payload. 25
]
Tuning
You may use the hidden query folder property queriesMaxExecutionTime to in-
crease the amount of time granted to complete all the queries during each cycle.
Failure to complete in this time causes schema generation to fail.
Setting up queries
In addition to the binding queries, which set up a single query bql, neql or ord, you can add additional
queries to a Queries folder. The schema turns the queries in this folder into a string.
Step 1 Create a regular schema.
December 9, 2019 33
The example above uses the points of a BACnet device. This JSON configuration includes the
Queries folder and the root object container for the schema.
a. Identifies the regular queries that define the source of the data for binding. In this example, the
query uses bql to identify the data.
b. Identifies a query that can become a JSON string. The query result injects the query referenced
from the Queries folder into the point in the schema output. You can nest these queries any-
where within your JSON message.
By default, each schema includes a Q u e r i e s folder, which comes with two properties: Query In-
terval (to configure how frequently to execute the query), and Last Query Completed
Timestamp.
Step 2 To configure the Query Interval, right-click the Q u e r i e s folder, click V i e w s → A X P r o p e r t y
S h e e t , configure the interval, and click S a v e .
Step 3 To add an ad hoc query to the schema, expand the Q u e r y node in the palette, drag a Q u e r y from
the palette to the Q u e r i e s folder in the schema, double-click the Q u e r y, enter the Query Ord, and
click S a v e .
For simplicity, the example Queries folder contains a single query. It could contain additional
queries.
A above identifies the ord for the single ad hoc query (BacnetQuery): station:|slot:/Driv-
ers/BacnetNetwork/MyName|bql:select name, proxyExt.objectId, out.value AS
‘v’, status from control:ControlPoint
This query searches a particular BACnet device for the name, object ID, current value and status of
all points under the device. The Last Result Size property indicates that the query finds two
points.
Step 4 To create a bound query result, expand the Q u e r y node in the palette and drag a B o u n d Q u e r y R e -
s u l t from the palette to the root object in the schema.
In the example, the bound query result (identified by the second box) references the query (Bac-
netQuery) and defines the Output Style to render the query in.
Step 5 To update the payload message, click the G e n e r a t e button.
The result of running the example query looks like this:
34 December 9, 2019
F ig ure 17 Device connectivity JSON payload
The first group of name and value pairs reports the result of the main binding query (under config). The data
block at the bottom shows the result of the ad hoc query in the Q u e r i e s folder. The data block displays as
an object array identified by the square brackets. The array contains one object per BACnet point, in this
case two objects, each inside a pair of braces.
This example could have used a relative schema. Which one to use depends on your requirements. Does
your API need all data in a single JSON message or does it require one message per point? This procedure
does not subscribe to the component model. It runs a bql query to populate the BITable and encodes that
data. The power of bql to select data feeds into the input to the schema the same as you could feed a series
transform into this schema, query the historical alarm data, or query history data.
This type of query configuration does not have to be done with device points. By “query” in this context, we
mean anything that returns a BITable so you could use a transform ord, bql on the history space or neql on
the component space. Any time you have something you can feed to the ReportService you can encode and
output it with a schema.
Alarms
The JsonAlarmRecipient exports alarms using the recipient’s schema.
AlarmRecipient
Linking the alarm topic of an alarm class into the route action of a JsonAlarmRecipient triggers the gen-
eration of a new payload each time the alarm class receives an alarm.
The JsonAlarmRecipient comes with a nested schema whose payload output depends on the alarms
passed through from the parent recipient.
December 9, 2019 35
Queries, bound objects and arrays, and/or properties can include present value data from the station in the
payload.
There are, however, some alarm-specific data types you can include, notably the properties from a Niagara
Alarm Record: BAlarmRecord
By including the unique identifier in an outgoing message, an inbound payload can acknowledge alarms.
A l a r m R e c o rd P ro p e r t y
Only the JsonAlarmRecipient’s schema supports these alarm-related properties. Adding each of these
to the schema allows inclusion of the selected alarm property in the output.
For example, the sourceState, uuid, alarmClass etc. As with other schema properties the name is deter-
mined by renaming the property, for example AlarmRecordProperty becomes timestamp.
BF orma t Prope rt y
This property defines the alarm data to be extracted from the Niagara alarm database. For example, if an en-
gineer used the Metadata property of an AlarmExt to record the location of a point in the building, this
could be fetched using alarmData.location to include in the payload.
E x p o r t i n g a l a r m re c o rd s t o t h e J s o n A l a r m R e c i p i e n t
This component comes with a nested schema whose payload output depends on the alarms passed through
from the parent recipient.
You may include queries, bound objects or arrays, and properties to return a station’s present value data in
the payload. You may also include some specific alarm data types, notably the properties from the alarm re-
cord: BAlarmRecord.
Step 1 Drag the JsonAlarmRecipient to the W i re S h e e t .
Step 2 Connect the Alarm Class to the Route Alarm action on the recipient.
Linking the alarm class to the route action of a JsonAlarmRecipient component triggers the
generation of a new JSON payload each time the recipient receives an alarm from the alarm class.
Step 3 Add an AlarmRecordProperty component to the schema and select one or more properties.
36 December 9, 2019
Each property you add to the schema can include selected alarm data in the output, such as the
sourceState, uuid, alarmClass etc. As with other JSON schema properties, you can rename the
property; for example “AlarmRecordProperty” can be renamed to “current value”, as shown
above.
Step 4 To filter out unwanted alarms before sending data to the alarm recipient, add the AlarmExport-
MarkerFilter to the W i r e S h e e t and connect it as shown below.
Normal filtering occurs on alarms passed from the alarm class to the recipient as the station gener-
ates the alarms.
December 9, 2019 37
The Send Since action queries the alarm database and passes existing records to the filter (includ-
ing the supplied timestamp). The system checks the records for a suitable ExportMarker, and
passes them to the receiving JsonSchema to create a new record for each alarm. Since the time-
stamp is in the past, the filter should be able to identify when its mode was active.
NOTE:
To prevent accidental data deluge, Send Since does not function if the filter’s Mode is set to Pass
All. You could use a bql query on the alarm database if this is a requirement.
Exporting schema output (JsonExporter)

The JsonExporter creates a file with the current output of the schema you are viewing. You could use this
feature with the ReportService to export on a regular basis, perhaps via file, email, ftp or HTTP for a machine
learning application or similar application.
Step 1 To export current JSON data, either click the E x p o r t button ( ) or click F i l e → E x p o r t
The E x p o r t window opens.
Step 2 Select the exporter and where to view.

Step 3 To export to a file, you may click the B r o w s e button to locate the file.
A URL like the following also allows access to the schema output via the JsonExporter:http://
127.0.0.1/ord/station:%7Cslot:/JsonSchema%7Cview:jsonToolkit:JsonExporter
This means that using a web client you can easily query the data in a station over HTTP.
Exploring the examples

The JSON palette includes several examples you can explore to learn how schemata work.
P r e r e q u i s i t e s : You are connected to a running station. The jsonToolkit palette is open.
Step 1 Expand your S t a t i o n → C o n f i g and double-click the C o n f i g node.
Step 2 Expand the E x a m p l e s node in the palette.
Step 3 Select the two folders: JsonExampleComponents and Schemas and drop them into the C o n f i g
node of your station.
38 December 9, 2019
The examples folders must be at the root of the station Config component for them to work
correctly.
The screen capture shows the example folders in the station C o n f i g folder.
Step 4 To view the components, double-click the J s o n E x a m p l e c o m p o n e n t s node.

The W i r e S h e e t opens to reveal two folders with points.
Step 5 Double-click the P o i n t s folder.

The W i r e S h e e t opens the P o i n t s folder.
December 9, 2019 39
This folder includes a Ramp that is updating.

Step 6 To view the sample schemata, double-click the S c h e m a s folder in the Nav tree.
The W i re S h e e t opens with nine example schemas.
There is a basic example with bindings. Another that runs a query. There is a relative schema. Along
the bottom are examples of how to apply a schema to a practical job. For example, there is are for-
mats for communicating with an IBM cloud and the Sparkplug standard.
Connecting a device
This procedure uses an example to demonstrate how to connect a device. The example sets up a relative
schema to look for all folders in the station that have a particular tag, such as “lights,” “sensor,” etc.
Step 1 Set up writable points in the station folders and connect them to the source points.
Step 2 Drag a relative schema to a logic W i re S h e e t .
Step 3 Set up a base query to locate the point values.
40 December 9, 2019
For example: slot:/Hue|neql:n:light (assuming a “light” tag has been applied to the point’s
parent folder).
Step 4 Specify the binding.
For example: slot:
The Output property displays the JSON message payload.
Step 5 Drag an E n g i n e C y c l e M e s s a g e Q u e u e to the W i r e S h e e t .
Step 6 On the W i r e S h e e t , link the R e l a t i v e J s o n S c h e m a ’s Current Base And Output to the Enqueue slot
of the queue.
Step 7 Post the output from the program to HTTP.
Vis ual i za tion

Generating the data for a graph uses the JSON queries. For example, you could use a JSON message to
embed a chart in a web page.
The screen capture shows a JSON message that serves as the source for rendering a chart in a web site.
F ig ure 18 JSON message for Google chart data
This shows all the square brackets of several arrays with values. The JSON that generates this payload
queries the history for a particular ramp in a station:
history:/json/Ramp|bql:select top 5 value
This is another (different) example of a schema and the JSON message that creates its chart.
F ig ure 19 JSON schema and output
Gold (orange) identifies the basic Query ord. The block identified by the green box and arrow (data) is the
bound query result. The resulting graph looks like the following on a web page.
December 9, 2019 41
Fi gu re 20 Charts created by JSON messages
42 December 9, 2019
Chapter 3 Importing JSON
♦ Routing complete incoming messages
♦ Routing part of a message
♦ About the Json Path selector
♦ Handlers and alarm acknowledgments
♦ Setpoint handler and writing to points
♦ Export setpoint handler and export registration
Data coming into a station can be used to modify a setpoint or execute some other action. A handler
processes imported JSON.
Routing complete incoming messages

A JsonMessageRouter component directs a whole incoming message (payload) to a new slot so that in-
coming messages may redirect the JSON to be handled by another component, such as a “handler” compo-
nent type.
Step 1 Open the jsonToolkit palette, expand I n b o u n d → R o u t e r s and drag a JsonMessageRouter com-
ponent to a working folder in the station.
Step 2 Open the router Property Sheet by double-clicking the JsonMessageRouter component.
Step 3 Type a value in the Key property to identify the type of message (for example: messageType) and
click S a v e .
Enabling Learn Mode adds a dynamic slot on input. This procedure documents how to add the slot
manually.
Step 4 Manually add a dynamic string slot to the router component by opening the A X S l o t S h e e t view,
or by simply right-clicking the sheet and clicking A d d S l o t .
An A d d S l o t window opens for either method, as shown below.
A d di n g a s l o t f ro m t h e S l o t S h e e t Vi e w Adding a s lot using the Action menu
December 9, 2019 43
Chapter 3 Importing JSON Niagara JSON Toolkit Guide
Step 5 Give the slot a name, use the transient and read-only flags to avoid onward handlers running again
at station start and click O K .
The new slot is added.
Step 6 On the Wire Sheet, connect the router.

The following Wire Sheet routes the entire incoming message to the dynamic slot for onward
processing:
For example, if Key = messageType, the JSON routes this message to a string slot with a name
“alarmAck” and then on to connected handlers, as shown above.
{
"messageType": "alarmAck",
"user": "AJones",
"alarmId": [ "5cf9c8b2-1542-42ba-a1fd-5f753c777bc0" ]
}
Routing part of a message

A JsonDemuxRouter directs a subset of an incoming message (payload) to a new slot so that links may redi-
rect the JSON to be handled by another component. This procedure provides an example of routing part of
a message.
P r e r e q u i s i t e s : The following instructions assume that you have an incoming message (payload) with the fol-
lowing key value pairs: “hue”, “sat”, “bri”, “on”.
{
"hue": 43211,
"sat": 254,
"bri": 254,
"on": true
}
Step 1 Open the palette, expand I n b o u n d → R o u t e r s and drag a JsonDemuxRouter component to a de-
sired location in the station.
Step 2 Open the JsonDemuxRouter’s P r o p e r t y S h e e t by double-clicking the router.
The property sheet view displays.
44 December 9, 2019
Niagara JSON Toolkit Guide Chapter 3 Importing JSON
N O T E : Enabling Learn Mode adds a dynamic slot on input. This procedure documents how to add
the slot manually.
Step 3 Manually add a baja:double slot by opening the A X S l o t S h e e t view, or by simply right-clicking the
sheet and clicking A d d S l o t .
An A d d S l o t window opens for either method, as shown below.
A d di n g a s l o t f ro m t h e S l o t S h e e t Vi e w Adding a s lot using the Action menu
Step 4 To add the slot to the JsonDemuxRouter component, give the slot a name (“hue” for this exam-
ple), choose Type: baja:Double and click O K .
The new slot is added.
Step 5 In the W i r e S h e e t view, connect the schema output to the JsonDemuxRouter component’s Route
slot.
The following image shows a W i re S h e e t view of components routing part of an incoming message
to the slot for onward processing. The slot that you add must match the key name, to select that
key, and should be either Boolean, Numeric or String to match the JSON value.
December 9, 2019 45
Once the JsonDemuxRouter component has a slot of type baja:Double named "hue", it passes
the hue to expose the value “43211” for use in the station.
N O T E : To extract nested JSON objects, add a string with an appropriate name, for example, a demuxed
string named ‘data’ could contain this entire nested object:
{
"type" : "line",
"data" :
{
"labels" : ["Sunday", "Monday"],
"values" : [ 1, 2 ]
}
}
About the Json Path selector

The JsonPath component allows data to be interactively located and extracted from JSON structures using
a special notation to represent the payload structure.
For the example below, the first item in the values array (1) can be selected using a JsonPath value of $.
data.values.[0]:
{
"type" : "line",
"data" :
{
"values" : [ 1, 2 ]
}
}
In this example a single numeric value was selected. However it is possible to select a complete subset of
the incoming JSON, for example: $.data would select the entire data object into the out slot, or $.data.
values would select the entire JSON “values” array. Any expression containing a search with $..labels,
for example, will return search results enclosed within an outer array.
Much more explanation of this powerful tool can be found at the following websites:
• https://goessner.net/articles/JsonPath/
• http://jsonpath.com/
• https://www.baeldung.com/guide-to-jayway-jsonpath
Applying a jsonPath selector

Selectors are components that apply selection criteria to an inbound message and display the result in an
out slot. The JsonPath component allows data to be interactively located and extracted from JSON struc-
tures using a special notation to represent the payload structure.
P r e r e q u i s i t e s : You have a schema generating an output that can be filtered.
46 December 9, 2019
The following task shows how to use a JsonPath component for data selection.
Step 1 Open the j s o n T o o l k i t palette, expand I n b o u n d → S e l e c t o r s and drag a JsonPath selector to a
Wire Sheet and then open the selector’s property sheet view.
Step 2 Configure the path property using the syntax $.data.values.[0], as shown below, and save
your changes.
The result of the configuration displays in the Out property.

For example, this path selects the first item in a values array (1): $.data.values.[0]. This is the
schema payload:
{
"messageType" : "line",
"data" : [
{
"values" : [ 1, 2 ]
}
}
This example selects a single numeric value, however, there are other possibilities for selecting a
subset of the incoming JSON:
• $.data transfers the entire data object to the Out slot.
• $.data.values selects the entire JSON array.
Any expression containing a search with, for example, $..labels returns search results enclosed
within an outer array.
These URLs to external web sites explain this powerful tool in detail.
• https://goessner.net/articles/JsonPath/
• http://jsonpath.com/
• https://www.baeldung.com/guide-to-jayway-jsonpath
Handlers and alarm acknowledgments

Message handlers are components designed to perform a specific task with the data routed and selected via
the other inbound components. Handlers make acknowledging alarms possible.
If an alarm exported from a station includes the UUID, an Alarm Uuid Ack Handler can pass back that unique
id. The expected format is shown below, where the array allows multiple alarms to be acknowledged at
once.
{
"user": "Maya",
"alarms": [ "5cf9c8b2-1542-42ba-a1fd-5f753c777bc0" ]
}
December 9, 2019 47
The user value stored on the alarm record identifies which user acknowledged the alarm in the remote appli-
cation. If the user key is omitted the component still tries to acknowledge the alarms using the fallback name
“AlarmUuidAckUser”.
N O T E : The Json Schema Service runAsUser is a prerequisite for this handler to work. The specified user
must have admin write permissions for the alarm class of the records being acknowledged.
Two alarm handler properties configure this task:
• AckSource is a string appended to every AlarmRecord acknowledged. Its purpose is to allow auditing in
future and is stored as AckSource in the alarm data.
• AckResult is a topic that reports the results of the alarm acknowledgment. Its purpose is to log or post
process activity. Here is an example of the output it reports:
"Ack-ed alarm " + record
"Already ack-ed in alarmDb " + record
"Could not create BUuid from " + uuid
Setpoint handler and writing to points

The SetPointHandler sets incoming setpoint values to control writable control points.
ID.
This is an example of setpoint handler JSON:
{
"%idKey%" : "x",
"%valueKey%" : y,
("%slotNameKey%" : "slotName")
}
The Control Points are located by handle ord in the form: "%idKey%" : "323e".
These properties configure setpoint handlers:
• idKey is a top-level key in the JSON payload. It represents the point ID.
• valueKey is a top-level key in the JSON payload. It represents the value to set.
• slotNameKey is an optional top-level key in the JSON payload. It represents the slot name to write to.
• defaultWriteSlot defines which slot to write to by default if the payload does not specify a slot.
• runAsUser is a mandatory property for the setpoint handler to use.
The nested keys, override/duration and status are not currently supported.
Exp o rt s et po i nt hand l er and exp or t reg is tr ati o n

Like the SetpointHandler, the ExportSetpointHandler allows an external JSON message to change
the value of a control point identified by the Id property of an export marker.
This handler locates target points in a station where a unique key from the cloud platform registered the
points. Once the cloud platform returns a suitable identifier for a point with an export marker, this setpoint
handler can apply write messages from the platform using the returned Id rather than the slot or handle ord
(for example).
E x p o r t re g i s t r a t i o n
The JsonExportRegistrationRouter and JsonExportDeregistrationRouter enable this behaviour
of applying a unique identifier from an external system to an export marker.
48 December 9, 2019
This allows the cloud (or other external system) to assign it’s own identifier or primary key to export-marked
points in the Niagara station, which can be used to locate them in future or include them in exports to the
cloud system.
The messages should be in this format:
{
"messageType" : "registerId"
"niagaraId" : "h:a032",
"platformId" : "mooseForce123"
}
or
{
"messageType" : "deregisterId"
"platformId" : "mooseForce123",
}
N O T E : This class does not use the messageType, which would be used simply to route it to this handler and
so can be changed as needed.
Example
This W i r e S h e e t and JSON loosely demonstrate some of the routers and selectors based upon a fictional
point search JSON message.
F ig ure 21 Json Export Registration Handler example Wire Sheet and JSON
December 9, 2019 49
50 December 9, 2019
Chapter 4 Developer guide
♦ JSON schema types
♦ Relative topic builder
♦ Type Override example
♦ Inline JSON Writer
♦ Custom query style
♦ Builder class / API
♦ Useful methods
♦ How schema generation works
♦ Working with Apache Velocity
♦ Subscription examples with bajascript
♦ Inbound components
Developers can use JSON to create complex queries and apps. They can extend the Toolkit by creating their
own query styles.
JSON schema types

All components that contribute to the string output of the schema are called members and are nested under
the schema. During generation, the system processes each member recursively (top down), appending each
member’s result to a JSON writer. This creates the final JSON output string.
Three interfaces represent three structural types of the JSON payload:
• Property (key/value pair)
• Object
• Array
A getJsonName() defines each schema member.
F ig ure 22 Schema types
Three interfaces represent the three structural types of a JSON payload: property (key and value pair), ob-
ject and array. All schema members have a name defined by getJsonName().
December 9, 2019 51
Chapter 4 Developer guide Niagara JSON Toolkit Guide
All schema members inherit the default processChildJsonMembers() behaviour, which allows us to recur-
sively call process() on each member down through the nested schema structure.
All schema member types extend BJsonSchemaMember and most implement one of the three interface
types. The base class lets us define the parent-child legal checks. This restricts nested types to just other
BJsonSchemaMembers. This is where the JSON passes global schema events, for example, unsubscribe.
Different types of JSON schema members may be nested under a schema. These are logically grouped by
common behaviour.
Fi gu re 23 Json schema members
When developing against the toolkit, most of these classes are open to extension.
Example 1
Consider a requirement for a new key and value pair to represent a device’s startup time as a string value.
You might simply extend the BJsonSchemaProperty<T> as type <String> using your own date format or
type <BAbsTime> allowing the schema to render the date automatically using the schema date config. Now,
you just need to implement getJsonValue() to return the appropriate value.
@NiagaraType
public class BDeviceTimeProperty extends BJsonSchemaProperty<BAbsTime>
{
/*+ ------------ BEGIN BAJA AUTO GENERATED CODE ------------ +*/
.....
/*+ ------------ END BAJA AUTO GENERATED CODE -------------- +*/
@Override
public BAbsTime getJsonValue()
{
return (BAbsTime) ..... // this will use the schemas date format config
}
}
Example 2
This requirement is for an object that contains a key and value pair for each slot on the target component,
but only those with a user defined 1 flag. You might extend BJsonSchemaBoundObject, hide the
52 December 9, 2019
Niagara JSON Toolkit Guide Chapter 4 Developer guide
slotsToInclude slot, and override the method getPropertiesToIncludeInJson() to only return properties with
the user defined flag.
@NiagaraType
@NiagaraProperty(name = "slotsToInclude", type = "jsonToolkit:SlotSelectionType",
defaultValue = "BSlotSelectionType.allVisibleSlots",flags = Flags.HIDDEN,
override = true) public class BUserDefinedFlags extends BJsonSchemaBoundObject
{
.....
@Override
public List <String>getPropertiesToIncludeInJson(BComplex resolvedTarget)
{
if (resolvedTarget == null)
{
return Collections.emptyList(); // or try to resolve it!
}
return Arrays.stream(resolvedTarget.getPropertiesArray())
.filter(prop -> (resolvedTarget.getFlags(prop) & Flags.USER_DEFINED_1) != 0)
.map(prop -> prop.getName())
.collect(Collectors.toList());
}
}
Relative topic builder

If the recipient requires a different topic or URL per point or device, the relativeTopicBuilder compo-
nent is an example of building a topic (for MQTT) or path (for HTTP url) as the output from the current base
item of a relative schema changes.
This program object is in the P r o g r a m s folder of the jsonToolkit palette.
As an example, to update each item returned by the base query, you would link from the RelativeJsonSche-
ma’s Current Base Output topic to the Base Item Changed property, and then from the output slot to
the publish points proxyExt.
Other properties of the base could be inserted to the topic as desired (not just the name).
The example that is included in the palette illustrates the %s variable substituted by this: "/an/mqtt/exam-
ple/%s".
Ty p e O v e r r i d e e x a m p l e
At the core of the JSON Toolkit is a method that maps baja object types to JSON. This determines, for ex-
ample, how any encountered BControlPoint, Facets, BAbsTime etc. should be encoded in the output.
The payload includes many variations for the supported Niagara types. Our approach to accommodating
this is to allow a developer or power user the ability to override specific types as they are converted to
JSON.
For a small JsonSchema, the example in the jsonToolkit palette demonstrates how to use a program ob-
ject[^1] to replace units:
/**
* Allows Json types to to be overridden when placed under JsonSchema/config/overrides/
*/
public BValue onOverride(final BValue input)
{
if (input instanceof BUnit)
{
December 9, 2019 53
javax.baja.units.UnitDatabase unitDB = javax.baja.units.UnitDatabase.getDefault()

javax.baja.units.UnitDatabase.Quantity quantity =
unitDB.getQuantity(input.as(BUnit.class))
if (quantity != null)
{
return BString.make(input.as(BUnit.class).getSymbol() + ":" + quantity.getName())
}
}
// If we can't override the value then just return it as we found it

return input
}
[^1]: To improve maintainability and station loading time in the event that a program object is duplicated re-
peatedly, use the ProgramBuilder.
To use the program, drag this component into the C o n f i g → O v e r r i d e s folder of the schema.
Fi gu re 24 TypeOverride component in jsonSchema
Developers could also override the doOverride(BValue value) method in their own BTypeOverride
variant.
I n l i n e J S O N Wr i t e r
This writer allows the schema to defer control to a developer’s own code in the tree of schema members.
This means that you can add any form of dynamic content into the schema output.
To add custom dynamic content, use a program object as per the example in the P r o g r a m s folder of the
jsonToolkit palette. Or you can extend BAbstractInlineJsonWriter. As code contained in a module
is easier to maintain, extending the abstract class would be preferred where the program object may be
widely distributed.
This palette example implements a method: public BValue onOverride(final BInlineJsonWriter
input), which you can customize to meet your project’s needs. The InlineJsonWriter has two impor-
tant methods:
• JSONWriter jsonWriter = in.getJsonWriter();
• BComplex base = in.getCurrentBase();
Demonstrated below:
/**
* The override method allows control of the writer and current base to be passed
* to the code below * allowing JSON to be dynamically constructed within a schema.
*
* @param BInlineJsonWriter wraps two things:
* JSONWriter jsonWriter = in.getJsonWriter();
54 December 9, 2019
* BComplex base = in.getCurrentBase();

*
* @return BValue allows logging of the "result" when fine logging is enabled
* (this does not need to match what happened to the JSON...)
*/
public BValue onOverride(final BInlineJsonWriter in)
{
//current base is set by the parent schema as each point is submitted for publishing
BComplex base = in.getCurrentBase()
//if (base instanceof BComponent)
JSONWriter jsonWriter = in.getJsonWriter()
jsonWriter.key("highLimit")
jsonWriter.value("1024")
// do not close writer
return null
}
Custom query style

Third–party systems may require query results to be formatted in a manner other than the options provided
in the JSON Toolkit.
To render query data differently, extend BQueryResultWriter and register the class as an agent on
jsonToolkit:JsonSchemaBoundQueryResult.
This example shows how to format the contents of the QueryResultHolder for an external system:
package com.tridiumx.jsonToolkit.outbound.schema.query
import static com.tridiumx.jsonToolkit.outbound.schema.support.JsonSchemaUtil.toJsonType
import java.util.concurrent.atomic.AtomicInteger
import javax.baja.nre.annotations.AgentOn
import javax.baja.nre.annotations.NiagaraType
import javax.baja.sys.BString
import javax.baja.sys.Sys
import javax.baja.sys.Type
import com.tridiumx.jsonToolkit.outbound.schema.query.style.BQueryResultWriter
import com.tridium.json.JSONWriter
/**
* An example custom query result writer.
*
* @author Nick Dodd
*/
@NiagaraType(agent = @AgentOn(types = "jsonToolkit:JsonSchemaBoundQueryResult"))
public class BCowSayJson extends BQueryResultWriter
{
/*@ $com.tridiumx.jsonToolkit.outbound.schema.query.style.BObjectsArray(4046064316)1.0$ @*/
/* Generated Thu Dec 13 11:24:58 GMT 2018 by Slot-o-Matic (c) Tridium, Inc. 2012 */
////////////////////////////////////////////////////////////////
December 9, 2019 55
// Type
////////////////////////////////////////////////////////////////
@Override
public Type getType() { return TYPE }
public static final Type TYPE = Sys.loadType(BCowSayJson.class)
@Override
public BString previewText()
{
return BString.make("A demonstration result writer")
}
@Override
public void appendJson(JSONWriter jsonWriter, QueryResultHolder result)
{
jsonWriter.object()
try
{
jsonWriter.key("mooo01").value("____________________________")
headerCsv(jsonWriter, result)
dataCsv(jsonWriter, result)
jsonWriter.key("mooo02").value("----------------------------")
jsonWriter.key("mooo03").value(" \\ ^__^ ")
jsonWriter.key("mooo04").value(" \\ (oo)\\_______ ")
jsonWriter.key("mooo05").value(" (__)\\ )\\/\\")
jsonWriter.key("mooo06").value(" ||----w | ")
jsonWriter.key("mooo07").value(" || || ")
}
finally
{
jsonWriter.endObject()
}
}
private void headerCsv(JSONWriter jsonWriter, QueryResultHolder result)

{
jsonWriter.key("columns").value(String.join(",", result.getColumnNames()))
}
private void dataCsv(JSONWriter jsonWriter, QueryResultHolder result)

{
AtomicInteger rowCount = new AtomicInteger()
result.getResultList().forEach( map - {
jsonWriter.key("data" + rowCount.incrementAndGet())
jsonWriter.array()
try
{
map.values()
.forEach(value - jsonWriter.value(toJsonType(value, getSchema().getConfig())))
}
finally
{
jsonWriter.endArray()
56 December 9, 2019
}
})
processChildJsonMembers(jsonWriter, false) // append any nested members content

to the json
}
}
Builder class / API

To support the programmatic creation of JSON schemata by developers, the JsonSchemaBuilder class
provides suitable methods.
For example:
BJsonSchema schema =
new JsonSchemaBuilder()
.withUpdateStrategy(BJsonSchemaUpdateStrategy.onDemandOnly)
.withQuery("Bacnet Query", "station:|slot:/Drivers/BacnetNetwork|bql:select
out.value AS 'v', status from control:ControlPoint")
.withRootObject()
.withFixedNumericProperty("Version", BDouble.make(1.23))
.withFixedObject("Config")
.stepDown()
.withBoundProperty("BacnetAddress", BOrd.make(String.format
("station:|slot:/Drivers/BacnetNetwork/%s/address", deviceName)))
.withBoundObject("DeviceSettings", BOrd.make(String.format
("station:|slot:/Drivers/BacnetNetwork/%s/config/deviceObject", deviceName)))
.stepUp()
.withBoundQueryResult("Data", "Bacnet Query", BObjectsArray.TYPE.getTypeSpec())
.build()
The above schema would result in this output:
{
"Version":1.23,
"Config":{
"BacnetAddress":"192.168.1.24",
"DeviceSettings":{
"pollFrequency":"Normal",
"status":"{ok}",
"faultCause":"",
"objectId":"device:100171",
…….
}
},
"Data":[
{
"v":0.45,
"status":"{down,stale}"
},
……*
]
}
N O T E : This example has been trimmed for demonstration purposes.
Useful methods
These are some methods you might regularly use to create custom content.
December 9, 2019 57
W hat to do (usage goal) Class Method
Override to return a different key. This skips the schema’s config BIJsonSchemaMember getJsonName()
settings for name case/space handling.
Override to append customized content to the current JSON BIJsonSchemaMember process(JSONWriter json, boo-
stream via json.key() and json.value(), etc. The Boolean lean jsonKeysValid)
parameter indicates if the syntax of the keys are currently valid
(for example, not inside an array)
Override to react to events, such as the base item changing or BJsonSchemaMember onSchemaEvent(BSchemaE-
subscription disabled. vent event)
Quickly get a reference to the parent schema BJsonSchemaMember getSchema()
Write a JSON key with the schema’s current case and space-han- JsonSchemaNameUtil writeKey(BIJsonSchemaMem-
dling rules applied. ber member, JSONWriter json-
Writer, String name)
Convert any Java value to a native JSON type (String or Number JsonSchemaUtil toJsonType(Object value,
or Boolean) with some default handling of some baja types, and BJsonSchemaConfigFolder
filter out sensitive types. config)
Convert core Java type values (Numerics or Strings or Booleans) JsonSchemaUtil toBValue(Object value)
to BValue equivalents. If the parameter is already a BValue, this
method returns a copy.
Get a live resolved reference to the ord bindings target. BJsonSchemaBoundMember getOrdTarget() / getTarget()
Override the schema’s default behaviour for handling a subscrip- BJsonSchemaBoundMember handleSubscriptionEvent(Sub-
tion event from a binding target. Depending on the content, the scription subscription, BCom-
schema’s default behaviour is to unsubscribe, ignore or request ponentEvent event)
schema generation.
Override to return a different set of slot values for the resolved BJsonSchemaBoundSlotsCon- getPropertiesToIncludeInJson
target. tainer (target)
Implement to perform any lifecycle, cleanup or reporting task BIPostProcessor postProcess(BJsonSchema

after a schema has completed output generation (or failed, in schema, Exception exception)
which case, the exception is non-null).
Extract values from incoming JSON payloads using various JsonKeyExtractUtil lookup*()
methods.
Implement to handle an incoming JSON payload or throw a Rou- BJsonInbound routeValue(BString message,
tingFailedException if unable to process the message. Context cx)
Override to locate a control point by another means than the BJsonSetPointHandler lookupTarget(BString msg,
handle ord, for example by slot path or name. String id)
How schema generation works

Two actions cause the JSON schema to generate or regenerate it’s output.
This charts the flow through the schema logic.
58 December 9, 2019
F ig ure 25 Generate actions
doGenerateJson() doForceGenerateJson()
Min write
time no generateOutputJson()
exceeded?
yes
return no Enabled? yes Licensed? no throw
yes
Set up
security context
Query timer Relative

yes CoV mode? no
running? schema?
yes
no no yes
Start query timer doExecuteQueries() QueryException
process(JSONWriter) JSON/PermissionException
recurse
postProcess() Update output string
recurse
December 9, 2019 59
Binding ords resolve against the current base item of the schema. Unless you are using a relative JSON sche-
ma, this is the station that uses the current result of the base query. Currently, base queries resolve against
the station.
Fi gu re 26 Regular JSON schema with absolute ord bindings that resolve against the station
Relative JSON schema with relative ord bindings resolve against the current base item. This process repeats
until there are no more base items, and results in several output strings.
Fi gu re 27 Relative JSON schema with relative ord bindings that resolve against the current base item
External access to schema output

A URL like the following also allows access to the schema output via the JsonExporter:
http://127.0.0.1/ord/station:%7Cslot:/JsonSchema%7Cview:jsonToolkit:JsonExporter
60 December 9, 2019
This could allow access to an external application consuming data from Niagara.
Wo r k i n g w i t h A p a c h e Ve l o c i t y
Apache Velocity is a Java-based template language anyone can use to reference objects defined in Java
code. You can use it to expose the output of a JSON schema via the Jetty Web Server in Niagara 4. This tool
may be beneficial for applications that expect to consume data provided by the Niagara station, for exam-
ple, a visualization or machine-learning library.
P re re q u i s i t e s :
Given JSON’s origin as a data exchange format for the web, many libraries expect to receive input in this for-
mat. The Google Chart library is such an example. The following example is from the Google Chart project
web site. Notice that the var data is populated with JSON data. Replacing hard-coded data with the out-
put from a suitably-configured JSON schema in your station draws a chart from the Niagara station data.
<html>
<head>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">
google.charts.load('current', {'packages':['corechart']});
google.charts.setOnLoadCallback(drawChart);
function drawChart() {
var data = google.visualization.arrayToDataTable([
['Year', 'Sales', 'Expenses'],
['2004', 1000, 400],
['2005', 1170, 460],
['2006', 660, 1120],
['2007', 1030, 540]
]);
var options = {
title: 'Company Performance',
curveType: 'function',
legend: { position: 'bottom' }
};
var chart = new google.visualization.LineChart

(document.getElementById('curve_chart'));
chart.draw(data, options);
}
</script>
</head>
<body>
<div id="curve_chart" style="width: 900px height: 500px"></div>
</body>
</html>
Step 1 Create a new file chart.vm and paste into it the code example of a sample chart from the json-
consuming-charting library of your choice.
Step 2 Replace the JSON data with a velocity variable, for example, $schema.output,
var data = google.visualization.arrayToDataTable([
$schema.output
])
Step 3 After saving the file, open the axvelocity palette and add a VelocityServlet named “chart”
to your station.
December 9, 2019 61
Step 4 Add a VelocityDocument below the servlet and change the Template File property to point to
the chart.vm file you created earlier.
Step 5 Add a new ContextOrdElement named Schema to the VelocityContext of your
VelocityDocument.
Step 6 Update the Schema Ord element to point to a suitable jsonSchema added to your station.
This schema could output live station data or the result of a query or transform. Both would be suit-
able for charting libraries, although it may be necessary to modify the time and date format form
the schema default settings or to reduce the presented interval of data by using a SeriesTrans-
form Rollup function.
So, what did we achieve? The template HTML file has a variable, which when accessed via the station’s veloc-
ity servlet will be replaced with the output from our schema.
If you add a WebBrowser from the workbench palette to a Px Page and set the ord property to http:\
\127.0.0.1\velocity\chart, you should see a chart when you view the page in a web browser. If not,
use the developer tools to view the source code and ensure that the output of your schema is replacing the
$schema.output variable.
Subscription examples with bajascript

Whilst Velocity is a very convenient means to inject data into an html document, one of many benefits of us-
ing bajascript in your application is support for subscriptions, which update the graphic as data change.
Of course, you could build this schema output in bajascript by executing queries or by directly subscribing
to the components required, but a jsonSchema may reduce some of the work needed in JavaScript, allowing
subscription only to the output slot, which can fetch the required data from the station.
Example html file for showing Chart.js

<!DOCTYPE html

<script type='text/javascript' src='/ord/file:%5Ebajascript/basic.js%7Cview:web
:FileDownloadView'></script>
</head>
<body>
<canvas class="my-4 w-100" id="myChart" width="800" height="450"></canvas>
</body>
</html>
Example basic.js file to fetch chart data
The data array in the payload below uses bound properties. A single-column query would allow historical da-
ta to be used instead from a bql query on the history database.
62 December 9, 2019
// Subscribe to a Ramp. When it changes, print out the results.

require(['baja!'], function (baja) {
"use strict"
// A Subscriber is used to listen to Component events in Niagara.

var sub = new baja.Subscriber()
var update = function () {
// Graphs
var ctx = $('#myChart')
var newJson = JSON.parse(this.getOutput())
var myChart = new Chart(ctx, newJson)

}
// Attach this function to listen for changed events.

sub.attach('changed', update)
// Resolve the ORD to the Ramp and update the text.

baja.Ord.make('station:|slot:/ChartsJS/JsonSchema').get({ok: update, subscriber: sub})
})
Example schema output for chart
{
"type": "line",
"data": {
"labels": [
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday"
],
"datasets": [
{
"data": [
202,
240,
202,
3,
150
],
"backgroundColor": "transparent",
"borderColor": "#007bff",
"borderWidth": 3,
"lineTension": 0
},
{
"data": [
3,
202,
150,
202,
240
],
"backgroundColor": "transparent",
December 9, 2019 63
"borderColor": "#ff0033",
"borderWidth": 3,
"lineTension": 0
}
]
},
"options": {
"scales": {
"yAxes": [
{
"ticks": {
"beginAtZero": false
}
}
]
},
"legend": {
"display": false
},
"title": {
"display": true,
"text": "Philips Hue Light Demo"
},
"tooltips": {
"intersect": true,
"mode": "index"
},
"hover": {
"intersect": true,
"mode": "nearest"
}
}
}
Inbound components
Inbound components route JSON messages to control points and devices.
To create a new inbound type, you extend one of the three main types: BJsonRouter, BJsonSelector or
BJsonHandler and implement routeValue(BString message, Context cx) throws RoutingFaile-
dException. You can create a new RoutingFailedException at any stage to report an error and update
the lastResult slot.
When extending any of the BJsonInbound types, you may specify which property triggers an automatic re-
routing of the last input with Property[] getRerunTriggers(). The helper interface JsonKeyExtrac-
tUtil contains several methods for extracting values from a JSON payload.
64 December 9, 2019
Chapter 5 Components
♦ JsonSchema (Json Schema)
♦ Config (Json Schema Config Folder)
♦ Debug (Json Schema Debug Folder)
♦ Queries (Json Schema Query Folder)
♦ RelativeJsonSchema (Relative Json Schema)
♦ JsonSchemaService (Json Schema Service)
♦ Object (Json Schema Object)
♦ BoundObject (Json Schema Bound Object)
♦ Array (Json Schema Array)
♦ BoundArray (Json Schema Bound Array
♦ FixedString (Json Schema String Property)
♦ FixedNumeric (Json Schema Numeric Property)
♦ FixedBoolean (Json Schema Boolean Property)
♦ Count (Json Schema Count Property)
♦ CurrentTime (Json Schema Current Time Property)
♦ UnixTime (Json Schema Unix Time Property)
♦ BoundProperty (Json Schema Bound Property)
♦ BoundCSVProperty (Json Schema Bound Csv Property)
♦ Facet (Json Schema Facet Property)
♦ FacetList (Json Schema Facet List)
♦ Tag (Json Schema Tag Property)
♦ TagList (Json Schema Tag List)
♦ Query (Json Schema Query)
♦ RelativeHistoryQuery (Relative History Query)
♦ BoundQueryResult (Json Schema Bound Query Result)
♦ JsonAlarmRecipient (Json Alarm Recipient)
♦ AlarmRecordProperty (Json Schema Alarm Record Property)
♦ BFormatProperty (B Format String)
♦ ExportMarker (Json Export Marker)
♦ AlarmExportMarkerFilter (Alarm Export Marker Filter)
♦ HistoryExportMarkerFilter (History Export Marker Filter)
♦ JsonExportSetpointHandler (Json Export Setpoint Handler)
♦ JsonExportRegistrationHandler (Json Export Registration Handler)
♦ JsonExportDeregistrationHandler (Json Export Deregistration Handler)
♦ JsonMessageRouter (Json Message Router)
♦ JsonDemuxRouter (Json Dmux Router)
♦ JsonPath (Json Path)
♦ JsonAtArrayIndex (Json At Array Index)
♦ JsonContainsKey (Json Contains Key)
♦ JsonIndexOf (Json Index Of Key Selector)
♦ JsonSum (Json Sum Selector)
♦ JsonLength (Json Length Selector)
♦ JsonFindAll (Json Find All Selector)
♦ AlarmUuidAckHandler (Alarm Uuid Ack Handler)
♦ SetPointHandler (Json Set Point Handler)
♦ EngineCycleMessageQueue (Engine Cycle Message Queue)
♦ EngineCycleMessageAndBaseQueue (Engine Cycle Pair Queue)
♦ InlineJsonWriter (Inline Json Writer)
♦ TypeOverride (Type Override)
♦ relativeTopicBuilder (Program)
Components include services, folders and other model building blocks associated with a module. You may
drag them to a P r o p e r t y or W i r e S h e e t from a palette.
December 9, 2019 65
Chapter 5 Components Niagara JSON Toolkit Guide
Descriptions included in the following topics appear as context-sensitive help topics when accessed by:
• Right-clicking on the object and selecting V i e w s → G u i d e H e l p
• Clicking H e l p → G u i d e O n T a r g e t
JsonSchema (Json Schema)

This component defines the schema, which includes the resulting output, configuration and queries proper-
ties, JSON entities, and actions.
Fi gu re 28 JsonSchema properties
You add a schema to a station by dragging a JsonSchema from the palette to the C o n f i g folder in the Nav
tree. From there, to access schema properties, expand the C o n f i g folder and double-click the schema.
Property Value Description

Output container Contains the generated JSON string.
License Status read-only Reports {ok} or {fault} based on the validity of the JSON
license.
Last Updated read-only Reports when the schema was updated last.
Config folder Contains properties for customizing the schema.
Queries folder Contains the query ords.
ro o t
This container holds JSON entities: objects, arrays, properties and bound properties.
66 December 9, 2019
Niagara JSON Toolkit Guide Chapter 5 Components
F ig ure 29 root Json Schema Object
A separate topic documents each of type of object, array and property.

Actions
These actions are available when you right-click on the J s o n S c h e m a or click the icons to the right of the
Output box on the schema P ro p e r t y S h e e t .
F ig ure 30 JSON Schema action buttons on the right side
• G e n e r a t e J s o n requests a rebuild and update of schema output. For relative schemas, this evaluates the
Base Query and publishes results.
• F o rc e G e n e r a t e J s o n forces the generate action regardless of the current tuning settings.
• C l e a r C a c h e discards the last known values of bindings and cached query results.
• C l e a r O u t p u t sets the schema output to an empty string.
• E x e c u t e Q u e r i e s forces an immediate execution of all the schemas queries. You can link this action to
some appropriate logic to trigger execution when needed.
• U n r e g i s t e r (relative schema only) unsubscribes the registration from any base items that the relative
schema monitors for updates.
• U n s u b s c r i b e A l l removes cloud registration from all export-marked entities in the station.
In addition to the standard properties (Enabled, Status, and Fault Cause), these properties are unique to the
jsonSchema. The child containers are documented in following topics.
Config (Json Schema Config Folder)

This folder contains properties used to configure the entire schema.
December 9, 2019 67
Fi gu re 31 Config folder properties
To access these properties, expand C o n f i g → J s o n S c h e m a , right-click C o n f i g and click V i e w s → A X P r o p e r t y

Sheet.
Name Casing Rule drop-down list (de- Configures how the schema formats JSON keys. Establishing a
faults to Camel) standard provides naming convention uniformity.
Camel begins key names with a lower-case letter and uses
upper case to begin concatenated words (camelCaseKey).
Pascal starts names with initial caps and concatenates all
words (PascalCaseKey).
Upper changes all letters to upper case (UPPERCASEKEY).
Lower reduces all letters to lower case (lowercasekey).
Preserve leaves the name unchanged as entered.
Name Spacing drop-down list (de- Promotes uniformity by defining the use of spaces in JSON
Rule faults to Remove) key names.
Remove removes all spaces ("SpaceTemp" : ...).
Keep leaves spaces unchanged ("Space Temp" : ...).
Add injects a space between caseChanges
Hyphenate replaces each space with a hyphen ("Space-
Temp" : ...).
Underscore replaces each space with an underscore
("Space_Temp" : ...).
URL Encode adds a plus (+) between words ("Space+Temp" :
...).
Date Format text Defines a Java SimpleDateFormat pattern for the time used by
Pattern the schema when it encounters AbsTime, for example, from a
history query or the Current Time property. ISO 8601, for ex-
ample, is yyyy-MM-dd HH:mm:ss.SSSZ.
Numeric Precision number Defines the number of decimal digits to show on exported
floating point numbers. Values are rounded. Point facets are
not used.
Use Escape true (default) or Turns on and off the use of escape characters around charac-
Characters false ters that otherwise would have special meaning.
When false, the schema removes the escape characters it
finds. For example, $20 becomes a “ “ or space character.
Tuning Policy folder Contains properties to configure performance.
68 December 9, 2019

Overrides folder Contains override programs.
Debug folder Contains troubleshooting information.
Tuning Policy (Json Schema Tuning Policy)

These properties configure how a schema evaluates write requests and the acceptable freshness of read
requests.
F ig ure 32 Tuning Policy properties
To access these properties, expand C o n f i g → J s o n S c h e m a → C o n f i g and double–click T u n i n g P o l i c y.

NOTE:
Clicking A c t i o n s → F o r c e G e n e r a t e J s o n overrides all tuning policy settings. Export markers applied to nu-
meric points also have a CoV Tolerance property, which you can use to throttle output.

Min Write Time hours minutes Specifies the minimum amount of time allowed between sche-
seconds ma generation, so that, for example, hundreds of concurrent
CoV changes over a short time do not result in a deluge of
JSON messages.
The default value of zero (0) disables this rule causing all value
changes to attempt to generate.
Max Write Time hours minutes If nothing else triggers a generate, this property specifies the
seconds maximum amount of time to wait before regenerating. Any
generation action resets this timer.
The default value of zero (0) disables this rule resulting in no
timed generation.
Write On Start true (default) or Determines schema behaviour when a station starts.
false
If true, a schema generation occurs when the station starts.
If false, no generation occurs on station start.
December 9, 2019 69

Write On Enabled true or false Determines schema behaviour when a status transitions from
(default) disabled to normal (enabled).
If true, a generate occurs when the schema transitions from
disabled to enabled.
If false, no generation occurs.
Update Strategy drop-down list Manages the control strategy in the station.
COV updates JSON at change of value.
On Demand Only updates JSON only when you right-click on
the schema component and click A c t i o n s → G e n e r a t e .
Overrides (Json Schema Overrides Folder)

Configures how to convert specific data types to JSON. This definition overrides the default conversion be-
haviour and applies to anywhere the datatype is encountered in an entire schema.
Examples might be where facets should be replaced to a locally understood value, such as ‘degC’ to ‘Cel-
sius’; defining a different format for Simple types, such as Color and RelTime; or perhaps to manage expect-
ations for +/- INF in a target platform.
Fi gu re 33 An example of an Overrides folder
To access these slots, expand C o n f i g → J s o n S c h e m a → C o n f i g , right-click O v e r r i d e s and click V i e w s → A X

Propert y Shee t.
This example contains a type override.
Debug (Json Schema Debug Folder)

This folder contains two slots. This information can help troubleshoot problems.
Fi gu re 34 Debug containers
To access these containers, expand C o n f i g → J s o n S c h e m a → C o n f i g , right-click D e b u g and click V i e w s → A X

Propert y Shee t.
Container Value Description

Schema Output Additional Displays the recent history of output from a JSON schema.
History Debug properties
Config, Debug, read-only folder Reports JSON statistics related to three aspects of activity:
Metrics queries, data generation, and data subscription.
(JsonSchema)
70 December 9, 2019
Schema Output History Debug (Schema History Debug)

The report this view provides lists the recent history of output from a JSON schema.
F ig ure 35 Schema Output History Debug properties
Right-clicking S c h e m a O u t p u t H i s t o r y D e b u g followed by clicking V i e w s → S p y L o c a l or S p y R e m o t e

opens a s c h e m a O u t p u t H i s t o r y D e b u g tab. This tab displays the recent history of output from the schema.
This information is useful when the output updates rapidly, such as when a link calls a generate JSON in
quick succession, or, in a relative schema, when output quickly changes once per base item.
In addition to the standard property (Enabled), this property supports the Schema Output History Debug
component.

History Max Size number (defaults Sets how many debug records to store in the station.
to 10 records)
De bu g rep ort
F ig ure 36 Debug report
To access this view, click the O u t p u t H i s t o r y button or right-click the Schema Output History Debug slot
and click V i e w s → S p y R e m o t e or S p y L o c a l .
Column Description
No. Identifies the row. You configure the number of allowed rows by setting the History Max Size value on
the Debug P r o p e r t y S h e e t .
Date Identifies when the history was written to the database.
Base Item Identifies the slot from which the system generated the JSON.
Result Shows the JSON payload.
Metrics (Json Schema Metrics)

This folder exposes schema generation, query execution and CoV subscription metrics. If needed, you can
log or link individual metric values to generate alarms.
Metrics help with determining sizing and provisioning capacity on a cloud platform by estimating the traffic
a station is likely to generate with a given schema. They may also assist in identifying performance problems.
To assist debugging, use the reset action.
December 9, 2019 71
Fi gu re 37 Metrics as reported from the schema
To access these metrics, expand C o n f i g → J s o n S c h e m a → C o n f i g → D e b u g and double–click M e t r i c s .

The metrics provide three categories of performance information: query performance, generate perform-
ance, and subscription performance.
Queries Generation Subscription
Query Folder Executions Request Schema Generations Subscribes
Individual Query Executions Schema Generations Unsubscribes
Query Fails Schema Generation Fails Subscription Events
Last Query Fail Reason Last Schema Generation Fail Reason Subscription Events Ignored
Last Query Execution Millis Output Changes Cache Hits
Query Execution Millis Total Last Output Size Cache Misses
Query Execution Millis Max Output Size Total
Query Execution Millis Avg Output Size Max
Output Size Avg
Resolve Errors
72 December 9, 2019
Most metrics are self-explanatory. Execution millis report the number of milliseconds spent performing a
query. Cache hits indicate the number of schema string generations that found a cached value for a binding.
Cache misses indicate the number of schema string generations that found no cached value for a binding.
Queries (Json Schema Query Folder)

This folder under a JSON schema stores search queries whose results are then available to be used by the
schema. Queries generate JSON payloads from the results of bql or neql searches. For example, a query
may include a report of overridden points, active alarms, or history logs for a given point.
F ig ure 38 Queries folder properties
To access these properties, expand C o n f i g → J s o n S c h e m a , right-click Q u e r i e s and click V i e w s → A x P r o p -

erty Sheet.

Query Interval time Defines how often the schema executes its queries, which de-
termines how up-to-date exported data are when the schema
uses an Update Strategy of COV.
If multiple queries exist, each time the schema executes it runs
each query in parallel.
Last Query Com- read-only (defaults Reports the time the last query completed.
pleted Timestamp to null)
Queries, queries- time Increases the amount of time granted to complete all queries
MaxExecutionTime on each cycle. Failure to complete within this time causes the
(hidden property schema generation to fail.
on the Queries
folder)
Query (Json Schema Query)

This JSON entity sets up a database search. A query can be any valid transform, neql or bql statement, which
returns a BITable.
F ig ure 39 Query properties
To add a query to a schema (JJs o n S c h e m a or R e l a t i v e J s o n S c h e m a ), expand the Q u e r y folder in the palette

and drag a query to the Q u e r i e s folder in the schema.
December 9, 2019 73
You access query properties by double-clicking the J s o n S c h e m a or R e l a t i v e J s o n S c h e m a node in the Nav

tree, expanding the Queries folder followed by expanding the query itself.

Query Ord ord (defaults to Identifies the target object of the query.
null)
Last Result Size read-only (defaults Reports the size of the query result the last time the frame-
to 0) work executed the search.
RelativeHistoryQuery (Relative History Query)

This query works in conjunction with a RelativeJsonSchema.
Fi gu re 40 RelativeHistoryQuery properties
You add a RelativeHistoryQuery under the Queries folder in the R e l a t i v e J s o n S c h e m a . You access these
properties by double-clicking the R e l a t i v e J s o n S c h e m a node in the Nav tree and expanding the Queries
folder.
Query Pattern bql Prepends to a bql query so query data can be included in the
payload for a given set of points or devices.
For example: %baseHistoryOrd%?period=today|bql:
select timestamp, value
Example
Here is an example of how to use the Query Pattern property to pre-pend the current base item to a bql
query. This example includes query data in the payload for a given set of points or devices:
You may use this with a base query to return a HistoryConfig or a HistoryExt (or the parent of these slots):
C A U T I O N : When creating queries, bear in mind the potential performance implications of running queries
frequently. To reduce the scope of the query, focus the first part of the ord on the location where the data
are likely to be found, or use the stop keyword to prevent depth recursion.
BoundQueryResult (Json Schema Bound Query Result)

This entity determines where and how to insert the results of a query in the payload.
Fi gu re 41 BoundQueryResult properties
74 December 9, 2019
To add this component, expand the Q u e r y folder in the palette and drag a BoundQueryResult to the root
JSON schema O b j e c t of a relative JSON schema.

Query drop-down list Associates this query result with a query ord as defined by a
query under the Q u e r i e s folder. This folder can contain multi-
ple queries.
Output Style drop-down list Defines the output style to render the query in.
Base Query (Base Query)

A base query feeds base components to a schema, which the query resolves against the schema one at a
time. When used with a relative schema, the base query allows you to limit the scope of your query and to
scale within that as you add new points or components.
The Base Query component is located in the palette as part of any of the relative schema components (for
example, BasicRelativeSchema, RelativeHistorySchema, and others).
In addition to the standard properties (Status and Fault Cause), these properties support the Base Query.

Base Query text Defines the scope of the query.
Publish Interval hours, minutes, Specifies the amount of time between query executions. It
seconds triggers a complete publish output (of every returned compo-
nent) at the interval selected.
Last Publish Count read-only Indicates the number of times the query executed.
Last Publish Time read-only Indicates the last time the query executed.
RelativeJsonSchema (Relative Json Schema)

This schema enables the scaling of JSON payload generation, which provides faster processing than the
speed available using multiple simple schemata.
December 9, 2019 75
Fi gu re 42 RelativeJsonSchema properties
You add a relative schema to a station by dragging a RelativeJsonSchema from the palette to the C o n f i g
folder in the Nav tree. From there, to access schema properties, expand the C o n f i g folder and double-click
the schema.
In addition to the standard properties (Enabled, Status, and Fault Cause), these properties are unique to
JSON.
Last Updated read-only (defaults Reports when the relative schema was updated last.
to null)
Config folder Contains properties for configuring the relative schema.
Queries folder Contains the search arguments.

Base Query additional Defines a query that is intended to resolve targets in the sta-
properties tion one at a time.
An example might be all BACnet devices. The base query re-
turns the objects that the schema resolves against. The schema
objects (below the query) then pick out appropriate values.
JsonSchemaService (Json Schema Service)

This service supports JSON functionality and provides some station global filtering.
76 December 9, 2019
F ig ure 43 JsonSchemaService properties
You access these properties by double-clicking the J s o n S c h e m a S e r v i c e under the C o n f i g → S e r v i c e s folder

in the Nav tree.
In addition to the standard properties (Status, Fault Cause, and Enabled), the following properties are
unique to the JsonSchemaService:

Run As User text Specifies the user account to assume in the event that a router
processes an incoming change. This is mandatory when using
the SetPointHandler, for example, so that the framework
can limit any changes triggered by a cloud platform to areas
where the platform should have write access within the station.
This setting is also optionally used for JSON schema export
data.
This property is important for security. Only a super user can
configure it. The framework requires it for incoming data used
to update a SetPointHandler. The set operation succeeds
only if a real user with operator-write permission on the slot is-
sues the incoming JSON.
This property is optional when exporting JSON with a schema.
When set, the data value of the exported slot defaults to an
empty string unless Run As User is a real user with operator-
read permission on the slot.
S M A Expiration additional Configures a reminder of when the framework Software Main-

Monitor properties tenance Agreement is about to expire.
Global Cov Slot Additional Provides some station global filtering by identifying which
Filter properties slots should be ignored when subscribed to bound values. The
default list of slots includes a good example of why this func-
tion is necessary in that changes to a component’s wsAnnota-
tion property (which details the position and size of a
component glyph on the W i r e S h e e t ), should generally be ex-
cluded from the changes of value reported to any upstream
consumer of data.
S M A Expiration Monitor (S M A Expiration Monitor)

Given the JSON Toolkit’s requirement for active maintenance (SMA) on non-demo licenses, this monitor in-
creasingly notifies you as the license expiration date approaches. It runs on startup, then every 24 hours
since the last check to establish if the expiration date is within the warning period or expired, and generates
an offNormal or Fault alarm accordingly.
December 9, 2019 77
Fi gu re 44 S M A Expiration Monitor properties
To configure these properties, expand C o n f i g → S e r v i c e s , double-click J s o n S c h e m a S e r v i c e and expand S

M A E x p i r a t i o n M o n i t o r.
Although the alarms are likely the most accessibly notification method, the SMA monitor also logs messages
to the station console and exposes the days remaining as a slot, which can be shown, for example, on a
dashboard.
The station itself has an S M A Notification Setting under the U s e r S e r v i c e , which alerts you at the web
login screen.
As an extension of S M A requires a reboot to install the new license, the monitor performs no further
checks, once it detects an expired license, until the station starts again.
In addition to the standard Alarm Source Info properties, these properties are unique to the JSON
Toolkit:
Mode drop-down list (de- Configures when to activate an alarm regarding a pending li-
faults to Early cense expiration.
Warning)
Early Warning generates an alarm before the license
expires.
Once Expired generates an alarm when the license expires
and thereafter.
Disable Monitor turns monitoring off.
Warn below number of days Configures when to start warning of the license expiration.
from 1 to 180 (de-
faults to 30 days)
Remaining read-only Displays the number of days before the license expires.
Global Cov Slot Filter (Subscription Slot Blacklist)

This filter denotes which slots to ignore when subscribed to bound values.
Fi gu re 45 Subscription Slot Blacklist
You access this list by expanding C o n f i g → S e r v i c e s → J s o n S c h e m a S e r v i c e and double-clicking G l o b a l C o v

S l o t F i l t e r.
The default list includes a good example of why this function is necessary, in that changes to a component’s
wsAnnotation property (which details the position and size of a component glyph on the Wire Sheet)
should, generally, be excluded from the changes of value reported to any upstream consumer of data.
Object (Json Schema Object)

This is an empty, named container that holds the other schema entities, which set up the JSON payload.
78 December 9, 2019
F ig ure 46 Example of an object container with JSON entities
To add the root object to a schema, expand the O b j e c t s folder in the palette and drag an O b j e c t to the
J s o n S c h e m a folder. To add another object to the schema, drag an O b j e c t from the palette to the root O b -
j e c t container under the schema.
An object is a container. It has no properties of its own or additional containers. Inside this container, the
JSON objects and properties model the structure of the JSON message underneath the schema object. If
you nest items in this container within each other in a tree structure, they will appear nested in the JSON
string.
BoundObject (Json Schema Bound Object)

This entity is a named JSON object whose child name and value pairs are the slots within a target ord.
F ig ure 47 Example of a BoundObject
To add a bound object to a schema, expand the O b j e c t s folder in the palette and drag a BoundObject to
the schema folder, then double-click the bound object.

Binding ord, bql, neql, ab- Establishes a relationship between a target object, such as a
solute path point, slot, component, tag, etc. and its representation in the
framework.
Json Name read-only Displays the name defined by the Json Name Source.
Json Name Source drop-down list Selects a name for the source object based on how it is defined
elsewhere. Options are:
Display Name is an explicitly-assigned name for the object.
Target Name
December 9, 2019 79
Target Display Name

Target Parent Name
Target Path displays the ord for the object rather than a
name.
Slots To Include dop-down lists Identifies which slots from the target to include in the resultant
JSON. Options are:
All Slots reports data from all slots in the target object.
All Visible Slots excludes hidden slots.
All Summary Slots includes only those with the summary
flag set.
Selected Slots manually selects slots from a list.
Json Slot Name drop-down list Selects the name for a specific source slot. Options are:
Source
Display Name is an explicitly-assigned name for the slot.
Name selects an alternate name.
Array (Json Schema Array)

This is an empty, named container for other schema entities, which set up the JSON payload.
To add an array to a schema object, expand the A r r a y s folder in the palette and drag an Array to the root
object folder in a schema.
An array has no properties of its own or additional containers.
BoundArray (Json Schema Bound Array

This is an empty named container for other schema entities.
Fi gu re 48 BoundArray properties
To add a bound array to a schema object, expand the A r r a y s folder in the palette and drag a BoundArray
to the root object folder in a schema, then double-click the BoundArray component.

framework.
80 December 9, 2019

Target Name
Target Display Name
Target Parent Name
name.
Slots To Include drop-down lists Identifies which slots from the target to include in the resultant
JSON. Options are:
flag set.
F ixe dS tr ing (J s o n S c hem a St ri ng Pro p ert y)

This property inserts a string value into the JSON payload.
F ig ure 49 FixedString property
To add this property to a schema object or array, expand the P ro p e r t i e s folder in the palette and drag a
FixedString to the root object { } or to an array [ ] under the root object, then double-click the Fixed-
String component.
Fixed properties, such as names, appear as constants.
You can link in to these if you expect a name to vary. JSON includes the current value during the next gener-
ation event triggered by a CoV on a bound entity or by the invocation of the Generate action. Changing
the value of a fixed property does not trigger a CoV generation event the same way that a bound equivalent
does.
F ixe dN um er ic ( J so n Sc hem a Nu m eri c P rop er ty )

This property inserts a fixed numeric value.
F ig ure 50 FixedNumeric property
FixedNumeric to the root object { } or to an array [ ] under the root object. To configure its property,
double-click it.
You can link in to this value if you expect it to vary. The next generation event includes the current value trig-
gered by CoV on a bound entity or by the invocation of the Generate action. A change in the value of any
fixed property does not trigger a CoV generation event in the way that a bound equivalent would.
December 9, 2019 81

Numeric Value single-digit num- Sets up a numeric value.
ber to six decimal
places (defaults to
0.000000)
Fi xed Bo ol ean ( J s on Sc h em a B oo l ean Pro pe rt y)

This property inserts a fixed Boolean value, which defaults to false.
Fi gu re 51 Fixed Boolean property
To add this property to a schema object or array, expand the P r o p e r t i e s folder in the palette and drag a
FixedBoolean to the root object { } or to an array [ ] under the root object, then double-click the Fixed-
Boolean component.
You can link in to this value if you expect it to vary. The next generation event includes the current value trig-
gered by CoV on a bound entity or by the invocation of the Generate action. A change in the value of any
fixed property does not trigger a CoV generation event in the way that a bound equivalent would.
Co unt ( J s on Sc h em a Co unt P rop er ty )

This fixed property defines a named value that increments by one each time the schema generates. You
could use this property for message IDs.
Fi gu re 52 Count property
Count to the root object { } or to an array [ ] under the root object, then double-click the Count
component.
This property is a number that defaults to zero (0).
To return this value to zero, right-click the Count property and click A c t i o n s → R e s e t .
Cur rent Ti m e ( J so n Sc hem a C urre nt T im e Pro pe rt y)

This fixed property inserts the current time as defined by the Date Format Pattern in the JSON schema
object.
Fi gu re 53 CurrentTime property
CurrentTime to the root object { } or to an array [ ] under the root object, then double-click the Cur-
rentTime component.
The format for the current time is: year-month-day hour:minute:second
82 December 9, 2019
U nix Ti m e (J s o n S c hem a U nix T im e Pro p ert y)

This fixed property inserts the current time as Unix time. This system for identifying a point in time is the
number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970. It is widely used in systems
that run the Unix operating system.
F ig ure 54 UnixTime property
UnixTime to the root object { } or to an array [ ] under the root object, then double-click the UnixTime
component.
Bo un dP rop er ty ( J s on Sc h em a B o und P rop er ty )

This property inserts the current value of the object specified by the Binding property.
F ig ure 55 BoundProperty in a JsonSchema and RelativeJsonSchema
To add a bound property to a schema object or array, expand the B o u n d P ro p e r t i e s folder in the palette
and drag a BoundProperty to the root object { } or to an array [ ] under the root object, then double-click
the BoundProperty component.
December 9, 2019 83

framework.
Target Name
Target Display Name
Target Parent Name
name.
Bo und CS VPro p ert y ( J s on Sc he m a B ou nd C sv P rop er ty )

This bound property is a named JSON string, which renders child slots as a string, comma separated list
(with no surrounding [] or {}).
Fi gu re 56 BoundCSVProperty properties
To add this bound property to a schema object or array, expand the B o u n d P ro p e r t i e s folder in the palette
and drag a BoundCSVProperty to the root object { } or to an array [ ] under the root object, then double-
click the BoundCSVProperty component.
84 December 9, 2019

Target Name
Target Display Name
Target Parent Name
name.
Slots To Include dop-down lists Identifies which slots from the target to include in the resultant
JSON. Options are:
flag set.
F ac et ( J s on Sc he m a F ac e t Prop er ty )
This bound property defines a single facet value from a bound component to insert in the schema output,
for example the units of the current point.
F ig ure 57 Facet property
To add this bound property to a schema object or array, expand the B o u n d P r o p e r t i e s folder in the palette
and drag a Facet to the root object { } or to an array [ ] under the root object, then double-click the
bound component.

Ord ord Selects the ord to the component with the facet applied.
Facet Key text Defines the name of a facet. Facet keys should be added as
follows: units, mix, max.
FacetList (Json Schema Facet List)

This bound property inserts a list of name/value facet properties based upon a comma separated list or * for
all.
December 9, 2019 85
Fi gu re 58 FacetList bound property
and drag a FacetList to an object { } or to an array [ ] under the root object, then double-click the bound
component.

framework.
Facet Csv List text (defaults to * Inserts a list of name and value facet property pairs based
for all) upon a comma-separated list or asterisk (*) for all. Add facet
keys as follows: units,mix,max.
Write Empty true or false Determines if the JSON outputs an empty string when facets
Strings For Missing (default) are missing.
Facets
Tag (J s o n Sc hem a T ag Pro p ert y)

This bound property inserts a single tag value from the bound component into the output.
Fi gu re 59 Tag bound property
and drag a Tag to an object { } or to an array [ ] under the root object, then double-click the bound
component.

framework.
Tag Id tag syntax (n: Identifies a tag to use in the binding search.
name)
Search Parents true or false Configures the search to include parent tags.
(Tag) (default)
If the search does not find a tag on the binding target, this
property, when set to true, searches up the hierarchy for the
closest component with a matching tag id.
86 December 9, 2019
TagList (Json Schema Tag List)

This bound property defines a list of name/value properties based upon selected tags found upon a binding
target.
F ig ure 60 TagList properties
To add this bound property to a schema object or array, expand the B o u n d P r o p e r t i e s folder in the palette
and drag a TagList to the root object { } or to an array [ ] under the root object, then double-click the
bound component.

framework.
Dictionary Name- drop-down list Limits the search based on a tag dictionary name.
space Filter
Tag Id List Filter text Identifies a comma-separated list to limit the tags to be in-
cluded in the output. For example, n:name,n:type or * for all.
If Include Name Space is set to true, the schema adds the
tag dictionary prefix to the key (for example, hs:hvac).
Include Name true (default) or Configures the search to include the tag dictionary prefix in
Space false the key.
Query (Json Schema Query)

This JSON entity sets up a database search. A query can be any valid transform, neql or bql statement, which
returns a BITable.
F ig ure 61 Query properties
To add a query to a schema (JJs o n S c h e m a or R e l a t i v e J s o n S c h e m a ), expand the Q u e r y folder in the palette

and drag a query to the Q u e r i e s folder in the schema.
December 9, 2019 87
You access query properties by double-clicking the J s o n S c h e m a or R e l a t i v e J s o n S c h e m a node in the Nav

tree, expanding the Queries folder followed by expanding the query itself.

Query Ord ord (defaults to Identifies the target object of the query.
null)
RelativeHistoryQuery (Relative History Query)

This query works in conjunction with a RelativeJsonSchema.
Fi gu re 62 RelativeHistoryQuery properties
You add a RelativeHistoryQuery under the Queries folder in the R e l a t i v e J s o n S c h e m a . You access these
properties by double-clicking the R e l a t i v e J s o n S c h e m a node in the Nav tree and expanding the Queries
folder.
Query Pattern bql Prepends to a bql query so query data can be included in the
payload for a given set of points or devices.
For example: %baseHistoryOrd%?period=today|bql:
select timestamp, value
Example
Here is an example of how to use the Query Pattern property to pre-pend the current base item to a bql
query. This example includes query data in the payload for a given set of points or devices:
You may use this with a base query to return a HistoryConfig or a HistoryExt (or the parent of these slots):
C A U T I O N : When creating queries, bear in mind the potential performance implications of running queries
frequently. To reduce the scope of the query, focus the first part of the ord on the location where the data
are likely to be found, or use the stop keyword to prevent depth recursion.
BoundQueryResult (Json Schema Bound Query Result)

This entity determines where and how to insert the results of a query in the payload.
Fi gu re 63 BoundQueryResult properties
88 December 9, 2019
To add this component, expand the Q u e r y folder in the palette and drag a BoundQueryResult to the root
JSON schema O b j e c t of a relative JSON schema.

Query drop-down list Associates this query result with a query ord as defined by a
query under the Q u e r i e s folder. This folder can contain multi-
ple queries.
Output Style drop-down list Defines the output style to render the query in.
JsonAlarmRecipient (Json Alarm Recipient)

This component configures the recipient of JSON alarm output.
F ig ure 64 JsonAlarmRecipient properties
To use this component, expand the A l a r m node in the palette and drag a JsonAlarmRecipient to the C o n -
f i g → S e r v i c e s → A l a r m S e r v i c e folder in the Nav tree.
In addition to the standard properties (Days of the Week, Transitions, Publish Point and Enabled), these
properties configure this alarm recipient.

Time Range, Start hour of the day When used with End Time, sets when to begin reporting alarm
Time (JsonAlarm- records.
Recipient)
Time Range, End hour of the day When configured with Start Time, filters alarm records by
Time (JsonAlarm- defining when to stop returning records.
Recipient)
Publish Point text (defaults to Selects the source.

null)
A l a r m R e c o rd P ro p e r t y ( J s o n S c h e m a A l a r m R e c o rd P ro p e r t y )
These properties are only supported on the JsonAlarmRecipients Schema.
F ig ure 65 Alarm record property
December 9, 2019 89
To use this property, expand the A l a r m node in the palette and drag a AlarmRecordProperty to a sche-
ma’s object folder.
Each of these added to the schema includes the selected Alarm Property in the output. For example the
sourceState, uuid, alarmClass etc. As with other schema Properties, the name is determined by renaming
the property, for example AlarmRecordProperty -> timestamp.

Alarm Property drop-down list Selects alarm properties to add to the JsonSchema.
BF or m atP rop er ty ( B F or m at St ri ng )
This property defines alarm data to extract from the Niagara alarm database. For example, if an engineer
uses the Metadata property of an AlarmExt to record the location of a point in a building, alarmData.lo-
cation could fetch this information and include it in the payload.
Fi gu re 66 BFormatProperty
To use this property, expand the A l a r m node in the palette and drag a BFormatProperty to a schema’s ob-
ject folder.

Format B Format String Defines the BFormat string. For example:
"%idKey%" : "x",
"%valueKey%" : y,
"%slotNameKey%" : "slotName"
Attempt Type true (default) or Converts Booleans and numbers in a formatted string to native
Conversion false JSON Booleans and numbers.
true performs the conversion.
false leaves Booleans and numbers as they are.
Error Substitute drop-down list, de- Controls the role of an error substitute.
faults to Blank
Ignore does nothing.
Key Only substitutes using the location ID.
Blank substitutes nothing.
ExportMarker (Json Export Marker)

Provides a way to mark a component for data export to JSON. You use this method rather than binding to
an ord, bql, neql, or an absolute path.
90 December 9, 2019
The toolkit provides three ways to select control point data for export:
• Add an absolute ord binding to a JSON schema.
• Use bql or neql to identify control points to a relative JSON schema.
• Add a JsonExportMarker to a component.
Marking a component offers several benefits beyond just marking points to include in a RelativeJson-
Schema. For example, markers support the export of alarm and history data for specific points. Markers can
store a unique identifier supplied by a third party platform. This can be used to differentiate between regis-
teredpoints with an ID and unregistered points without an ID. For example, with markers JSON can send dif-
ferent payloads prior to registration including more detailed information (units, min/max, descriptive tags)
than should be sent upon every change of value.
When applied to a numeric point, a JSON export marker introduces a CovTolerance property to reduce
unwanted updates from the station if a value changes only slightly. You may also use the export marker with
incoming JSON payloads.
F ig ure 67 ExportMarker properties
To use this marker, expand the E x p o r t M a r k e r node in the palette and drag an E x p o r t M a r k e r to a point in
the station.
Id (ExportMarker) Provides an id from the cloud platform. The expectation is that
this value will be unique, at least within each station as it may
be used by the cloud platform as a primary key.
Platform Writable true or false Used with the setpoint/override feature to prevent writes from
(ExportMarker) (default) the upstream platform.
filterEnabled true (default) or Turns the filter on and off. When disabled, the schema ignores
false CovTolerance.
CovTolerance number to two Sets up an amount that defines a range of values within which
decimal places a given value may vary without requiring the station to update
the value. This eliminates the overhead required to update
when a value changes only slightly.
lastPublishedValue read-only Reports the most recent value that was exported.
Examples
Example JSON
Base query station:|slot:/|bql:select * from jsonToolkit:
JsonExportMarker
BoundProperty binding ord slot:.. (References the parent of the JsonMarker Base)
December 9, 2019 91
AlarmExportMarkerFilter (Alarm Export Marker Filter)

This filter selects specific alarms before the station passes the data to an alarm recipient. Typically, the recipi-
ent for the filtered alarms would be a JsonAlarmRecipient, but it could be an SNMP, BACnet, etc. recipi-
ent with the source alarm class linked to the In slot of the filter.
Fi gu re 68 AlarmExportMarkerFilter properties
To use this filter, expand the E x p o r t M a r k e r node in the palette and drag an AlarmExportMarkerFilter
to a point in the station.

Current Export Id read-only Provides an ID for the export action.
For HistoryExportMarkerFilters, this ID should be linked into
the schema output to provide identifying information. Or you
could even use a query to select data to include if the target
system could infer useful data from it.
Count read-only Reports how many export marked alarms where processed in
the last invocation. It resets when the station restarts.
Mode drop-down list (de- Selects which alarm records to output to the alarm recipient.
faults to Marked
Marked With Id outputs records that have an ExportMarker
With ID)
on the source component with an Id set.
Marked outputs records that have an ExportMarker on the
source component.
Pass All outputs all alarms.
Block All outputs no alarms.
Action
Action Description
Send Since Queries the alarm database and passes existing records in to this filter (inclusive of the supplied time-
stamp) so that the framework can check them for a suitable export marker and then pass them on to the
receiving JSON schema as required to create a new record for each alarm. The timestamp, being in the
past, should help identify when this mode is active.
HistoryExportMarkerFilter (History Export Marker Filter)

This filter exports history data for points with an export marker. To do so, it adds a new query under the
schema’s Queries folder (if one does not already exist). A BoundQueryResult references this query.
92 December 9, 2019
F ig ure 69 HistoryExportMarkerFilter properties
To use this filter, expand the ExportMarker node in the palette and drag an HistoryExportMarkerFil-
ter to a location in the station.
You access these properties by double-clicking the HistoryExportMarkerFilter node in the Nav tree.
There is some overlap with the RelativeHistoryComponent, which can select point histories using many
different criteria, and an appropriate BaseQuery may also be used to generate history for each export
marked point. The HistoryExportMarkerFilter updates the timestamp stored on each ExportMarker,
so that the schema sends only recent history records to the remote system (typically records added since
the last export).
The History Export Filter container is a JsonSchema nested under the filter. It determines the payload for-
mat, and the output from that schema to link to a target transport point to complete the export.
If a point with an ExportMarker has more than one history extension, the schema exports each in turn.
N O T E : Since the ExportMarker relies on being added to a local control point in the station, it is not possi-
ble to match histories imported over BACnet or the NiagaraNetwork using this filter. Instead, use a
RelativeJsonSchema.
In addition to the standard properties (Enabled, Status, and Fault Cause), the history export filter provides
these properties.

Current Export Id read-only Provides an ID for the export action.
For HistoryExportMarkerFilters, this ID should be linked into
the schema output to provide identifying information. Or you
could even use a query to select data to include if the target
system could infer useful data from it.
Count read-only Reports how many export marked histories where processed
in the last invocation. It resets when the station restarts.
CurrentQuery Identifies the query used by the HistoryExportMarkerFil-
ter’s schema. The first query in the Q u e r i e s folder is linked
on start, but it does not have to be the only query, or output
first data in the JSON schema.
Columns CSV text Defines the columns to appear in the filter. For example,
timestamp, value, status.
Update Send Since true or false Enables and disables the updating of the timestamp stored on
Time (default) the ExportMarker every time the schema exports history.
If true, which means the most recent send time was updated,
the schema sends only the changed records.
If false, the schema sends all history records that meet the
other criteria.
December 9, 2019 93
Actions
Send Since Last Export uses the timestamp stored in each ExportMarker to send only history records
that have not yet been sent.
JsonExportSetpointHandler (Json Export Setpoint Handler)

This component allows an external JSON message to change the value of a control point identified by the ID
property of an export marker.
Locating target points like this can support a station where a unique key registers the points from the cloud
platform. Once the cloud platform returns a suitable identifier for an export-marked point, you can use this
setpoint handler to apply write messages from the platform using the ID, rather than the Niagara slot or han-
dle ord (for example).
Fi gu re 70 JsonExportSetpointHandler properties
To add this handler to a station, expand the E x p o r t M a r k e r folder in the palette and drag this component to
the router folder in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonExportSetpointHandler.

Last Result read-only Reports the results of the alarm acknowledgment to allow for
logging or post-processing activity. Example output:
Unable to find messagge key:
Problem parsing messageType
Last Result Time read-only Reports when the handler ran last.
Last Input read-only Reports the last message routed to a component.
Id Key text Defines which top-level key in the JSON payload represents
the point Id.
Value Key text (defaults to Defines which top-level key in the JSON payload represents
value) the value to set.
Slot Name Key text (defaults to Defines the optional top-level key in the JSON payload that
slotName) represents the slot name to write to.
Default Write Slot text Defines the slot to write to by default if the payload does not
(JsonExportSet- specify the slot.
pointHandler,
SetPointHandler)
94 December 9, 2019
JsonExportRegistrationHandler (Json Export Registration Handler)

This component works with the JsonExportSetpointHandler to apply a unique identifier from an exter-
nal system to an export marker.
This allows the cloud (or other external system) target to assign it’s own identifier or primary key to export-
marked points in the Niagara station, which can be used to locate them in future, or included in exports to
that cloud system.
F ig ure 71 JsonExportRegistrationHandler properties
In addition to the standard property (Enabled), these properties support the
JsonExportRegistrationHandler.

Remote Key text (defaults to Identifies the name of the JSON property that denotes the
platformId) point's identifier in the remote system.
Local Key text (defaults to Identifies the name of the JSON property that denotes the
niagaraId) point’s identifier in the Niagara station.
Syntax
{
}
or
{
}
December 9, 2019 95
N O T E : This class does not use the messageType, which would be used simply to route it to this handler
and so can be changed as needed.
Example
This W i r e S h e e t and JSON loosely demonstrate some of the routers and selectors based upon a fictional
Fi gu re 72 Json Export Registration Handler example Wire Sheet and JSON
J so nE xp or tD ereg i st ra tio nH and l er ( J s on E xp or t De reg is tr ati on H and l er)

This component works with the JsonExportSetpointHandler to remove a unique identifier from an ex-
ternal system to an export marker.
Fi gu re 73 JsonExportDeregistrationHandler properties
In addition to the standard property (Enabled), these properties support the
JsonExportDeregistrationHandler.
96 December 9, 2019

Remote Key text (defaults to Identifies the name of the JSON property that denotes the
platformId) point's identifier in the remote system.
Syntax
{
}
or
{
}
N O T E : This class does not use the messageType, which would be used simply to route it to this handler
and so can be changed as needed.
Example
This Wire Sheet and JSON loosely demonstrate some of the routers and selectors based upon a fictional
December 9, 2019 97
Fi gu re 74 Json Export Registration Handler example Wire Sheet and JSON
JsonMessageRouter (Json Message Router)

This component transfers inbound messages to an onward component that is suitable for processing or han-
dling the message.
This allows the cloud (or other external system) target to assign it’s own identifier or primary key to export-
marked points in the Niagara station, which can be used to locate them in future, or included in exports to
that cloud system.
Fi gu re 75 JsonMessageRouter properties
You add this router to a station by expanding the I n b o u n d → R o u t e r s in the palette and dragging this com-
ponent to the C o n f i g folder in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonMessageRouter.

98 December 9, 2019

Learn Mode true or false true configures the JSON to add a dynamic slot on input for
(default) any newly-found message key.
Key text (defaults to Defines which part of the incoming message to switch on)
messageType)
Resend With Blank true or false Turns on and off the resending of a message if a duplicate or
(default) matching message is received.
true causes the router to send an empty string to the target
slot, then resend the output.
Without injecting an empty message, the link does not propa-
gate the change, which could be an issue if the handler needed
other values in place to respond to this message.
false does not send the empty string to the target slot, which
does not resend the output.
JsonDemuxRouter (Json Dmux Router)

Unlike the JsonMessageRouter, which forwards the whole JSON payload to the added slots intact, this
component passes a selected part of the message to the added slots. It is a very basic method of selecting
data of interest, and likely will become inefficient to use when faced with a large payload and chained
routers. An approach with far more features is JSON Path.
The added slots must match the key name and should be either Boolean, numeric or string to match the
JSON value.
F ig ure 76 JsonDemuxRouter properties
You add this router to a station by expanding the I n b o u n d → R o u t e r s in the palette and dragging this com-
ponent to the C o n f i g folder in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonDemuxRouter.
December 9, 2019 99

Learn Mode true or false true configures the JSON to add a dynamic slot on input for
(default) any newly-found message key.
Default Missing true (default) or Can set a dynamic slot’s value to its default if the value is
false missing.
true sets the value to its default if the inbound JSON mes-
sage did not include a value for the slot.
false ignores setting the default value.
JsonPath (Json Path)

Selectors are components that take an inbound JSON message, apply some selection criteria to it, and set
up the result an out slot. This might be a subset of the JSON. It could be, for example, the size of a message
or the result of an aggregate function, such as the sum of a repeated value. This selector component allows
data to be interactively located and extracted from JSON structures using a special notation to represent
the payload structure.
Fi gu re 77 JsonPath properties
You add this selector to a station by expanding I n b o u n d → S e l e c t o r s in the palette and dragging the Json-
Path to a JSON message router node in the Nav tree.
In addition to the standard properties (Enabled and Status), these properties support the JsonPath.

100 December 9, 2019


Out read-only Displays the result.
Path (JsonPath) text Defines the path.
JsonAtArrayIndex (Json At Array Index)

This component selects a value in a JSON array by array index.
F ig ure 78 JsonAtArrayIndex properties
You add this selector to a station by expanding I n b o u n d → S e l e c t o r s in the palette and dragging the JsonA-
tArrayIndex to a message router in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonAtArrayIndex.

Index number Defines the index in the JSON array.
JsonContainsKey (Json Contains Key)

This selector returns a Boolean value if the specified key is present in the payload.
F ig ure 79 JsonContainsKey properties
ContainsKey to a message router in the Nav tree.
December 9, 2019 101

In addition to the standard property (Enabled), these properties support the JsonContainsKey.


messageType)
JsonIndexOf (Json Index Of Key Selector)

This component returns the index of a given key within a JSON object.
Fi gu re 80 JsonIdexOf properties
You add this selector to a station by expanding I n b o u n d → S e l e c t o r s in the palette and dragging the Jso-
nIndexOf to a message router in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonIndexOf.


messageType)
JsonSum (Json Sum Selector)

This selector sums all values found in the payload that match the key (numeric values parsed only).

F ig ure 81 JsonSum properties
Sum to a message router in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonSum.


messageType)
JsonLength (Json Length Selector)

This selector returns the length of the first object or array that matches the key.
F ig ure 82 JsonLength properties
Length to a message router in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonLength.



messageType)
JsonFindAll (Json Find All Selector)

This selector returns all values in an array that match the key.
Fi gu re 83 JsonFindAll properties
FindAll to a message router in the Nav tree.
In addition to the standard property (Enabled), these properties support the JsonFindAll.


messageType)
AlarmUuidAckHandler (Alarm Uuid Ack Handler)

If the alarms exported from a station include a unique ID (UUID), this component passes back the UUID.

Message handlers are components designed to perform a specific task with the data routed and selected via
the other inbound components.
F ig ure 84 AlarmUuidAckHandler properties
You add this handler to a station by expanding the I n b o u n d → H a n d l e r s folder in the palette and dragging
this component to a message router in the Nav tree.
In addition to the standard property (Enabled), these properties support the AlarmUuidAckHandler:

Ack Source text Configures a string to append to every alarm record acknowl-
edgement. This string can provide additional information for
future auditing. The alarm data record stores it as AckSource.
Ack Result Reports the results of the alarm acknowledgment for logging
or post processing activity.
Example
The expected format for this component is:
{
"user": "Maya",
"alarms": [ "5cf9c8b2-1542-42ba-a1fd-5f753c777bc0" ]
}
This array allows the system to acknowledge multiple alarms at once.
The alarm record stores the user value, which identifies the user who acknowledged the alarm in the remote
application. If the user key is omitted, the component still tries to acknowledge the alarms using the fallback
name: AlarmUuidAckUser.
NOTE:
The J s o n S c h e m a S e r v i c e ’s Run As User property is a prerequisite for this handler to work. The specified
user must have admin write permissions for the alarm class of the records being acknowledged.
SetPointHandler (Json Set Point Handler)

This handler sets incoming setpoint values to control writable control points.
Override, duration, the status parameter and nested keys are not supported.

Fi gu re 85 SetpointHandler properties
You add this handler to a station by expanding the I n b o u n d → H a n d l e r s folder in the palette and dragging
this component to a message router in the Nav tree.
N O T E : The Run As User property in the J s o n S c h e m a S e r v i c e is required to use the SetPointHandler.
In addition to the standard property (Enabled), these properties support the SetPointHandler:

Id Key text Defines which top-level key in the JSON payload represents
the point Id.
Value Key text (defaults to Defines which top-level key in the JSON payload represents
value) the value to set.
Slot Name Key text (defaults to Defines the optional top-level key in the JSON payload that
slotName) represents the slot name to write to.
Default Write Slot text Defines the slot to write to by default if the payload does not
specify the slot.
EngineCycleMessageQueue (Engine Cycle Message Queue)

When the system generates JSON very quickly, this component can provide a buffer between the data
source and destination control point to prevent potential discards within the same engine cycle. Using this
component ensures that the JSON processes all messages.
Fi gu re 86 EngineCycleMessageQueue property
You add this queue to a station by expanding the I n b o u n d → H a n d l e r s folder in the palette and dragging this
component to a message router in the Nav tree.
For example, you can link a string output slot to onward points or, where necessary, to an
EngineCycleMessageQueue.

To buffer incoming messages when using this component, it is advisable to link from the readValue on a
proxyExt rather than from the out slot of its parent point.

EngineCycleMessageAndBaseQueue (Engine Cycle Pair Queue)

F ig ure 87 EngineCycleMessageAndBaseQueue property
You add this queue to a station by expanding the I n b o u n d → H a n d l e r s folder in the palette and dragging this
component to a message router in the Nav tree.

Out
Inl ine Jso nWri ter (Inl in e Jso n Wri te r)

This feature supports custom JSON code.
You achieve this using a program object as per the example in the P ro g r a m s folder of the jsonToolkit pa-
lette. You can extend BAbstractInlineJsonWriter. Extending the abstract class would be preferred
where the program object may be widely distributed, as code contained in a module is easier to maintain.
F ig ure 88 InlineJsonWriter code properties
To use this program object, drag it from the P ro g r a m s folder in the jsonToolkit palette to the C o n f i g
folder in the station. To open this A X P r o p e r t y S h e e t , double-click the InlineJsonWriter component in
the station.
To view the example code, right–click the P ro g r a m node, clickV
Vi e w s → P r o g r a m E d i t o r and click the E d i t
tab.
In addition to the standard properties (Status and Fault Cause), these properties support the
InlineJsonWriter.


Class Name read-only Reports the name that describes this object. Each object is cre-
ated from a single class. One class can instantiate multiple
objects.
Class File read-only Reports the name of the file that contains the custom
program.
Dependencies read-only Identifies the dependent modules.
Signature read-only Identifies the mathematical scheme used to verify the authen-
ticity of the program.
Ty p e O v e r r i d e ( Ty p e O v e r r i d e )
This component is an example of a program to override a data type.
Fi gu re 89 TypeOverride properties
To use this program object, drag it from the P r o g r a m s folder in the jsonToolkit palette to the C o n f i g
folder in the station. To open its A X P ro p e r t y S h e e t , double-click the TypeOverride object in the station.
To view the example code, right–click the E x a m p l e O v e r r i d e node, clickV
Vi e w s → P r o g r a m E d i t o r and, if
needed, click the E d i t tab.
In addition to the standard properties (Status and Fault Cause), these properties support the TypeOverr-
ide example. These properties are part of the Program component from the Program module and are not
specific to the JSON Toolkit.

objects.
program.


Source read-only Displays the program’s source code.
User Defined read-only Displays user-defined custom imports of the types used in the
Imports source code.
rel ati veT o p ic B uil d er ( Prog r am )

This program object uses an instance-based class file to implement your component logic. You view and edit
the program using the ProgramEditor.
F ig ure 90 relativeTopicBuilder properties
To use this object, drag it from the P r o g r a m s folder in the jsonToolkit palette to the C o n f i g folder in the
station. To open this A X P ro p e r t y S h e e t , double-click the relativeTopicBuilder component in the
station.
In addition to the standard properties (Status and Fault Cause), these properties support the
relativeTopicBuilder.

objects.
program.
Source read-only Displays the program’s source code.
User Defined read-only Displays user-defined custom imports of the types used in the
Imports source code.


topicTemplate text Defines a template string for the output topic in a Java-format
style.
For example, %s represents a replaceable substring. The sche-
ma resolves these against the object it passes to the input slot
and writes the result to the topicOutput.
topicOutput read-only Identifies the destination for the output JSON.
Actions
Execute takes some input, does whatever the action should (including

Index
A export marker .............................................. 28, 90
export registration handler .................................95
about this guide ...................................................7 export setpoint handler ................................ 48, 94
alarm exporting ...........................................................17
acknowledging................................................64
export marker filter .........................................92
recipient .........................................................89
record property...............................................89
F
records ...........................................................36 facet list .............................................................85
Alarm Uuid Ack Handler......................................47 facets .................................................................85
alarm UUID acknowledgment handler................ 104 features..............................................................12
alarms ................................................................35 find all .............................................................. 104
Apache Velocity..................................................61 fixed boolean .....................................................82
API.....................................................................57 fixed numeric .....................................................81
array ............................................................ 11, 80 fixed string .........................................................81
at array index ................................................... 101
G
B global cov slot filter ............................................78
base query .........................................................75
BFormat property...............................................90
binding ..............................................................21 H
bound array........................................................80
bound CSV property ...........................................84 handlers .............................................................47
bound object......................................................79 history export marker filter .................................92
bound property ..................................................83
bound query result ....................................... 74, 88
builder class .......................................................57 I
inbound components ..........................................43
index of............................................................ 102
C inline json writer ......................................... 54, 107
client-side target media ......................................12 introduction .........................................................9
components .......................................................65
contains key ..................................................... 101
count .................................................................82 J
current time .......................................................82 JSON alarm recipient..........................................36
custom content ..................................................57 Json Schema ......................................................66
json schema config folder ...................................67
Json schema service ...........................................13
D Json Schema Service...........................................14
debug .......................................................... 70–71 jsonPath
demux router .....................................................99 applying selection criteria ................................46
developer guide .................................................51 JsonSchemaService ............................................76
device
connecting ......................................................40
document change log ...........................................7 K
key/value pair.....................................................11
E
engine cycle message queue ......................106–107 L
examples...................................................... 11, 38 length .............................................................. 103
export................................................................38 license
export deregistration handler .............................96 expiration .......................................................77

Index Niagara JSON Toolkit Guide
requirements ..................................................13 S
S M A expiration .................................................77
schema...............................................................25
M construction....................................................21
message generation ......................................................58
router .............................................................98 properties .......................................................66
routing a a subset of a payload ........................44 types ..............................................................51
routing the whole payload ...............................43 selectors ............................................................46
methods.............................................................57 setpoint handler ......................................... 48, 105
metrics...............................................................71 SMA expiration monitor ......................................13
structure ............................................................20
subscription .......................................................62
N subscription slot blacklist ....................................78
sum.................................................................. 102
naming conventions............................................18
O T
tag .....................................................................86
object ..................................................... 11, 22, 78
tag list................................................................87
output................................................................38
transport protocols.............................................12
control ............................................................19
troubleshooting..................................................71
history, viewing ...............................................20
tuning policy................................................. 19, 69
overrides............................................................19
type override.............................................. 53, 108
folder..............................................................70
P U
path ................................................................. 100 Unix time............................................................83
property....................................................... 81–82 use cases, transport protocols, JSON Toolkit
Px target media features ............................................................11
about types of.................................................12
Hx PxMedia ....................................................12
Mobile PxMedia ..............................................12 V
Report PxMedia ..............................................12 visualization.................................................. 33, 41
WbPxMedia ....................................................12
Q
queries......................................................... 30, 73
bound query result ..........................................31
folder..............................................................30
query ..............................................................30
relative history query .......................................31
query ...................................................... 55, 73, 87
ad hoc.............................................................33
base query ......................................................33
R
related documentation .........................................7
relative history query .................................... 74, 88
relative Json schema..................................... 27, 75
relative topic builder................................... 53, 109
Run As User........................................................14

Glossary
binding A relationship between a widget in a station and a data source, such as a point,
slot, component, tag, etc.
The most common binding, a value binding, provides information for
presentation as text or a graphic. Bindings include mouse-over and right-click
actions, and a way to animate any property of its parent widget using
converters that convert the target object into a property value.
payload The objects, arrays and key/value pairs contained between open and close
curly brackets that conform to JSON syntax.
subscription A method for updating a station with the current value of a remote
component. When a remote component’s value changes, subscription
synchronizes the related proxy point’s value in the station with the current
value of the remote component. Subscription occurs in real time.

DR-JSON Manual

Uploaded by

DR-JSON Manual

Uploaded by

Technical Document

Niagara JSON Toolkit Guide

Copyright and patent notice

Chapter 1 Introduction .....................................................................................9

Chapter 2 Exporting with a JSON schema ......................................................17

Chapter 3 Importing JSON .............................................................................43

Chapter 4 Developer guide ............................................................................51

Type Override example ............................................................................53

AlarmRecordProperty (Json Schema Alarm Record Property) .....................89

Document change log

Fi gu re 1 Logical JSON flow

F ig ure 2 JSON workflow

Quick JSON example

JSON Toolkit use cases

Li c ens e req uirem e nts

JSON schema service

Global Cov Slot Filter

Operation Optional? How it works

Debugging with Spy page

Fi gu re 4 JsonSchmaService Spy page link

NiagaraNetwork point export

• Example schema base query: station:|sys:|neql:n:point|bql:select *

NiagaraNetwork schema export

F ig ure 5 Schema parts

Entity Type Output

Array “arrayName” :[value, value2….]

Property “key”: value

Property List “key”: value, “key2”: value2

Fi gu re 6 root Json Schema Object

F ig ure 7 Config properties

• Name Casing Rule conforms names to camel case or another style.

JSON schema metrics

Queries Generation Subscription

Query Folder Executions Request Schema Generations Subscribes

Individual Query Executions Schema Generations Unsubscribes

Query Fails Schema Generation Fails Subscription Events

Last Query Execution Millis Output Changes Cache Hits

Query Execution Millis Total Last Output Size Cache Misses

Query Execution Millis Max Output Size Total

Query Execution Millis Avg Output Size Max

Output Size Avg

Binding configuration, about binding

F ig ure 10 Slots to include

Strings The string value is unchanged

Booleans A JSON Boolean

Integer/Long A JSON number

Enum value A JSON String that represents the Enum value

Status A JSON string to represent the value, for example, {ok}

Display Name The name of the bound property, object or array

Target Name The name of the ord target

Target Display Name The display name of the ord target

Target Parent Name The name of the ord target’s parent

F ig ure 11 A Json Schema Bound Object

F ig ure 14 Message properties

Crea tin g a reg ul ar sc hem a

Relative schema construction

Base query examples

Exp ort ma r ke r : se le ct i ng co nt rol poi nt s

Alarm export marker filter

F ig ure 15 Wire Sheet showing the use of an export marker filter

Filter mode Outputs alarms

Marked If the source has an export marker present

Pass All All alarms

Block All No alarms

BACnet points currently in {override} status slot:/Drivers/BacnetNetwork|bql:select name, out.value from

History records history:/Newhaven/waveHeight|bql:select timestamp, value

Output from a series transform station:|transform:slot:/VelocityServlet/lineChart/

Alarm database contents alarm:|bql:select timestamp, uuid, ackState, source as

Relative history query

Row array with header

Named objects (The first column is as-

Column array with header

Single column array

F ig ure 17 Device connectivity JSON payload

Exporting schema output (JsonExporter)

Step 2 Select the exporter and where to view.

/+ ------------ END BAJA AUTO GENERATED CODE -------------- +/