Skip to content

Working with Niagara Schedules

Jump to bottom
Richard McElhinney edited this page Aug 25, 2023 · 6 revisions

Since 3.0.4

Support for Niagara Schedules

'nhaystack' now includes support for reading events out of a weekly schedule. A weekly schedule can output different types of values and the support for the weekly schedule includes the reading of schedules that output a BStatusNumeric, BStatusBoolean or a BStatusString. A schedule can be added to a Niagara Station by opening up the 'schedule' palette in the Niagara Workbench and dragging/dropping a:

  • Numeric Schedule
  • String Schedule
  • Boolean Schedule

onto a wiresheet. Once a user has configured the weekly schedule events and rebuilt the 'nhaystack' cache it is now possible to use the REST API to read the events. Note, at this time only weekly schedule events are supported, Special Events such as public holidays are not yet supported or reported via the nhaystack REST API.

How to interact with schedules via REST

Step 1 - Identify a schedule

The first step to reading the events out of a schedule is to be able to identify the schedule within the Niagara Station. Of course adding tags can assist. Using the standard Niagara Workbench tools you could add a tag from an existing Niagara Tag Dictionary or you could add your own custom tag from your own Tag Dictionary.

TIP: in this example the 'schedule' marker tag comes from the built-in Niagara Tag Dictionary and is in the Niagara ('n') namespace. To use other Tag Dictionaries the namespace must be configured in the NHaystackService using the 'prioritizedNamespaces' slot. For example, to do this you would want to set this slot to the value of "hs,n" indicating that the NHaystackService should use the Haystack Dictionary first and then look for tags out of the Niagara Dictionary.

It is also possible to use one of the implied tags on the schedule when doing queries. Although, this may return more than one schedule depending on how many schedules of a particular type are configured in your station. For example, one implied tag on a schedule is the 'n:type' tag and for a Boolean schedule the value is set to "schedule:BooleanSchedule". So it would be possible to apply a filter query over the Haystack REST API of:

type="schedule:BooleanSchedule"

Step 2 - Execute a 'read' against the schedule

The next step is to try and to execute the standard 'read' Op against a schedule using a HTTP GET request. As discussed above it is important to be able to identify a schedule or schedules in the Niagara Station. There are a few examples below that demonstrate different ways to do a read on a schedule:

The first example will read all schedules in the Niagara Station with the standard implied tag 'n:schedule'. In this case you may get one or more results. The second example will read all schedules in the Niagara Station that have the implied tag of 'n:type' with the value of "schedule:BooleanSchedule". In this case you may get one or more results. The third example will read a specific schedule identified by it's unique 'hs:id' tag. In this case you will always only get one result.

When executing a 'read' Op against one or more schedules you will get a Zinc Grid serialized to text with a number of tags including the current output of the schedule.

Step 3 - Read the schedule events

'nhaystack' now includes support for reading the weekly events out of a schedule. To do this the standard 'pointWrite' Op is used. To read a single schedule the following HTTP GET request should be executed:

https://localhost/haystack/[email protected]

Note that the 'pointWrite' Op only works against a single Niagara point at a time. This defined in the Haystack REST API here.

When executing this request, assuming the schedule has been configured with regular weekly events, a Zinc Grid will be returned in serialized text format with something similar to the following:

ver:"3.0"
scheduleGrid,tz,dis,enum,schedule
<<
ver:"3.0"
end,val,weekdays,start,dates
16:30:00,T,"0",09:00:00,"N"
00:00:00,T,"1",08:00:00,"N"
03:00:00,T,"2",00:00:00,"N"
00:00:00,T,"2",07:00:00,"N"
19:00:00,T,"3",01:00:00,"N"
04:00:00,T,"4",03:00:00,"N"
15:30:00,T,"4",13:30:00,"N"
21:00:00,T,"4",19:00:00,"N"
07:00:00,T,"5",04:00:00,"N"
12:30:00,T,"5",11:00:00,"N"
15:30:00,T,"5",14:00:00,"N"
17:30:00,T,"5",16:30:00,"N"
21:00:00,T,"6",02:00:00,"N"
>>,"Australia/Sydney","BooleanSchedule","false,true",M

Clone this wiki locally