Event configuration
Once the event types with their accompanying event properties are set up, event types can be linked to assets to start configuring the event detection. First select an asset from the asset tree and click Configure event:
Next, choose the Detection mode. The form labels each mode by its input, followed by the value the API stores in parentheses:
- From timeseries (historian)
- From a schedule (schedule)
- From users (manual)
- From an external database (external_database)
- From child events (child_events), only with named events on
The tooltip next to the field describes the selected mode. The different detection modes are elaborated below .
Optionally, a Parent event configuration can be given. It is recommended that the parent event configuration is of the same event type as the parent event type configured on the selected event type. With a parent selected, the parent linkage settings decide which parent event each child event links to.
The asset and event type of an event configuration cannot be changed after it is created. From version 8.3, the API also rejects a request that changes them.
Once created, the event detection of this event configuration can be started or paused (except event configurations with the From users detection mode).
Newly created event configurations are paused by default. They need to be started by clicking the Start button.
Once the event detection has started for this event configuration, the detected events of this event configuration and their event properties can be found in the Events tab, or in the Events overview. In a similar fashion the logs pertaining to this event configuration can be found in the Logs tab.
Parent linkage
Available from version 8.3 and later.
When a Parent is selected, the following settings control how a child event finds its parent event. Event configuration prototypes carry them to their instances.
Parent window
Description: Which parent event a child event links to.
- Child starts inside the parent: the child links to the latest-starting parent event whose window contains the child's start time. This is the rule of earlier versions.
- Child overlaps the parent: the child links to a parent event whose window overlaps the child's window, so a child that starts before its parent still links. The window of an open parent event extends to now. When several parent events overlap the child, the latest-starting one wins.
Default: Child starts inside the parent
For example, with a parent event from 08:00 to 12:00 and a child event from 07:30 to 08:30, the child links to the parent only with Child overlaps the parent. With parent events from 08:00 to 10:00 and from 10:00 to 12:00 and a child event from 09:30 to 10:30, Child overlaps the parent links the child to the parent that starts at 10:00.
With Child overlaps the parent, a child whose parent event stops before the child stops keeps waiting for a later parent event. It is processed once its parent stops at or after the child's stop, once a parent event starts at or after the child's stop, or once Wait for parent has passed. In the last two cases it keeps the earlier parent. A waiting child that links to another parent event has its properties calculated again.
Wait for parent
Description: How long to wait for a parent event after a child event stops, as a duration such as 1d or 2h. After that, the child is processed without a parent. A child also gives up earlier once a parent event exists that can no longer match it: with Child starts inside the parent, a parent event that starts after the child's start; with Child overlaps the parent, a parent event that starts at or after the child's stop. When empty, the child waits until such a later parent event exists, with no time limit. With Parent match set to By name, the wait works differently, see Parent match.
Default: The form pre-fills 1d for a new configuration. Left empty, for example when created through the API, children wait with no time limit. Configurations created before version 8.3 keep an empty value, so they behave as before.
A child that was processed without a parent does not link when its parent arrives later. Re-evaluate the child event configuration to link it.
Parent match
This setting is part of named events, which are experimental and off by default. To turn them on, add named-events to the FEATURE_TOGGLES_ENABLE environment variable (comma-separated) and restart Factry Historian.
Description: How a child event picks its parent event.
- By time: the child links by the Parent window rule.
- By name: the child links only to a parent event with the same name, for example the same batch ID. Among parent events with that name, Parent window picks one. A child never links to a parent with another name or without a name.
Selecting By name sets Parent window to Child overlaps the parent, since batches with different names can overlap. You can change it back. The form warns when the parent configuration does not name its events, because child events will then not link to it. A parent names its events when it uses the From users or From child events detection mode, or Event name source Trigger.
With By name, a named child without a matching parent stays pending after it stops. With Wait for parent empty, it waits until a parent event with its name exists, with no time limit. With Wait for parent set, it is processed without a parent once that time has passed. A later parent event with another name does not end the wait. An unnamed child is processed without a parent once it stops.
Default: By time
While named events are off, the form hides this setting, and a configuration that stores By name links by time.
Detection mode
A trigger measurement can be used by opting for From timeseries as the detection mode or a recurring schedule can be used by opting for From a schedule as the detection mode.
Detection mode: From timeseries (historian)
The historian detection mode works by observing the values of a trigger measurement for a change. Whenever the value of the trigger measurement changes, that timestamp is used to start a new event, along with closing the previously open event on the same timestamp. Take into account, if the new value of the measurement is considered a zero value (depending on the datatype), the previous event will be stopped but a new event will not be created.
Zero values
The values considered as zero values with respect to event detection for each datatype are listed below.
- boolean: false
- number: 0
- string: "" (an empty string)
Refresh interval
To prevent the creation of an event with an incorrect start time the event detection will only start creating new events after the first change in value is detected. The refresh interval at which the detection is evaluated can be adjusted by using the refresh interval.
Grace period
To ignore value changes and consequently triggering a new event, a grace period can be configured. If a value changes and subsequently the value changes back to the former value within the grace period, the current event will not be closed and no new event will be started. Thus, the grace period is the time period for which value changes are ignored or can be seen as the minimum time between value changes.
Example historian event detection
An example of the historian detection mode by observing the values of the trigger measurement “BATCH_LABEL”:
Value | Time | Event detection |
|---|---|---|
5AB | 2006-05-04 12:59 | start of event-detection |
5AB | 2006-05-04 13:00 | no action |
5AB | 2006-05-04 13:01 | no action |
| 2006-05-04 13:02 | close previous event |
16BA | 2006-05-04 13:03 | open new event |
16BA | 2006-05-04 13:04 | no action |
17B0 | 2006-05-04 13:05 | close event, open new event |
| 2006-05-04 13:06 | close event |
17BA | 2006-05-04 13:07 | open new event |
This results in the creation of 3 new events:
Event | Start time | Stop time |
|---|---|---|
1 | 2006-05-04 13:03 | 2006-05-04 13:05 |
2 | 2006-05-04 13:05 | 2006-05-04 13:06 |
3 | 2006-05-04 13:07 | ongoing |
Event name source
Available from version 8.3 and later.
This setting is part of named events, which are experimental and off by default. To turn them on, add named-events to the FEATURE_TOGGLES_ENABLE environment variable (comma-separated) and restart Factry Historian.
Sets where the detected events get their name.
- None: events are unnamed. This is the default.
- Trigger: each event is named after the trigger value that started it, for example a batch ID. Spaces around the value are removed. An empty, blank or null value, 0 and false stop the current event and start none.
After changing this setting while an event is open, re-evaluate from before that event. While named events are off, the form hides this setting, and a stored Trigger is kept but events are stored unnamed.
Detection mode: From a schedule (schedule)
The schedule detection mode allows for generating events based on a recurring schedule. By means of an RRULE, this event detection can be configured. An RRULE is a recurrence rule which defines a pattern to generate a set of timestamps to setup new events. Their syntax is defined by the rfc5545 standard.
To set up a schedule event detection, add a recurrence rule for generating a set of start timestamps and optionally add another recurrence rule to close the corresponding events. Multiple recurrence rules can be combined for either the start timestamps and/or the stop timestamps. One recurrence rule for the start timestamps is required.
Example schedule event detection
An example of the schedule detection mode to generate a set of start and stop timestamps for new events:
Start rules
DTSTART;TZID=Europe/Brussels:20200101T080000
RRULE:FREQ=DAILY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR
DTSTART;TZID=Europe/Brussels:20200101T140000
RRULE:FREQ=DAILY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR
Stop rules
DTSTART;TZID=Europe/Brussels:20200101T220000
RRULE:FREQ=DAILY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR
This results in the creation of 2 new events per weekday:
Event | Start time | Stop time |
|---|---|---|
1 | xxxx-xx-xx 08:00 | xxxx-xx-xx 14:00 |
2 | xxxx-xx-xx 14:00 | xxxx-xx-xx 22:00 |
For further information on RRULE including a useful GUI to build a recurrence rule, visit RRULE ui .
Detection mode: From users (manual)
The manual event detection mode allows for events to be manually started/stopped inside manual entry forms. No further configuration is needed for this detection mode.
Detection mode: From an external database (external_database)
The external database detection mode works by querying a database for start and stop times to generate events. External databases can be configured by going to Configuration > External Databases.
The query must return a table with exactly one or two columns, and every column value must be a timestamp. A third column, or a column of any other type, makes the whole detection run fail. The first column should contain the start times of the events, the second column (if it is present) should contain the stop times of the events. If only start times are available in the dataset, the stop time for an event will be based on the start time of the following event. This detection mode has a required refresh interval, given as a duration literal of at least 1s, which determines how often the query runs.
You can use query parameters to narrow down your data selection, which includes the asset metadata. The supported parameter values are CurrentTime, LastEvaluationTime, AssetName and asset metadata keys. For example, given the following database table event_times:
Type | Start time | Stop time |
|---|---|---|
Pump1 | 2024-12-27 08:00 | 2024-12-27 14:00 |
Pump2 | 2024-12-27 09:00 | 2024-12-27 15:00 |
We can create this query to generate events for a specific asset type:
SELECT start_time, stop_time FROM event_times
WHERE type='Pump1' AND stop_time < $1
We can create more dynamic queries, based on asset metadata:
SELECT start_time, stop_time FROM event_times
WHERE type=$1 AND stop_time < $2
If no stop times are available we can omit that column:
SELECT start_time FROM event_times WHERE start_time < $1Detection mode: From child events (child_events)
Available from version 8.3 and later.
This detection mode is part of named events, which are experimental and off by default. To turn them on, add named-events to the FEATURE_TOGGLES_ENABLE environment variable (comma-separated) and restart Factry Historian.
This detection mode builds one parent event per name from the named events of its child configurations, for example a batch from its unit batches. Set it on the parent event configuration, for example on the process cell, and select that configuration as the Parent of the unit event configurations. Name the unit events, for example with Event name source Trigger.
- A parent event opens when the first child event of a name starts. It starts at the earliest start and stops at the latest stop of its child events.
- A child event that starts while another child of its name runs, or no later than Gap tolerance after the latest one stopped, belongs to the same parent event. A child that starts later gets a new parent event with the same name.
- The parent event stays open while any of its child events runs, and until Gap tolerance has passed after the last one stopped. It then closes with its stop time set to the latest child stop.
- While a parent event is open, a child that starts before it moves its start earlier. A closed parent event is final: child events stored, changed or deleted later do not change it. Re-evaluate the configuration with Delete previously generated events to include them.
- Every child configuration that is not deleted counts, also a paused one or one in error. Unnamed child events are ignored.
- Events of this configuration entered by hand are left alone, and child events link to them by name. No parent event is opened while another open event with the same name exists on the same asset and event type.
- Child events of this configuration always link by name, with Child overlaps the parent. The form of a child configuration shows these values and does not let you change them.
- Deleting the configuration closes its open parent events.
For example, with a Gap tolerance of 1h:
Child events | Parent events |
|---|---|
B1 on R1 from 08:00 to 10:00, B1 on R2 from 09:00 to 11:00 | B1 from 08:00 to 11:00 |
B1 on R1 from 08:00 to 10:00, B1 on R2 from 10:05 to 15:00 | B1 from 08:00 to 15:00 |
B1 on R1 from 08:00 to 10:00, B2 on R2 from 09:00 to 11:00 | B1 from 08:00 to 10:00 and B2 from 09:00 to 11:00, overlapping |
FOAM-40 from 08:00 to 10:00, FOAM-40 from 11:30 to 12:00 | Two events named FOAM-40, from 08:00 to 10:00 and from 11:30 to 12:00 |
Refresh interval
Description: How often the parent events are updated from the child events. At least 10s. Default: 10s
Gap tolerance
Description: How long after the last child event of a name stopped a new one with that name still joins the same parent event. The parent event closes this long after its last child event stops. Keep it below the time between runs that reuse a batch ID. Default: 1h
While named events are off, the form does not offer this mode, and shows an existing configuration with this mode with a notice that it needs named events. The API rejects creating or updating such a configuration, and instantiating a prototype that carries one, with a 403. An existing configuration stores no events, but it can still be changed to another detection mode or deleted.
Named events
Available from version 8.3 and later.
Named events are experimental and off by default. To turn them on, add named-events to the FEATURE_TOGGLES_ENABLE environment variable (comma-separated) and restart Factry Historian. The setting applies to every organization on the server.
With named events on, an event can have a name, typically a batch ID. An unnamed event has no name at all, never an empty one.
- Events get a name from their trigger value (Event name source), from the From child events detection mode, or from a user in a manual entry form or through the API.
- Events of one asset and event type with different names may overlap. Events with the same name, or two unnamed events, still may not overlap.
- A name has at most one open event per asset and event type. A detected start for a name whose event is closed starts a new event with that name, and does not extend the closed one.
- A detected start still ends the open detected events of its own configuration, since a trigger has one value at a time. It does not close or shorten a manual event with another name.
- Child events can link to their parent by name, see Parent match.
- The events overview shows the name and can filter on it. Merging and splitting keep the name.
While named events are off, stored names and naming settings are kept but ignored: detection and linkage follow the rules for unnamed events. Turning named events off deletes no names.
Re-evaluation of events
By selecting an asset in the asset tree and clicking the re-evaluate button in the top right corner, all events underneath that asset can be re-evaluated from the chosen start time onward. In this way, events can be detected on already existing historian time series data.
Note that this will not overwrite events which have been edited by hand (flagged manual), nor will interfering existing events be deleted unless the option Delete previously generated events is selected in the re-evaluation popup.
To re-evaluate only one event, see re-evaluate a single event.
Pausing and resuming
Event configurations can be paused to stop the detection of any future events. This can be done by clicking the "Pause" button in the top right corner of the asset details page. This button will then change to a "Start" button, which can be used to resume the event configuration and start detecting new events.