> For the complete documentation index, see [llms.txt](https://gsfcorp.gitbook.io/macula/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gsfcorp.gitbook.io/macula/administration-guide-v1.33.0/add-rules.md). # Add Rules All existing and added entities of E\&A can be combined to create **rules** (rule map) for each server, which will define server behavior if events are triggered. This section will guide you through related features, explain the meaning and purpose of used items and provide usage examples. The rule map is created via the ***Event & Action Configurator***: to open it, go to the *Events & Actions* section in Macula Console and then click *Rules* in the menu on the left, then select the target server for which you wish to add the E\&A setup, and then click the *Open configurator* button on the upper panel. To change the target server, click the *Change* button next to the server name and then pick one from the available server list.
The *Event & Action Configurator* will open in a new window; by default, no rules are defined.
You can pre-create all events, actions, conditions and schedules beforehand using the relevant menu sections in Macula Console, or create necessary items as you go from the configurator. Delay timers can only be created as you go for the specified rule and are not saved as independent entities. #### Add and Edit Events Choose the target item from the Events list and then click the *+ Event* button below: configuration dialog box will then open with the target device pre-selected. Here you can add alerts from device digital inputs and VCA notifications; see the detailed description of how to create events in the Add Events section. Events are arranged by sources. Typical event sources are: channels, channel groups, servers, user buttons, video walls, external services. {% hint style="info" %} Built-in (default) types of events - lost/restored video, recording errors etc. - cannot be edited. This is also the case for all built-in actions. {% endhint %} #### Add and Edit Actions Choose a target item from the Actions list and then click the *+ Action* button below: the configuration dialog box will then open with the target device pre-selected. Here you can add reactions to the following types of events: * trigger device digital output * write to OS Application log * activate target device's PTZ preset * activate main/secondary stream recording profile * send an email notification * run a third-party program See the detailed description of how to create and configure actions in the Add Actions section. #### Manage Rules To start combining events, actions and additional controls, simply follow this scheme: * find your desired **event** in the *Events* list - use search filter on the top panel, if required * use the < and > arrows or double-click events to add/remove them to/from the *Rules* list * click free space of the target rule in the *Rules* list (use CTRL or Shift to select multiple ones) - the selected rows will then become highlighted green * find your desired **action** in the *Actions* list - use search filter on top, if required * use the < and > arrows or double-click actions to add/remove them to/from the *Rules* list, and the + button to add more than one action for a single event * select desired actions and add auxiliary controls by clicking buttons on the bottom panel (see description below for details) {% hint style="info" %} **Useful tips:** * double-click a device (highlighted grey) to add **all** its events to the rule map * to **add** an action to an existing rule, use the + button instead of the < button: the original event will be duplicated and new action will be added to the copy * use the + button between *Rules* and *Actions* lists to add **multiple actions** of the same type to the selected rule(s) * to clear the *Rules* list, select all rules using Shift or CTRL+A, then press < button on the left to remove all events * use the *Expand/Collapse list* button on top of each column to hide all contents and only display node titles {% endhint %} The rule header displays the event source and event itself; below, related actions are listed, each with its own set of special controls. Actions of the same type are listed under the same rule header; for all other cases, the events are duplicated, resulting in a separate rule. One condition, one schedule and one delay timer can be attached to **each action**.
Once the rule map has been created, click the *OK* button in the bottom right corner to **save and exit**. Note that simply closing the *Event & Action Configurator* is analogous to clicking *Cancel*: no changes will be saved. #### Conditions, Schedules and Delay Timers For each event/action pair that is added to the rule map, additional options can be defined in the form of conditions, delays periods and schedules. Select one or multiple target events from the *Rules* list and then click desired control item in the bottom panel.
To remove auxiliary controls from a rule, select it in the *Rules* list and click the *Clear* button on the bottom panel. Note that all defined conditions, timers and schedules will be removed from the target rule, and it is not possible to de-attach them one by one. #### Delay Timers To add a pause timer for specific actions, select one or more of the mapped rules (use *CTRL+click* or *Shift+click* to mark multiple items) subject to delay, and then click the *Delay Timer* button on the bottom panel of the central part of the *Event & Action Configurator*.
Set the delay period for the target timer. Time can be adjusted in the following ways: * click hours/minutes/seconds and then use the UP and DOWN arrows on the right, or * click hours/minutes/seconds and use the mouse scroll, while still holding mouse cursor over the relevant timestamp section, or * enter the time manually using the keyboard numpad. Next, choose the pause mode: * **Create a separate action**: new actions of the same type will be created regardless of the acting delay timer, and queued in the same way as the original delayed action * **Extend a postponed action**: new events of the same type will restart the timer, postponing the resulting action for the specified amount of time When you have finished, click *OK* to save and exit the dialog box. The newly created delay timer will be assigned to the pre-selected actions. {% hint style="info" %} **Extending** **an action** allows you to postpone the action execution repeatedly if more events of the same type arrive within the chosen time period. For example, if incoming events are of a *Recording Error* type, there may come too much of them at once e.g. in case of a major storage issue, causing a lot of triggered actions of the same type, while only a single action may be desirable. Say, if required action is *Write to application log*, setting a delay timer to *5 minutes + extended action* will postpone the email sending for 5 minutes every time a new recording error appears; when, at a certain point, more than 5 minutes have passed without new incoming events, a single log entry will be eventually created. The **separate action** option, on the contrary, will force logging for every single triggered event. {% endhint %} To remove a delay timer from rule configuration, click the timer to highlight it within the rule, and then click the *Clear* button in the bottom panel. Note that, if there are schedules and/or conditions attached to the same rule, they will be removed as well. #### Schedules Schedules are used when you wish a rule to be active based on a pre-defined itinerary. You can create any number of custom schedules via the *Conditions* section in the Macula Console and then use them for rule control: see Create Schedules section in this document for a detailed explanation of this. Select one or multiple target events from the *Rules* list and then click *Schedule* button in the bottom panel. #### Conditions Conditions are supplementary variables that can allow or prevent action execution. The decision is taken based on the condition state: if the condition is **ON**, the planned action will be executed; if the condition is **OFF**, the action will not be performed regardless of the frequency of the triggered event. The condition state can be changed as a result of some other event, so ad additional rule should be added to perform this task; alternatively, you can manually set and unset conditions at your will. Thus, conditions allow the activation and deactivation of rules without requiring them to be entirely deleted. To assign a condition to the rule, choose one or multiple target events from the *Rules* list and click the *Condition* button on the bottom panel, then either select target condition from the list or create a new one. Please read the Conditions topic of this document if this feature is new to you: it contains detailed description and usage examples. #### Source and Target Channels Some actions participating in the rule creation need a related channel to be specified so that these rules can be properly executed. For such actions, the source/target channel is specified when you create a rule involving such an action: corresponding additional buttons appear on the bottom panel or the rule map section, next to conditions, schedules and delay timers. Each action allows exactly one related channel; if you need, for instance, two snapshots to be sent via email, just add two actions of the same type and specify different source channels.
When you combine such actions with events that already are related to some channel (e.g., *Video Lost*, *Motion*, *VCA*, *DI*), that channel is selected automatically for the resulting action. For the rest of events, the channel is not set by default and you need to use the **target/source channel** buttons on the panel below the rules. Also, you can set a different channel instead of the one selected automatically by using the same buttons. #### Attaching Snapshots The *Send Email* action allows you to attach a snapshot from one channel and deliver it together with the email to the recipient. The snapshot can be taken either from the main stream or from the secondary stream (substream), if available. At the action creation time, you just enable the snapshot from either main or secondary stream, and then you will have an option to specify the source channel when creating the rule that involves such an action. When creating the Send Email action, you can choose to attach a snapshot by selecting the necessary stream option (main/sub) from the drop-down list. The channel itself is not specified at this step as it is not known beforehand, to which channel this action will be applied in future - this makes the action universal, applicable to any target channel.
The source channel is specified when you attach the *Send Email* action to an event, i.e., create a rule in the *Event & Action Configurator:* * if the event in the rule has some channel as a source (e.g., motion, VCA, DI), this channel is set automatically as a snapshot source * for events having sources other than channels (e.g., user buttons, server events), you can specify the source channel by using the *Snapshot source* button on the panel below the rule map * you can modify the source channel by using the same button, and also disable snapshot attachment by selecting *none* as the source Email sending rules can accept any extra modifiers just like any other rules – delay Timer, conditions and schedules, each of them once. #### Adding Target Channels to Rules There are other actions, apart from *Send Email with a Snapshot*, that are related to channels and may use them as action targets. These are, namely, *Create Bookmark* and *Send Event to Client*.
The *Create Bookmark* action requires a channel to add the bookmark to. To add bookmarks to multiple channels simultaneously, add several actions of the *Create Bookmark* type and specify different target channels for each. The *Send Event to Client* action only needs a target channel to be specified in case the action has the *Display event in notification panel* option enabled: as a result, the pre-defined message will appear in the notification area of the specified channel (overlay area in live view, the same place where the stream errors appear - see Macula Monitor user manual for more information). Similarly to bookmarks, you can add more than one action of the same type and add different channels as targets in order to display the message in the notification areas of these channels. #### Examples Here are a few examples of the *Event & Action Configurator* usage. You will find more examples in each of the related topics. #### Create Bookmark Time Offset The **Create bookmark** action can shift the bookmark timestamp relative to the event time. Use the **Time offset** field to create the bookmark slightly earlier or later than the event that triggered the action.
The default value is 00:00. The offset can be set up to one minute earlier or later than the event time. Use a negative value when the bookmark should start before the event moment. For example, -00:05 creates the bookmark 5 seconds before the event. This is useful when detection happens slightly after the actual start of the situation and operators need the bookmark to include the beginning of the event. Use a positive value when the bookmark should be placed after the event moment. In the Monitor application, snapshots from all available (those having video) channels will be saved into the specified location. #### Email Notification on Video Loss Task: send an email notification when the video stream from certain channel(s) is not available for more than five minutes. Preliminary setup: * in the channel settings, set the video loss timeout to 300s (five minutes) for each target channel (select multiple channels and use the *Bulk Edit* button on the upper panel to modify several channels at once) * configure a mail server with your desired parameters * create an action: send email to the responsible person using the pre-configured SMTP server Rules: * the *Video lost* event from each of the target devices triggers the *Send email* action
Note that you do not need to create the *Video lost* event as it is already exists by default for each channel. #### Pop Up Channel on Video Analytics Event Let's see how to pop up video channels if built-in video analytics (VA) trigger a line cross event. Such rules let you efficiently load operators' monitors, so that they only see relevant video instead of tons of static channels. Task: if video analytics on Channel X detect a person crossing a line, pop up Channel A on all operators' screens. Preliminary setup: * Channel A: enable VA, add a crossing line, add a line event of the *Crossed* type with the *Person* class enabled Rule for Channel A: * *VCA rule* with the *Line crossed* parameter triggers the *Pop up on screen* action If you want to limit the popup to a specific video wall display, simply create an additional action of the *Popup object* type. In the action properties, you will be able to specify the video wall display and even viewport index as the channel destination. #### Global Handling of Recording Errors This example will cover a use case with a global event, showing how multiple servers within a single system can be involved in a more sophisticated chain of events and actions. Task: if there are recording errors on Server A, log this event locally and also add corresponding entry to Windows Application log on the central server. The *Recording error* event is there by default and so there is no need to create it. Preliminary setup: * Server A: *Write to A Application log* action * Central Server: *Write to CS Application log* action * Global event *Recording Error on Server A* Rules for Server A: * *Recording error* event triggers local *Write to A Application log* action * *Recording error* event triggers *Send global event* action for the *Recording Error on Server A* event Central Server rules: * *Recording Error on Server A* global event triggers its own *Write to CS Application log* action
Server A generates a global alert and sends it to all servers in the system.
The Central Server is subscribed to the global alert and therefore reacts with the assigned action.