Add Events
Events are entities that appear when something happens in the system - namely, when system or system component state changes. These changes can be set up to trigger certain actions so that system administrators and/or users can react to them in a timely fashion.
In addition to the default set of events, certain types of events can be added manually.
To access event management in Macula Console, select the Events & Actions section and then select Events from the menu on the left.
To create an event, click + New event button on the upper panel; event configuration dialog box will open. It is also possible to add events as you go, from the Event & Action Configurator. Fill in the settings, then click OK to save and close the dialog box. The newly created event will appear in the item list under Events and will be available for setup in the Event & Action Configurator.
Once you have created an event, it is impossible to change its type, only its source and properties.
Below, you will find explanations about every available event type.
Prior to software version 1.17.0, events and actions were simply listed alphabetically. Starting with v.1.17.0, events and action are additionally grouped for your convenience. Start typing a keyword to quickly find a specific event.
Channel Related Events
Events in this category have channels as sources.
Before creating such events - from camera DI or VCA source - make sure to:
enable alert generation in channel settings via Macula Console for device digital inputs (DI)
enable and set up rules via camera Web interface for edge VCA, or set up Open VCA rules (Open VCA must be activated)
Without these settings, the target channel will not have corresponding DI or VCA items available in the event settings (the item list will be empty).
Auxiliary Device Event
This type of event is similar to VCA Event and designates some event that happens on the device side, with the difference that the auxiliary device event comes from a non-video device. Auxiliary device events may come from alarm control panels, various sensors, audio detectors etc. These events are received directly via device integration (not via OPC/MQTT/...) and are not directly reported as DI/DO events either.
If your device falls into this category but the auxiliary event list is empty, try the VCA event type.
Available settings:
Title: user-defined event name that will appear in the E&A Configurator
Source: source device (e.g. Satel alarm control panel)
Device event: event type on the device side
Digital Input
This event is triggered when a device's DI state is changed. Before creating the event, make sure you have enabled DI event generation in the device channel's properties.
The following settings are available for Digital Input event:
Title: a user-defined event name
Source: choose the device from which the DI event originates; event generation must be enabled in the channel settings
Digital Input: select one of the DIs of the target device to serve as event trigger; the number of inputs depends on the total available and configured inputs
Digital Input Mode: the binary input state to trigger alert; must conform with the DI state set up in the channel settings
VCA Event
For camera-side VCA and software-side Open VCA events. Note that this event only covers triggered VCA rules, and not counters. In order to set up reactions for VCA counter changes, use the Channel variable value event (for Open VCA) or Counter value event (for camera-side counters).
The available settings are:
Title: user-defined event name
Source: choose a channel from which the video analytics event originates; analytics rules must be enabled via the camera Web interface (some cameras have basic VCA events enabled by default, e.g. volume detection) or pre-configured using the Macula Console for the software-side Open VCA module (see corresponding documentation for configuration details)
VCA Rule: video analytics rule to trigger event alert; may come from the camera side, Open VCA engine, or built-in VA engine; available rules depend on device model, capabilities and VCA configuration
If you do not see a recently created VCA event in the drop-down list, try clicking the Reload button: this will refresh the source event list. For guidelines on how to enable and configure Open VCA, please see the related document.
External Events
These events come from all kinds of external systems.
Event Triggered by MQTT Notification
This event is triggered by incoming MQTT messages from a third-party broker. The message may be an exact text match, or you can evaluate it using a regular expression (regex) and catch a keyword or a part of the message.
Title: event name that will appear in the E&A Configurator, corresponds to the macro {EVENT_TITLE}
Source: MQTT client that will subscribe to the current topic and act as event source. Leave empty if you want the event to be visible for all existing MQTT clients
Topic: MQTT topic to subscribe to
Text: incoming message that will trigger the E&A event. If empty, any message will trigger the event. The field cannot be empty if marked as regular expression!
Regular expression: enable this option to enter a regular expression in the Text filed instead of plain text
QoS: required level of quality of service
Fields Source and Text may be left empty. Empty source means that the event will be created for every existing MQTT client. Empty message text means that the event will be triggered by any message having the defined topic; however, you cannot leave this field empty if you wish to use regex. If the Regular expression option is enabled, the Text field must contain an evaluating expression to analyze the message text.
External Service
External Service type events are messages from modules that are operating via Macula HTTP API and are listed in Macula Console as external services. By default, license plate recognition and face recognition services are integrated.
The following settings should be defined:
Title: user-defined event name
Source: choose a Channel, Channel group, Service or Service group from Macula Console. When the rule actually fires, the real source is always the channel defined inside the external service, so all macros resolve to that channel—not to the group or service you picked.
Service group: the group the external service belongs to in Macula Console settings
Target event: service-specific result type, e.g., recognition result
Known: recognition result has a match within the external service database (black/white list in LPR, subjects' database in FR), matching any tag
Unknown: recognition result has no matches within the external service database
Tags: recognition result was found in the external service database and it has a specific tag assigned to it
External Service event from the License Plate Recognition module
Why these matters
Picking a group or service lets one rule cover every channel inside that logical container, while still logging the exact camera that triggered it. Existing pop-ups, e-mails, and audit trails continue to show the precise channel, so nothing breaks.
Quick example
Suppose you set Source → Service group = “FR Cluster East”.
If AnyCamera-07 inside that cluster reports a “Known” face, the macros resolve like this:
%Source.Channel% = AnyCamera-07
%Source.Service% = FR-East-Node-01
%Source.Group% = FR Cluster East
Your notifications will therefore mention AnyCamera-07, even though the rule itself was attached to the service group.
External
External events are HTTP requests from third-party software: integrations, scripts, Web browsers etc. These are a basic example of Macula HTTP API: an URL is used to trigger the event.
For the external request to trigger an event, create the event on your desired Macula server:
Title: user-defined event name
Source: Macula server that will accept the HTTP request
Event ID: alphanumeric event identifier, only Latin letters [a-zA-Z] and digits [0-9] allowed
The request link is built as follows:
http://<server_address>:<http_port>/externalEvent/activate?id=<event_id>, where
<server_address> is the target server's IP address or hostname (in Macula Enterprise systems, use the exact Macula Recording Server address, not Macula Enterprise server address)
<http_port> is the server's HTTP port (8080 by default)
<event_id> is an alphanumeric identifier of the event, which is defined at the event creation step
Example: http://192.168.1.99:8080/externalEvent/activate?id=666
SMS Message Received
SMS events are events triggered by short messages, which are received by SMS (GSM) modems. You need to connect the hardware (modem) to the Macula server, insert a SIM card, and add the modem into Macula Console in order to receive this type of events.
Available settings:
Title: user-defined event name
Source: existing modem hardware to accept the message
Phone: sender's full phone number; if empty, the event will be triggered by SMS from any number
Text: SMS text to trigger the event, case-sensitive; leave empty for any text to trigger the event
Regular expression: enable if you wish to evaluate the incoming text with regex, e.g., use placeholders
The phone number must be in the international format (with leading + or 00 and a country code) for ALL numbers, even local ones. The event will not work properly without the country code.
In this event type, you can use certain keywords in your messages, or set up regular expression rules to catch patterns.
Variables and Counters
Events in this category are triggered by certain value changes. These values can be text variables, software or VCA counters, mappings from data sources (POS or other serial text), channel metadata etc. Each event is dedicated to a specific kind of variable or counter.
Counter value: for camera-side VCA counters and also software counters
Data source: text match from Data sources
Open VCA counter value: server-side VCA (Open VCA) counters
Variable value: pre-defined variable value analysis
Counter Value
Solely for camera-side counters and software counters (server-side, NOT VCA).
Software counters can be created in Macula Console to count any events in the system. Camera-side counters are only available for certain integrations (e.g., Dahua with smart tools).
This event is similar to the previous one, with the difference that you do not have to set the data type, but rather simply select a pre-created counter. Counters from the cameras must be also explicitly added in Macula Console under E&A > Counters > New VCA Counter.
Title: user-defined event name
Source: choose one of the pre-created software or camera-side counters
Condition: define what the counter value will be compared to
Conditional operator: choose the comparison type - greater, less, equal, etc.
Value: an integer value for the counter to be compared to
For actions further linked to this event, you can pass the counter value by using the text macro (field) {ADDITION_INFORMATION} (you can insert it in any textual action by right-clicking the text area or by clicking the Insert field button). The format will be [counter_name]=[counter_value]. For example, for a counter named Total hitting a value of five, the macro will show Total=5.
Data Source
The server will monitor incoming text from Data sources, triggering an event in case the specified string is received. This can be used to react to certain keywords from POS terminals and any other serial data sources. The string for comparison is defined in free text form (not regex). The server will be looking for an exact match, i.e., the field is case-sensitive and all extra symbols (commas, spaces) are accounted for.
Available settings:
Title: user-defined event name
Source: data source to be used as event source; text from data provider will be analyzed for matches
Text: case-sensitive keyword or key phrase; when an exact match is found in the text, the event will be triggered
For the event to operate, it is not necessary for the target data source to be bound to any channel. Associating data sources with channels only affects video overlay in the Macula Monitor application; text detection will work on the server side, and therefore the data source may be independent.
Open VCA Counter Value
This event is dedicated to Open VCA counters (those set up on the server side for a specific channel). Each counter value update triggers a comparison of the integer counter value to the pre-defined value. The comparison operation is carried out using two integer data types and returns true (event is triggered) if the condition is true. The available conditions are: equal/not equal, greater/less, greater/less or equal.
To react to Open VCA rules, use the VCA Event under channel-related events.
Title: user-defined event name
Source: a channel that has Open VCA enabled and at least one counter set up
Condition: define what the counter value will be compared to
Variable: Open VCA counter name
Type: must be integer (other types are listed to ensure event compatibility with older software versions)
Conditional operator: choose type of comparison - greater, less, equal, etc.
Value: an integer value for the counter to be compared to
For actions further linked to this event, you can pass the counter value by using the text macro (field) {ADDITION_INFORMATION} (you can insert it in any textual action by right-clicking the text area or by clicking the Insert field button). The format will be [counter_name]=[counter_value]. For example, for a counter named Total hitting a value of five, the macro will show Total=5.
Variable Value
If you have some variables set up in the E&A section, you can use E&A manager to trigger events when these variables meet some specific condition. Mostly, these variables are mappings from Data sources: thus, this event supplements the previous Data Source event by matching any data type (not just text).
The second purpose of this event is analysis of metadata received from cameras (or other devices). A typical example of this is variables from thermal cameras containing exact temperature measurement. To use this feature, first create channel variables under Variables in the E&A section. Then, use them as
This event has the following settings:
Title: user-defined event name
Source: a channel to be analyzed for the variable (which is set in the corresponding data source profile or has VCA configured); if none selected, the event will be visible for all channels
Variable: variable name, must match the mapping name in the data sources profile or the VCA counter name
Type: variable type; may be integer, double or string for a data source mapping, and integer for VCA counters
Conditional operator: depends on the variable type
Value: value that will be compared with the variable value
For VCA counters, there are a few special requirements:
type must be integer
event source must be selected (the channel that has VCA configured, either camera-side or software side)
Other Events
Events having no special category (or, at this point, unique), are grouped under Other events.
OPC Client Event
Data received from OPC servers can be analyzed - compared to specified values using conditional operators - so that an event is triggered when the target OPC node value meets the defined condition.
For this type of event to work, there should be at least one OPC server configuration available with at least one data node.
Settings:
Title: user-defined event name
Source: OPC client configuration (connection to an OPC server)
Condition: defines a requirement for the OPC data item that will trigger the event
Variable: OPC data node, must be of compatible type and have a read permission
Value type: one of the standard data types, auto detected
Conditional operator: list of possible conditional operators, depends on the data type
Value: value to compare the variable to, must match the variable value type
For some conditional operators, the Value field may be different, e.g., represent a range, a regular expression, or a bit mask. This depends on the selected data type and conditional operators available for it.
Recording Server Connected/Disconnected*
In the Macula Enterprise system, when a recording server goes down, this event will be triggered on the central management server. (Built-in events only include central server disconnection and failover activation events.) You can add both connection and disconnection events, or either one, for every recording server in the system.
Settings:
Title: user-defined event name
Source: central management server (unchangeable)
Recording server: target secondary server to trigger the event, or Any to enable this event for all recording servers
Connection event: connected/disconnected (one at a time)
So, if you need to get a notification about a particular server going offline or online, choose that server in the event properties. To cover all recording servers with a single event, choose Any in the Recording server field: if your associated action is textual (email, alert, etc.), use the {ADDITION_INFORMATION} macro to display the name of the recording server in question.
From each recording server's side, there also exist two default (built-in) events: Central server connected and Central server disconnected. You do not need to add them manually, they will appear for each existing recording server.
*This feature is only available in Macula Enterprise edition.
Scheduled Event
The server can create automatic events on a daily or weekly basis, or at certain intervals. Such an event does not have any underlying source to originate from, it is simply generated by the system in the specified moment(s) of time. Note that the time defined here is server time.
There are two types of automatic events: periodical and scheduled. Periodical events arise at the specified intervals, e.g., every hour or every ten minutes. Scheduled events follow the specified timetable, e.g., are triggered at 8AM every day.
For a scheduled event, you need to define:
Title: user-defined event name
Source: target server to generate the event on
Periodical: choose this type if you need the events to be generated every N seconds
Interval: time interval in seconds between two automatically generated events, minimum interval is fifteen seconds
Scheduled: choose this mode if you wish to build a timetable to serve as a basis for the event generation
Event schedule: weekly timetable for the event generation
To add a schedule, simply click the Add button below and append as many items as you like. You can add multiple moments per day as well.
Remember that you can enter the time either manually from the keyboard or by clicking the timestamp elements and then using your mouse wheel, while still hovering your mouse cursor over the element that is being adjusted. To edit any of the items, select one and click Edit, or simply double-click an item; to remove, select one or many (use CTRL+click or Shift+click to select multiple items, or also CTRL+A to select all) and then click Remove.
Tag Match
This event occurs when the Macula server receives a recognized car number plate or a face that matches one or more internal tags.
Settings:
Title: user-defined event name
Source: the video channel that serves as the event source (the one being analyzed)
Tag match mode:
No tags: event will be triggered by items that are not tagged
Any: the item matches one or more (at least one) of the tags selected below
All: the recognition results must match all tags specified below
Not any: the event is triggered if the recognition results do not match any of the specified tags
Flags: choose if you want to use LPR, FR, or both recognition results to trigger the events
Tags: define the tag list, if required
You can use as many tags as you need in each event.
Video Wall*
This type of event is raised when the video wall state is changed. This happens, when objects are sent to video wall from the resources' menu in Macula Monitor, when they pop up automatically based on another event, or when users manage the video wall via dedicated tab in the Macula Monitor application. Note that events of this type are not generated if screen contents are changed directly via local screen management - drag-and-drop or double-click.
Advanced options let you specifically define the nature of that change, the video wall screen and even the target viewport.
This event can happen on three levels, depending on the defined scope:
any part of the video wall (video wall is defined, other settings set to any)
specific video wall screen (video wall and its screen are defined, leaving viewport choice to any)
specific viewport in the video wall screen (all settings defined)
The triggered events for all these areas will differ slightly (see examples below).
Available settings:
Title: user-defined event name
Source: video wall
Mode: the type of changes
Updated: any change in the specified location (any or a specific object has been placed on or removed from the target location)
Added: the target object has been added to the specified location for the very first time
Removed: the target object has been completely removed from the target location
Video wall screen: target video wall display
Viewport index: number of the port to trigger the event, set 0 (zero) for any viewport
Object: any object (if updated), or a specific map/channel (updated/added/removed)
Note that the target object must be specified for added/removed modes: there are no events for "any object added" or "any object removed". These two modes are intended to be used with concrete objects. If you do not care, which object was added or removed, use the updated mode.
The viewports are numbered starting from 1, from top to bottom and from left to right. Zero index means the event will be triggered, when the target object appears in any viewport of the target video wall display.
Event Examples:
An event is set to be produced when Channel S is removed. Depending on the defined settings, the event triggering will differ in the following way:
if only video wall is defined without any details: event will be triggered after all instances of Channel S are removed. In other words, if Channel S is present several times on different video wall screens, the Removed event will only be triggered after the last instance of Channel S is removed, and the exact video wall screen or viewport do not matter.
if a video wall screen is defined: same behavior but limited to this specific screen. If Channel S is currently displayed on other video wall screens, its presence is ignored. The last Channel S instance removed from the target screen will trigger the event.
if a specific viewport is defined: the event will be triggered every time Channel S is removed or replaced by any other channel.
Event settings are set to maximum precision: video wall, video wall screen, and viewport are specified. In this case, the event area is limited to the viewport, and replacing Channel E with Channel X will trigger the following events (if they have been set up):
Removed event for Channel E
Added event for Channel X
Updated event (no object needs to be specified)
The event is set to be generated when Channel Y is added. Consider the following scenarios:
only video wall or video wall screen is defined for the event; the target video wall screen has a 2x2 layout, and:
Channel Y pops up in any viewport, filling in an empty space or replacing any other channel: event is triggered
Channel Y pops up again in the same viewport, replacing itself (so there are no changes): event is not triggered
Channel Y is then displayed in another viewport (so that it now appear in two viewports): event is not triggered
video wall, its screen and a viewport index are defined:
every time Channel Y pops up or is placed into the target viewport, the event is triggered
*This feature is only available in Macula Enterprise edition.
Removing and adding event sources again (e.g., deleting and creating edge VCA rule with the same name) may render them unusable if they are already included in the Event & Action configuration. Make sure to verify the event operability and then re-create and re-insert the event after modifying it, if necessary.
Last updated