AdHoc Events (version 23)

Knowledge Base / Version 23 / Client Tools / Excel Add-in

updated 1 yr ago

The 'AdHoc Events' function allows the user to search for events on the fly that are not already configured within Canary's Calcs & Events service.

View

Select an available 'View' from the drop down list. This list is read from the Views service on the machine the endpoint is set to and includes the raw historian view as well as any virtual views that may be available. This can also reference a cell containing the name of the view. To set a cell reference, make sure the selection box has focus and the text area is empty. "CTRL-click" on the desired cell and a cell reference will be written into the input parameter.

Expression Base Path

This is the base path for tags used in the expressions which allows the user to drill down into a specific branch within the view when searching for an event.

Asset Type

If an asset type is selected, the search is applied across the list of this asset type within the view. This option is only available if selecting a virtual view from the 'View' drop-down list in which assets have been defined.

Search From/To

This can be an absolute date (2/9/2021 12:00:00 AM) or a relative one (Now-7d). If the field is empty, the Search From is defined as the earliest possible time and the Search To as the latest possible time. An absolute time can by typed or selected via the calender that is activated by clicking on the down arrow at the end of the field. To set a cell reference, make sure the selection box has focus and the text area is empty, "CTRL-click" on the desired cell and a cell reference will be written into the input parameter.

Start/End Trigger Expression

This is an expression that evaluates to True or False. If the Start Trigger evaluates to TRUE, then this is defined as the beginning of an event. Then the End Trigger is evaluated on the data to find where an event ends. If the End Trigger Expression is empty, the reverse of the Start Trigger Expression becomes the End Trigger. An expression may look like [Tag1] > 6.0. This expression will evaluate the data stream of the tag (starting at Search From) looking for the [Tag1] tag to be above the value of 6.0. Tag names are enclosed within square brackets [ ]. The tag is read from the specified view. The full tag name is the Expression Base Path or Asset Instance with the tag name from the expression appended to the end.

Multiple tags can be incorporated into the expression:

[Tag1] > 6.1 && [Tag2] < 150

The evaluation process is case sensitive and includes the following:

Logical Operators: or, ||, and, &&
Relational Operators: =, ==, !=, <>, <, <=, >, >=
Math Operators: +, -, *, /, %
Bitwise Operators: & (bitwise and), | (bitwise or), ^(bitwise xor), << (left shift), >>(right shift)
Unary Operators: !, not, -, ~ (bitwise not)
Primary Operators: ( )
Values: Integers, Floating point numbers, Scientific
notation, Dates and Times, Booleans, Strings
Functions: Abs, Acos, Asin, Atan, Ceiling, Cos, Exp, Floor, IEEERemainder, Log, Log10, Max, Min, Pow, Round, Sign, Sin, Sqrt, Tan,
Truncate

Min. Event Duration

If no duration is set, all events matching the criteria will be returned within the 'Search To/From' range. If set, the event must last for the minimum duration before it will be reported. The input can be 00:10:00 for a 10-minute duration, or 10m.

Max. Number of Events

An absolute maximum of 10,000 events will be returned in a single search. The search will stop when the maximum number of events is reached.

Event Properties

When an event is found, the user can define properties that are computed across the range of the event. The property must be given a name and an equation. For example, Avg may be the property name and TimeAverage2([Tag1]) may be the equation. In this case, when the end of an event is found, it will compute the TimeAverage2 aggregate for the [Tag1] tag across the entire time span of the event. The equation functionality is the same as used in the expressions. All available Canary Aggregate functions can be used. An equation of Maximum2([Tag1])+10.0 will find the maximum value across the interval and then add 10 to it.

A special condition occurs when an Aggregate name contains ActualTime. For example, MaximumActualTime2. In this case, 2 property columns are returned, one for the max value and another for the time when the max value occurred.

Sort Order

Events can be returned in ascending or descending order.

Sort By

This field is used to sort the data. It can be any of the standard fields or event properties.

Starts At
Ends At
Duration
Source

Display Fields

If a display field name is checked, that field will be included in the output results. The order of the display field names is the order of the fields in the output result. To rearrange the order, click a field and then press the up/down buttons along the right side. You can also drag and drop fields to rearrange the order. The function parameter is a comma separated string of selected options.

Show Headers

If checked, a heading for each display field will be included in the output.

Starts At
Ends At
Duration
Source
Properties - will show all properties defined in separate columns

Progress Report Location

The output cell location where statistics will be shown. This setting is optional. If left blank, no statistics will be shown during the load of ad hoc events. To set a new cell reference, select the cell and press the 'Set' button beside the field.

Output Location

The cell location where the results will be posted, adding columns to the right and rows down. The default 'Output Location' cell is set to the cell that has focus when the Ribbon button for this function is selected. To set a new cell reference, select the cell and press the 'Set' button beside the field.

When using input parameters referencing other cells, if the input cell changes it will automatically update the resulting data.

The Input Pane can be closed at any time by clicking on the X in the upper right corner. To re-open the Pane, click on the Canary Ribbon "Adhoc Events" button. If the cell containing an existing Canary2 function has the focus and the user selects the corresponding function button from the Canary Ribbon, the input controls in the Pane will be set according to the parameters of the Canary2 function.

Because the search operation can take a long time, this is an asynchronous call in Excel. It will display #GettingData- until the function completes (Which could be a long time several minutes). When the search completes, the results are displayed. The actual search operation happens within the Views Service. To complete the search, Excel will repeatedly call into the View Service, picking up where it previously left off.

If an error occurs during the search, an error message will be appended after the events already found are returned.

If an Event started, but did not finish before it reached the Search To time, a partial event will be generated. In this case, the "Ends At" field will be will blank.

Properties are computed from the beginning of the event to the end of the event.