NHaystack Client

7. Using NHaystack as a client

NHaystack can also model remote haystack servers as N4 devices. This is done via a standard N4 driver that maps the Haystack protocol into the N4 driver framework.

You do not need to have an NHaystackService installed in your station to do this -- the driver is a standalone piece of functionality. In fact you shouldn't have an NHaystackService in the station unless you are acting simultaneously as a server and a client.

To get started, open the nhaystack palette in Workbench, open the "drivers" sub-folder of the palette, and drag-and-drop the NHaystackNetwork onto the "/Drivers" folder of your station. Then drag an NHaystackServer so that it is underneath your NHaystackNetwork.

Next, configure the internetAddress, uriPath, and credentials slots on the NHaystackServer. The internetAddress adress should just be the hostname or IP address (plus a colon and then the port number if something other than port 80 is being used). The uriPath should be of the form "api/myProjectName" if the remote server is running FIN|Stack or SkySpark. If the remote server is an N4 station that is running nhaystack-as-a-server, then the uriPath should simply be "haystack".

After you've configured the NHaystackServer, manually do a ping to make sure its connected. Once connectivity has been established, you can go to the "points" and "histories" folders of the NHaystackServer object, and discover points and histories just like any other Niagara driver.

Note that currently, the driver imports "Str" points as Baja BStringPoint and BStringWritable objects, even if the haystack point has an enum tag which specifies a list allowable values. BEnumPoint and BEnumWritable objects are currently not created by the driver. Instead, the enum tag is stored as a 'range' facet on the N4 ControlPoint.

New Proposal

7.1 Exporting history to another Project Haystack server

The NHaystack client can be used to push history (or time series)data stored on the Niagara station to an upstream Project Haystack-compatible server. This feature is an optional feature for a Project Haystack server to implement.

The NHaystack History Export Manager can be found by right-clicking on Histories beneath your Project Haystack server instance and selecting Views -> NHaystack History Export Manager. From here, clicking Discover will present you with a list of all the histories on the station.

After selecting the histories of interest, click Add, and you'll be presented with a dialogue box listing the histories and the options to be set.

From this form, each history in the Niagara station must be associated with the unique Ref of the point in the remote Project Haystack server to which it will write its historical data. There are three ways this can be done.

7.1.1

The lowest-common denominator method here is to use a standard Project Haystack client to get a list of valid points from your server, then manually copying the id of each point into the Id field on the Add form.

***** Question: should this be added into Niagara so a list of points in the remote Project Haystack server can be retrieved and then these manually matched? Or do you assume retrieving the list of points is done outside of Niagara?

This should work for any Project Haystack server. The point in the remote Project Haystack server is assumed to carry a his tag, be of the correct kind for the type of history being exported, and either carries a tz tag matching that of the history, or is on a server that supports time-zone conversion.

For more detail on tagging assumptions, see section 7.1.2 below.

7.1.2 Automatic look-up using nstation and nhistoryid

Depending on the Project Haystack server, it may be easier to retrieve a list of histories from the station and tag the points so the station can find them. Such a list can be obtained from Workbench via the following procedure:

1. Double click on your station's "History" space (it'll take you to a chart view)
   

2. Press CTRL+L to bring up the ORD dialogue
   

3. At the end of the text field (after `history:|`), add `bql:select id, recordType, timeZone from /`
   

4. From the File menu, select Export.
   

5. Choose "Text to CSV" and "Save to File"
   

6. Enter the path where you want the file and click OK.
   

Filter out of that list the histories you want to upload. To associate a history in this list to a point in your asset model, tag the point with the following two tags:

• nstation (Str): should be the name of your Niagara station (as seen in the brackets in the Workbench navigation tree, e.g. mystation)
• nhistoryid (Str): should be the ID of the history taken from your BQL query dump

The point will also need to have kind and tz setup properly:

• Histories of type history:NumericTrendRecord should be tagged with kind=="Number". Ideally these should also be tagged unit (Str) with an appropriate Project Haystack unit
• Histories of type history:BooleanTrendRecord should be tagged with kind=="Bool"
• Histories of type history:EnumTrendRecord should be tagged enum (Str) with a comma-separated list of valid enum values
• Histories of other types should be tagged with kind=="Str"

7.1.3 Automatic creation of points

If the server supports the createRec call, then points will be automatically created on the Project Haystack server. The station will issue a HTTP POST instruction to the server's createRec endpoint with a single-row grid containing the following columns:

• name (Str): This will be the name of the control point, or if that's not known, the name of the history.
• dis (Str): This will be the Display Name of the control point (or history), or if those are blank/null/not known, the name of the new point.
• point (Marker)
• his (Marker)
• kind (Str): The point kind; one of Str, Bool or Number, depending on the type of history being exported.
• tz (Str): The timezone of the history (this is set in the Add dialogue, default is automatically determined from the history database).
• nstation (Str): The name of the Niagara station exporting the history
• nhistoryid (Str): The ID of the history being exported
• nslotpath (Str): If known, the slot path of the control point (may be omitted if not known).
• unit (Str): If known and history is a NumericTrendRecord, the measurement unit for the control point
• enum (Str): If known and history is a EnumTrendRecord, the list of valid enumeration values for the control point

It is assumed that siteRef and equipRef are optional and can be filled in later via other CRUD ops by the end user. The nstation and nhistoryid should be used to obtain listings of the orphaned point entities so they can be associated with the correct site and equip.

7.2 Fine tuning payload sizes

The number of records exported at a time can be tuned by configuring the Upload Size. This is a count of the number of rows used in each hisWrite request. It defaults to 10000, which depending on the server may work, or may result in a "Request Entity Too Large" error message from the server.

In such cases, the driver will automatically divide this value by two and try again, so if the server experiences difficulty processing the set number of records, you'll see smaller payloads (5000, 2500, 1250, etc) attempted. (It will not go any smaller than 1 record.)

You can manually set this value to any payload size suits your requirements.

7.3 Setting an alternate start point

By default, exports begin at the very first record in the history. This can be configured via the "Upload From Time" field. This specifies the start point for the very next export task.

It can be used to "skip over" invalid data that was captured during the commissioning process, as well as to re-upload data in the event that data is lost or corrupted on the upstream Project Haystack server.