Calcs & Events Tile (version 25)

Knowledge Base / Version 25 / System Admin Duties / Canary Admin

21 hrs ago

Major updates to the Calcs & Events tile which are reflected in this article occurred in v25.4. If using versions 24-25.3.1 click here.

Active Jobs - number of active calcs/events currently running
Errored Jobs - number of calcs/events in an errored state
Tags Writing - number of calc tags being written to the Historian
Hourly TVQs - number of TVQs (timestamp/value/quality) written to the Historian in the last hour
Hourly Events - number of events that have been generated in the last hour
Version - versioning number of the Calculation service

Jobs Screen

The Jobs screen provides an overview of the calculations and events that are configured within the Canary system. Calc tags () are written to the Historian using the Store & Forward service. Events () are written to a SQLite database or an external MSSQL database if configured to do so.

Name Filter - filters the jobs table based on the JOB NAME column. Keywords can be separated by spaces and prepended with an exclamation mark (!) to exclude them from the search.
START - starts the selected job(s). Multiple jobs can be selected using Ctrl+Click or Shift+Click.
STOP - stops the selected job(s)
+ADD - opens the screen to create a new calc/event. If an event is highlighted in the jobs table, the user has the option of adding a child event using the drop-down arrow. Child events are indented and placed under their parent event within the jobs table.
EDIT - opens a screen to edit the selected calc/event. Double-clicking the row itself will also open the screen to edit the job.
COPY - copies the selected job and opens a new screen to edit the calc/event
DELETE - prompts the user to delete the selected job(s) and the tag(s)/event(s) associated with it. When a calculation is deleted, the tag is renamed with the prefix 'zObsoleted [dateTime]...' and flagged for obsoletion. It will remain in the current file, but will be removed from client queries. The tag will not be carried over into the next HDB file when the Historian performs its next roll-over.

MORE - opens a list containing the following options: Backfill Selected Jobs, Browse Events, Move To Folder, Rename Folder, Set Startup Order, Column Options, Import Jobs, Export Jobs.

Backfill Selected Jobs	Opens the Backfill Job menu to delete a range of data from the Backfill Start Time up until Now and replace it with new calculated data. Data that falls earlier than the Backfill Start Time will remain untouched. The Data Start Time and Data Stop Time display the range of data that is currently stored in the Historian. If a job is asset-based, the user will see the Backfill Assets option to backfill all or some asset instances. If Some is selected, the user can filter the list using keywords separated by spaces and select the instances to be backfilled. Keywords can be prepended with an exclamation mark (!) to exclude them from the search.
Browse Events	Opens a new screen to view all historical and current events stored in the Events database for the selected job
Move To Folder	Moves the selected job(s) to another folder of choice. The drop-down menu is editable if wishing to create a new folder to move the job to.
Rename Folder	Renames the selected folder
Set Startup Order	Sets the Startup Order of the selected job(s) starting with 0 being the highest priority. Jobs that do not have a Startup Order specified are lowest priority. Startup Order can also be configured on an entire folder.
Column Options	Allows the user to choose which columns to display in the jobs table
Import Jobs	Imports jobs from a JSON file the user can browse for. The user has the option of maintaining the folder structure that may exist in the JSON file or to ignore them.
Export Jobs	Exports All or the Selected jobs to a JSON file which can then be imported into another Calculation service using the Import option.

The aforementioned options can also be found when right-clicking a job or folder.

Job Configuration Screen

Clicking the +ADD button or editing a job from the Jobs screen will open a configuration screen. Display fields will vary depending if the job is outputting Tags or Events. Fields marked with an asterisk (*) are required.

As this screen varies depending on the Output selected, fields which only apply to Tags are orange. Fields which only apply to Events are blue.

GENERAL

Job Name - a unique name identifying the calculation or event
Folder - a list of preexisting folders from the main Jobs screen in which the job can be placed. New folders can be created here by typing in the desired name and using a forward slash (/) to indicate a subfolder.
Output - defines the output mode of the job and determines which fields to be displayed for the remaining screen
- Tags - results of the configured expression(s) are written to a tag(s) stored in the Historian. As a best practice, calc tags should be written to their own DataSet.
- Event - logs an event to a SQLite database (or MSSQL database, if configured) whenever the configured conditional expression occurs
Notes - adds notes or a job's description

EVALUATION TRIGGER

Mode - the frequency at which the job is triggered. Subsequent fields will be hidden/revealed based upon the option selected: Subscription or Periodic.
- Subscription - the job is triggered whenever an input tag's value or quality changes or related events are evaluated
  - Tag Changes - determines which tags will trigger the job to evaluate
    - SubscribeAll - the job is triggered whenever any tag(s) in the expression(s) change
    - SubscribeSome - the job is triggered whenever the selected tag(s) change
    - SubscribeNone - tag changes do not trigger the job to evaluate. Instead, related events trigger the job to evaluate based on the Event Evaluations.
  - Event Evaluations - determines which events will trigger the job to evaluate. Used in conjunction with the Event_GetActiveCount, Event_GetAssetInstanceCount, Event_GetCompletedCount, and Event_GetParentVariable functions. One of these functions must be used in the EXPRESSION section at the bottom of the screen.
    - SubscribeAll - the event is triggered whenever the event's parent or immediate children are evaluated
    - SubscribeSome - the event is triggered whenever the selected events are evaluated
    - SubscribeNone - other related events do not trigger the job to evaluate. Instead, Tag Changes trigger the job to evaluate.
- Periodic - the job is triggered at fixed intervals using the Interval and Offset parameters
  - Interval - the interval at which the job is evaluated. Times can be relative (i.e. 1minute, 1m, 1hour, 1h, etc.) or literal (00:01:00).
  - Offset - an optional offset for the Interval. Times can be relative (i.e. 30minute, 30m, 12hour, 12h, etc.) or literal (12:00:00).
  Example: If wanting the job to trigger every 12 hours at 9am and 9pm, set the Interval to '12h' and the Offset to '9h'.
Delay - delays the evaluation by the configured amount of time to prevent miscalculations due to data stream latency. The delay should be set greater than or equal to the highest latency stream in the calculation. Times can be relative (i.e. 10seconds, 10s, 1day, 1d) or literal (00:00:10). This delay does not affect the timestamp associated with the output. When creating jobs that are dependent on other jobs, delays are accumulated. For example, if one job has a 1 minute delay, and a subsequent job has a 10 minute delay, the 2nd job will wait 11 minutes before evaluating its expressions.
Startup Order - a number that determines when the job will start when multiple jobs are started at the same time, such as after a service restart. The order will be honored unless a dependency causes a job with a higher startup order number to start earlier.
Backfill Start Time - the date/time the job will backfill to when it initially starts
Data Start Time - the earliest date/time in the Historian for which there is data for ALL tags in the expression(s)
Data Stop Time - the latest date/time in the Historian for which there is data for ALL tags in the expression(s)

ASSET CONTEXT (optional)

Path - allows the user to select a view/path which narrows the focus of tags to be used in the expression. The Tags menu on the right side of the screen will update as the user drills further into the path. A path using a Virtual View must be specified if wishing to create an asset-based job.
Type - an asset type that resides within the given Path, assuming it is a Virtual View. A type is only needed for asset-based jobs. As soon as a type is selected from the list, the Asset Tags menu on the right side of the screen will populate with all of the tags that pertain to the given type which the user can then use to add to the expression(s). An Asset drop-down list will also appear in the EXPRESSIONS section.

EXPRESSIONS

Expressions are built using the Expression Builder on the right side of the screen where Functions, Operators, Variables, Tags, and Asset Tags are located. This area will be grayed out until the expression field is selected. The output value determined by the expression is assigned to a variable key in the left box. This variable can then be used in subsequent expressions or assigned to a Tag Value or Property Value as indicated above.

Asset - (only visible when outputting an asset-based tag) a drop-down list containing every asset instance of the given Type that falls under the given Path from the ASSET CONTEXT section above.
EVALUATE EXPRESSIONS - evaluates the expression. If the job is configured to use a Subscription mode, the evaluation will return a timestamp of Now. If using a Periodic mode, the evaluation will return a timestamp of the most recent interval.

Clicking the drop-down arrow next to the button will open a new screen allowing the user to enter test values of their choice for each variable.
Quality Override - an expression used to override the quality of the value when the condition is true. Output values can include Good, Bad, Uncertain, NoData, NoOutput, or any valid numeric quality. Said quality values are listed in the Variables menu of the Expression Builder.
Data Type - the data type of the value. The Default option will set the data type that best fits the value. Otherwise, the user can override the data type using one of the options from the drop-down list.
Timestamp - allows the user to overwrite the output timestamp of the value using relative times. Timestamps can be normalized to the second (s), minute (m), hour (h), week (w), month (mo), or year (y). For example, a timestamp of 'd' would normalize to midnight of the current day. 'd-1d+1h' would output a timestamp of 1:00 AM yesterday.
(ellipsis) - displays options to reorder the expression box up or down if multiple expressions are used (expressions are evaluated from the top-down); show/hide the Quality Override, Data Type, and Timestamp fields; duplicate the expression; or delete the expression
+ADD EXPRESSION - creates a new expression box for complex, multi-level calculations. Expressions are evaluated from the top-down; therefore, variables assigned at a top-level can be used in subsequent expressions.

EVENTS

Name - the name given to each generated event when the event begins. Names must be unique for each event instance. The Default option will assign the name based on the job name, asset instance (if applicable), and event start time. Otherwise, the user may assign a variable key from an expression below. This expression could be a tag that is reading a batch number or order ID.
Parent - a collection of events can be hierarchical. There may be a main event that has different stages within it. This assigns the parent of the event. If assigned, the event will not be monitored unless an instance of its parent is running. If the parent event ends, the monitoring of the child event stops.
Mode - defines whether multiple instances of an event can run at the same time
- Series - once an event starts, another instance of the event cannot start until the current event ends
- Parallel - another instance of the event can start while any number of instances are already running.
Start Trigger - the variable key of an expression that starts the event whenever the expression is true.
Stop Trigger - the variable key of an expression that ends the event whenever the expression is true. If a Stop Trigger is not configured, the event will end whenever the Start Trigger is false.
Abort Trigger - the variable key of an expression that aborts an ongoing event whenever the expression is true
Min Duration - the minimum time to elapse while the Start Trigger expression is true before the event starts (i.e. 0seconds, 0s, 5minutes, 5m, etc.)
Notify Email - a semi-colon (;) separated list of email recipients who are notified whenever an event starts or ends
Email Message - opens the Email Template screen where users can customize the message that is sent when the event starts. An email message is NOT sent upon an event ending unless the Event end section is configured.

EVENT PROPERTIES

Property Name - name of the property to be written to the event. Properties can be added using the symbol or removed using the .
Property Value - the variable of the expression whose result determines the value of the property
Evaluation Time - specifies when the event property is calculated. If Continuous is selected, the property is evaluated at the start and end of the event and at any other evaluations that may take place while the event is in progress.

Expression Builder

Functions

A list of all supported functions and aggregates. Hovering over a function will display a short description. Selecting the function will display the description and the syntax for its expected inputs beneath the list. Click here for more information on the available functions.

Operators

A list of mathematical, logical, and bitwise operators. Hovering over an operator will display a short description. Selecting the operator will display the description and how it is used.

Variables

A list of all configured variables from the EXPRESSIONS section along with Quality Override outputs, the %Asset% wildcard, and EventDuration. EventDuration can be used in place of a fixed interval within an aggregate function. (See the bottom two expressions from the EVENTS screenshot above for reference.)

Asset Tags

A list of all tags that pertain to the asset Type defined in the ASSET CONTEXT section.

Settings - Endpoints Screen

IPC - endpoint used by a local Views service to read events
gRPC Admin (55340) - endpoint used specifically by the local Admin service for configuring settings and requesting status information
gRPC API (55341) - endpoint used by a remote Views service to read events

Settings - Settings Screen

SERVICE SETTINGS

Delayed Start Time (seconds) - general delay from when the service starts until calculations/events are evaluated
Destination Historians - comma delimited list of destination machine names where calculations will be sent to
AssetInstanceCount Read Interval (seconds) - frequency at which the service evaluates the total number of all asset instances for each asset type to be used in the AssetInstanceCount function
Property Read Interval (minutes) - frequency at which the service evaluates the properties of each tag to be used in the Property function
Check for New Assets Interval (minutes) - frequency at which the service checks for new assets that have come online
Max backfilling calculations - throttling mechanism used to limit the max number of calculations that are permitted to backfill simultaneously
Restart Failed Calculations Interval (minutes) - how frequently calculations in the Error state are restarted
Live Data Read Interval (milliseconds) - how frequently live data is retrieved from Views
SaF Keepalive Interval (seconds) - how frequently a keepalive request is made to SaF
SaF Reconnect Interval (seconds) - how quickly to reconnect to SaF when the connection is lost
Views Endpoint - server name of the Views service the Calculation service is connected to

IDENTITY

Identity API Token - token used to authorize tag access when the Views or SaF service is remote from the Calculation service. This token must be mapped to a user who is in the Views>BypassSecurity access control list within the Identity tile>Security>Access Control Lists screen.

EVENTS DATABASE SETTINGS

Provider - the method for storing the Events database
1. SQLite - by default, events will be stored in C:\ProgramData\Canary\Events\CanaryEvents.sqlite
2. MSSQL - events will be stored in a Microsoft SQL database determined by the remaining parameters. (See Storing Events in an External SQL Database)
  - Server - machine name of the SQL server that will store the events
  - Database Name - name of the database in which the events table will be created
  - Integrated Security - if checked, the Calculation service will connect to the database using the account on which the Calculation service is running
  - Is Domain User - determines if the configured user is a domain user
  - User/Password - credentials of the user that has read/write access to the database
  - TEST - tests the connection to the database using the provided credentials.