Section 1 – Introduction 9-7

Action Thread Pooling

The action thread pool is essentially a pool of four threads that execute actions from three different
action queues. Each thread in the pool maintains a database connection.
The three action queues are:
z Critical queue
z Normal queue
z Post-detector delay queue

Note: For detailed information about each of these queues, see Event Action Priorities in the
Historian online help files.

As a processor thread completes its previous task, a new action will be fetched from one of the
queues. If there are any actions in the critical queue, these will be processed first. Actions in the
critical queue are executed in the order in which they were added to the queue; that is, the oldest
action sitting in the queue will be processed first.
If the critical queue is empty, actions will be fetched from the post-detector delay queue. Actions in
the post-detector delay queue are ordered by time. Actions assigned the shortest post-detector
delay will be executed first.
If both the critical and post-detector delay queues are empty, actions will be fetched from the
normal queue. Like critical actions, normal actions are processed in the order in which they were
added to the queue.

Event Tables
Event tables contain definitions for events, including tags associated with events, detectors for
events, and actions for events. The event system tables can also store "snapshots" of tag values
at the time of an event, as well as details about the event itself.
A special type of event action is a summarization of tag values. A subset of the event tables
provides the supporting framework for fully automated summary generation for analog, discrete
and string tags.
The event system tables are:

ActionType SQLTemplate
AnalogSnapshot StringSnapshot
CalcType SummaryData
DetectorType SummaryHistory
DiscreteSnapshot SummaryOperation
EventHistory SummaryTagList
EventTag Tag
EventTagPendingDelete TimeDetectorDetail
Frequency TimeDetectorDetailPendingDelete
SnapshotTag

Wonderware System Platform Course - Part 2

9-8 Module 9 – Historian Event System

– Intentionally left blank –

Wonderware Training
 Section 2 – Defining Event Tags 9-9

Section 2 – Defining Event Tags

Section Objective
Explain and define Historian Event Tags and their characteristics.

This section explains and defines Historian Event Tags and their characteristics.

Event Tags
An event tag is a name for an event definition in the system. For example, if you wanted to log an
event when the temperature of a tank reached 100 degrees, you might define an event tag and
name it "TankAt100." Event tags differ from all of the other tag types in the Historian (analog,
discrete, and string). These tag types are the definitions of variables to be stored, but an event tag
is a named reference for the definition of the specific event you want to detect and what to do
when it occurs.
Event tags are created and maintained using the Historian. When you define an event tag, you
must specify:
z A name, description, and other general configuration information
z The event criteria, which describes the conditions that must exist for the event to occur
and how often the event system will check to see if the event has occurred.
z Whether or not to log the event detection when it occurs.
z Whether or not to enable/disable the event detection.
z An optional action that to be triggered when the event is detected.
The following table describes the tables that are used for storing event tag definitions:

Type of definition Table

Detection of a particular event and the possible EventTag, DetectorType, and ActionType
resulting action
Time-based detections TimeDetectorDetail
Snapshots of analog, discrete, and string tags SnapshotTag
Summary actions SummaryOperation and SummaryTagList

Wonderware System Platform Course - Part 2

9-10 Module 9 – Historian Event System

Edge Detection
When detecting events, it is useful to pinpoint rows in a result set where criteria changed from true
to false, or vice-versa.
For example, you may want to know when the level of a tank goes above 5 feet. As the tank level
approaches 5 feet, the criteria does not return true. Only when the level crosses the line from not
satisfying the criteria to satisfying it, does the event actually occur. This imaginary "line" where the
change occurs is called the edge.
Over a period of time, there may be many instances where the criteria crosses the "edge" from
being satisfied to not satisfied, and vice-versa. The values on either side of this "edge" can be
detected if you configure your event tag to include this information. There are four possible options
for edge detection: none, leading, trailing, or both. You will get differing results based on which
option you use:

Edge Detection Option Results

None Returns all rows that successfully meet the criteria; no edge detection is
implemented at the specified resolution.
Leading Returns only rows that are the first to successfully meet the criteria (return true)
after a row did not successfully meet the criteria (returned false).
Trailing Returns only rows that are the first to fail the criteria (return false) after a row
successfully met the criteria (returned true).
Both All rows satisfying both the leading and trailing conditions are returned.

Edge detection only applies to analog and discrete value detectors. Also, edge detection is
handled slightly differently based on whether you are using analog tags or discrete tags.

Historical Logging of Events

The exact time at which a particular event actually occurred and the time at which it was detected
by the event system can be logged into a Historian table, called EventHistory. Each row in the
EventHistory table contains the name of a defined event tag, the date/time stamp for when all of
the detection criteria for that event tag were satisfied, the date/time stamp of when the event
detector detected the event, and an additional field that provides event detection information.

Note: You cannot disable event logging if analog and/or discrete snapshot actions are configured.

In addition to the conditions that must be met for an event, you must also have the event detection
process enabled for the event tag.

Tip: The EventHistory table can be used to determine if too many event tags have the same time
interval. If the latency between when the event actually occurs (stored in the DateTime column)
and when it was detected (stored in the DetectDateTime column) is constantly growing and/or
multiple event occurrences are being detected during the same detector time interval, you need to
move some of the event detectors to a different time interval.

Wonderware Training
 Section 2 – Defining Event Tags 9-11

System Thread Allocation for Events

A system thread is an object that independently performs a particular function within a process. In
the event system, threads are allocated for event detectors and actions.

Detector Thread Allocation

Two threads are allocated to handle event detections: one for all SQL-based detectors and one for
schedule detectors. Each of these threads uses a logon to the SQL Server.
Schedule detectors are processed in real-time and are executed at the scheduled time. Since
SQL-based detectors operate on historical data, they are ordered and then processed. The
detectors are first divided into groups, based on the time interval specified for the corresponding
event tags. The time interval is the rate at which the configured detector component will check to
see if an event occurred (this time interval is stored in the ScanRate column of the EventTag
table). The detectors are then sequentially ordered in the time interval group.

Note: Each detector thread maintains a database connection.

Action Thread Allocation

All actions are assigned to a thread pool. Within this pool are three different queues:
z A "critical" queue, which contains any actions for event tags that have been assigned a
critical priority. You should categorize any events that are highly important as "critical"
events. All events that are given a critical priority will be processed first if a system
overload condition occurs. Use caution when assigning an event as critical. If all events
are assigned as critical, there is no protection in the system in the case of an overload.
Critical means that the system will always attempt to perform the action before any normal
actions.
z A "normal" queue, which contains any actions for event tags that have been assigned a
normal priority. All non-critical events are labeled with a "normal" priority and will be
processed after the critical events if a system overload condition occurs.
z A “delayed action” queue, which contains any actions for event tags that have been
assigned a post-detector delay. The post detector delay is the minimum amount of time
that must elapse after an event was detected before the associated action can be
executed.

Note: Each thread in the action thread pool maintains a database connection.

Wonderware System Platform Course - Part 2

9-12 Module 9 – Historian Event System

Latency
Latency is the amount of time between when an event actually occurred and when it is detected by
the event system. Latency is important when you want to quickly trigger an action after an event
occurs.
For example, if you created an event that detects when an instrument is starting to send non-
normal values, you would want an action to notify you to check the instrument as soon as possible.
You would create an event tag for this with a short time interval (scan rate) so that the event
system would frequently check to see if this event has occurred.
Other events (for example, when an operator ended a shift) are not as critical and latency is not as
important.
Use caution in assigning time intervals to event tags. Too many event tags assigned to the same
time interval may result in detector "overruns." While this should not have a negative impact on
actual detection of events, it may add to increased latency. Also, assigning short time intervals will
result in higher CPU loading and may lead to degraded performance.

Event Detectors
Each event tag has an associated event detector. An event detector is a mechanism for
determining when the set of event criteria for an event tag has been satisfied. An event detector
must be of a specified type listed in the DetectorType table. When you configure an event
detector, you must first configure its type and then configure the parameters associated with that
detector type.
The Historian is shipped with the following pre-configured event detectors.

Detector Description
External Event detection is triggered via the ActiveEvent ActiveX control. For example, an
InTouch script can invoke necessary ActiveEvent methods to trigger a Historian
event. The external detector is not configurable.
Generic SQL Detects an event based on criteria that are outlined in a SQL statement. You can
use pre-configured SQL templates that are stored in the database as the basis
for your script, or you can create your own script from scratch.
Analog Specific Value Detects an event based on criteria applied to the value of a particular analog tag.
The value of an analog tag is compared (using operators) to a constant value.
Discrete Specific Value Detects an event based on criteria applied to the state of a particular discrete
tag. The state of a discrete tag is compared to a constant target state.
Schedule Detects an event based on the system clock being equal to or greater than a
specific time. For example, you could log an event every week on Monday at
2:00 p.m.

For SQL-based detectors, the time that an event is detected may occur significantly after the
actual time that the event occurred, depending on event configuration parameters. For example,
you configure a detector to detect a particular event based on a time interval of 10,000 ms (10
sec). This means that every 10 seconds, the event detector will check to see if the event occurred.
If the event occurs 2,000 ms (2 sec) after the last check, the event detector will not detect that the
event occurred until the full 10 seconds has elapsed.
Schedule detectors, however, are real-time detectors; they run once every 1 second.

Wonderware Training
 Section 2 – Defining Event Tags 9-13

Event Actions
An event may or may not be associated with an event action. An event action is the action that is
configured to take place when the event detector determines that the event occurred. Event
actions are not required; there are times when you may want to store only when events happened.
The Historian is shipped with the following pre-configured event actions:

Action Description
None Will not perform any action as the result of an event detection.
Generic SQL Triggers an action that is outlined in a SQL statement. You can use pre-
configured SQL templates that are stored in the database as the basis for your
script, or you can create your own script entirely from scratch.
Snapshot Records the values of selected analog tags or the states of selected discrete
tags or the string values of selected string tags at the time that the event
occurred. Quality is also recorded.
E-mail Sends a pre-configured Microsoft Exchange e-mail message.
Deadband Changes the time and/or value storage deadband for one or more analog tags
that are using delta storage (storage by exception).
Summary Performs one or more aggregations for one or more analog tags.

Event Components and Programs

The event system consists of the following components and programs:
z The Event System Data Model, which is the schema that supports the data configuration
and history logging requirements of the event system.
z The Event System Service (ESS), which is a Windows NT Service that coordinates the
event detection and action functions. The ESS is automatically started and stopped when
you start and stop the Historian system using Historian Control program; however, the
ESS can be started and stopped independently from the rest of the system using the
Services program in Control Panel.
z A set of system event tags for pertinent system internal variables; similar to pre-defined
system tags.
z The System Management Console, a system-wide configuration application that provides
an intuitive user interface in which you can create or delete event tags, configure event
detectors and event actions, and manage the event system.
z Event system COM components for enumerators, detectors and actions.

Wonderware System Platform Course - Part 2

9-14 Module 9 – Historian Event System

Event System Variables

The Event System uses a set of internal variables called tokens to facilitate event detections and
actions. During the Event Detection and Action, the variables are replaced with the associated
values by the event components just prior to executing the query. The query received by the
Historian does not contain the variables.
The variables are as follows:

Variable Description
@EventTime Time of the detected event of the current detector.
@EventTagName Tagname associated with the detected event.
@StartTime Start date/time for the detector query.
@EndTime End date/time for the detector query.

Detector Strings use only the @StartTime and @EndTime tokens.

Action Strings use all 4 tokens.
The following figure shows Detector and Action tokens used in several Event Tags (created in the
subsequent lab):

A detection query executed by a detector component is similar to the following:

SELECT DateTime
FROM History
WHERE Tagname = 'BoilerPressure' AND Value > 75
AND DateTime > '@StartTime'
AND DateTime < '@EndTime'
@StartTime and @EndTime are simply placeholders for the detector component to coordinate
event detection over a moving time range.
The following action query illustrates how the event variables could be used:
SELECT * INTO TEMPTABLE
FROM History
WHERE DateTime = '@EventTime'
AND TagName IN (
SELECT TagName
FROM SnapshotTag
WHERE EventTagName = '@EventTagName'
AND TagType = 1)

Note: These tokens only function in the internal context of the Event System and do not function
in queries from external client tools such as SQL Server Query Analyzer.

Wonderware Training
 Lab 18 – Create Events 9-15

Lab 18 – Create Events

Introduction
This Lab is designed to teach Event tag creation within the Historian, including how SQL queries
are used as event actions and event validations.

Objective
Upon completion of this lab you will be able to:
z Utilize the Historian Event System capabilities
z Create the HiLevelEvent Tag
z Create the TransferEvent Tag
z Create the MixerSummary Tag
z Create the ExternalEvent Event Tag

Wonderware System Platform Course - Part 2

9-16 Module 9 – Historian Event System

Create the HiLevelEvent Tag

1. Maximize the ArchestrA System Management Console.
2. Expand the Configuration Editor icon under your Historian server.
3. Expand the System Configuration folder.
4. Expand the Tag Configuration folder.
5. Right-click the Event Tags icon.
6. Select New Tag…. from the sub-menu
The New Event Tag Wizard appears.
7. Enter HiLevelEvent in the Unique Tag Name field.
8. Click Next.

Wonderware Training