Add Actions
In addition to the default actions, certain types of actions can be added manually and customized.
To access action management in Macula Console, choose the Events & Actions section and select Actions from the menu on the left. In order to create an action, click the + New action button on the upper panel; an action configuration dialog box will open. It is also possible to add actions as you go using the Event & Action Configurator.
All available actions are grouped according to their purpose. Choose your desired action type from the list to see action-specific settings.
Channel Related Actions
Actions in this category have direct relation to channels, e.g., PTZ presets and tours, digital output (DO) state change etc.
Activate PTZ Preset
This action type allows you to make a PTZ camera go to a specific pre-configured preset. You just need to specify:
Title: a user-defined action name
Target: the target device which is to accept the PTZ command
PTZ priority: priority to execute PTZ action with (0 = lowest, 10 = highest, higher priority will override tours and user commands*)
Preset: pick one of the automatically loaded target device presets from the drop-down list (you might need to create some first via Macula Monitor)
*PTZ priority parameter is used when two or more simultaneous PTZ command requests (either from action or from direct user input) are sent at the same time. When this happens, request with a higher priority is fulfilled while request with a lower priority is delayed for ten seconds. Default PTZ priority for all actions is equal to five (medium priority), which also coincides with the default per-user PTZ priority. You can assign any action a higher PTZ priority (six to ten) or a lower one (four to zero) by editing the Activate PTZ Preset action properties. All PTZ tours have zero priority.
Use the Reload button to refresh the list of presets: this will be useful if you have created new presets while keeping the action creation dialog box open.
Activate PTZ Tour
This action is similar to the previous one but instead of activating a single PTZ profile you run a series of presets called a PTZ tour. PTZ tours must be pre-created via Macula Monitor application. For each tour, you define the order of presets and their duration.
Action: activate a custom pre-configured PTZ tour
Title: the user-defined action name
Target: the target channel that has a pre-configured PTZ tour
PTZ tour: the target PTZ preset sequence to be activated
When this action is executed, the target PTZ tour is activated and looped endlessly. You can stop the tour manually via Macula Monitor or Macula Mobile application. Tours that do not have the autostart property will also be stopped when the Macula server is restarted.
Control Digital Output
Devices having relay (digital) outputs (Dos) can have them triggered as a result of the Control digital output action. You are asked to enter the following details for this action type:
Title: user-defined action name, by default it is > Activate PTZ preset >, suggesting that before and after >> arrows you can insert the camera name and DO number/target – or, alternatively, re-define the whole title according to your own naming convention
Target: the target device which is to accept the digital input control command
Digital Output: pick one of the available Dos of the target device to be triggered
Digital Output Mode: choose whether an activation or deactivation command is sent to the target relay output
Device Action
This action is reserved for special device-side actions like wiper control, arm/disarm, lights ON/OFF etc. This functionality depends on the device integration.
Title: the user-defined action name
Target: the target channel to accept the command
Device action: integration-specific device action
Parameter: command-specific parameter, if required (e.g., alarm code for arming/disarming alarm panels)
Currently, device actions are only supported for few devices. If you do not see any available action for your device, try using the Send HTTP Request action described further: that action allows you to enter a CGI/HTTP command from device API.
The Parameter field is integration-specific. For example, when working with Satel devices, you can use device action to arm/disarm the panel, providing the code in the Parameter field.
Export Snapshot
A snapshot from the main or secondary stream of any channel can be saved as a result of an action. The file can be saved either locally (on the target server) or to a remote server (FTP).
The following settings are to be defined here:
Title: user-defined action name
Target: the server to execute this action on
Stream: main stream or substream of the target channel (the channel is to be defined at the action rule creation step)
Enable subtitles: enable this setting to activate subtitles and expand additional settings
Text: subtitle text (plain text and/or macros)
Position: subtitle alignment (top/bottom, left/right, corners)
Font: subtitle font (choose from the system dialog)
Colors: background (transparent by default), foreground (text itself), shadow (text shadow)
Export to local file: the snapshot will be saved to the target server chosen above using the specified path
Local path: full path and filename, e.g., C:\MyDirectory\{EVENT_SOURCE_TITLE}_{EVENT_TIMESTAMP}.jpg
Export to FTP directory: the snapshot will be saved onto a different machine that is not a part of the system
FTP path: full path and filename
Host: target machine's IP address or domain name
Port: port to be used for FTP connection
Username: user account name to connect to the remote server
Set password: specify a password, if required to log into the remote server
You can include text macros in the filename, for example, insert timestamps and event source title automatically to create files with different names every time the action is executed.
Start Playing an Audio File
It is possible to send an audio file to the connected device in case it has a built-in or a connected speaker: Macula server can use a .wav file to send audio to the remote camera or video server.
You need to specify:
Title: user-defined action name
Target: the channel for the sound to be sent to (if none selected, the action will be available for all channels)
File path: full path to the local *.wav file that should be used for audio output
Duration: the amount of time for the audio to be played (set zero to play the whole file)
Repeat count: the number of times for the audio file to be repeated (set zero for the file to played non-stop)
If you need the audio to be played continuously until another event stops it, set the Repeat count parameter to zero and use the Stop playing an audio file action to terminate the playback.
Stop Playing an Audio File
This action is used as a complement for the Start playing an audio file action: it stops the audio transmission in case you need to force stop it earlier than specified in the Start playing an audio file action, e.g., if the starting action lets the audio file to be played infinitely.
The following settings are available here:
Title: user-defined action name
Target: target channel (leave none for the action to be available for any channel)
Logging
In addition to default audit log, you can choose custom events to be appended to the Macula server audit log or to Windows application log.
Write to Application Log
The Application log action type allows you to write a log entry into the Windows Application log, which will be accessible via Windows Event Viewer. The log entry level is Information and entry source is Macula Server. You can define:
Title: a use-defined action name inside the Macula Console; by default it is Write to Application log
Log Message: the message text to appear in Windows Application log
Use the Insert Field button on the right-hand side (it appears when you have clicked inside the text area) or right-click the text area and choose Insert to add a text macro (see Action Parameters further in this topic for details).
Write to Audit Log
The Audit log action type is similar to that of Application log: it allows you to write a log entry into the Macula own Audit log, which will be accessible via Macula Console, in the Audit section. The log entry is added in the Server audio section and its event type will be User defined. You can set:
Title: a use-defined action name inside to be used in E&A; by default it is Write to Audit log
Log Message: the message text to appear in the Audit log
Use the Insert Field button on the right-hand side (it appears when you have clicked inside the text area) or right-click the text area and choose Insert to add a text macro (see Action Parameters further in this topic for details).
Notifications
Actions in this section allow you to send all kinds of alerts to clients and also email notifications.
Highlight On Map
If your target device appears on one or more maps, you can visually accent it on the map as a result of the triggered event. It is possible to define one particular map or make the device become highlighted on all maps where is has been placed.
The following objects are supported for this action as targets:
Channels (channel markers will be highlighted)
User buttons (user button markers will be highlighted)
Pop Up Object On Screen
You can set up individual channels, maps and layouts to appear on a specific video wall display as a result of some triggered event, e.g. motion detected in certain regions. If you wish an object to pop up in all connected Macula Monitor applications without using video walls, use the built-in (default) event of the Pop up on screen type.
Automatic Pop-up actions (extended)
Built-in per-channel Pop-up / Pop-up playback is created automatically for every channel
Built-in per-server Pop-up / Pop-up playback – identical actions are added automatically for every server in Macula Console. These appear in the Actions list as “parametric” items with one extra field - Channel. You can:
select any channel manually, or
leave the field empty ➜ at run-time it is auto-filled with the event’s source channel (if the event has one).
User-defined Pop-up actions with empty source – when you create a custom Pop-up (for Videowalls, Map highlights, etc.) you can now set Source = None.
The action is then replicated to all channels, maps and layouts, plus a parametric copy under each server (same Channel field as above).
In a rule, leaving that Channel parameter blank will again default to the event’s channel at execution time.
In practice:
Want a single rule that pops the triggering camera on any operator screen? Pick the built-in per-server Pop-up and leave Channel empty. Need a Videowall tile to show whatever camera fired the rule? Create one user-defined Pop-up with Source = None and attach it.
What you need to specify in the action properties is:
Title: user-defined action name, by default it is [channel] Pop up and object on screen [Video wall name]
Target: a channel, map or a pre-created shared layout to appear on the screen
Video wall: target video wall for the object to appear on
Video wall screen: a specific display in the video wall layout for your object to appear on
Viewport index: the exact position of the video output cell in the grid (starting from 1, left to right, top to bottom), leave 0 to use the first available viewport
If you do not care, which viewport is used for popup, leave the viewport index parameter equal to 0. This will send the popup object to the first empty viewport; if all viewports are occupied, the object will pop up to the first non-locked one. When all viewports are occupied and locked and the viewport index is set to 0 (=any viewport), the popup will not work on that screen.
If the target viewport is set (is different from 0) but it is occupied and locked on the Macula Monitor side, the target channel will force pop up anyway, and the viewport state will stay locked.
You can create new maps right from the object selection dialog in case you have not created them beforehand.
Send Email
In order to send an email notification, you are requested to define the following values in the action settings:
Title: a user-defined action name; by default it is <mailserver> Send email, you can insert the device name and target email address - or, alternatively, you can re-define the whole title according to your own naming convention
Target: specify the SMTP server to be used for email sending; if none are selected, the action will be available for selection on any of the existing configured mail servers when creating a rule
To: notification recipient email address
Subject: email notification subject (use the Insert field button to add text macros)
Body: email notification body text (use the Insert field button to add text macros)
Send Email with a Snapshot
This action is similar to the Send Email action described above, with all the settings being the same except for one: it allows to attach a snapshot from a channel and send it together with the email. The channel is specified when creating a rule with this action.
Additional setting:
Attach snapshot: choose if you want to take a snapshot of main stream or substream of a channel and deliver it together with the message
Snapshot title: user-defined file name, e.g., Snap.jpg, or Snap_{EVENT_TIME}_from_{ACTION_PARAMETER_TITLE}.jpg
Enable subtitles: enable this setting to activate subtitles and expand additional settings
Text: subtitle text (plain text and/or macros)
Position: subtitle alignment (top/bottom, left/right, corners)
Font: subtitle font (choose from the system dialog)
Colors: background (transparent by default), foreground (text itself), shadow (text shadow)
The subtitles will be hard merged with the exported image.
If you specify no snapshot source when creating the rule, a regular email will be sent. You will find more details on attaching the snapshot in the Rules section of this document.
Send MQTT Notification
This action uses a pre-configured MQTT Client to publish MQTT messages. You must have at least one MQTT Client in your server configuration, and a running MQTT broker to accept and broadcast the message. Message/connection settings are typical MQTT message properties; make sure your broker supports the settings you enter here.
Available settings:
Title: action name that will appear in the E&A Configurator
Target: pre-configured MQTT client; leave empty for the action to be available for all existing MQTT clients
Topic: MQTT topic to be published
Text: MQTT message text to be published
QoS: required level of the MQTT quality of service
You can use macros in all text fields to pass parameters like {EVENT_TIMESTAMP} or {EVENT_TITLE}. To insert those, right-click the text field or use the Insert text field button.
Send SMS
Using this action, you can send short messages to the pre-defined numbers. GMS modems must be present in the server configuration for this action to work.
You have to fill in the following:
Title: user-defined action name
Source: existing modem hardware to send the message
Phone: the recipient's phone number in international format (cannot be left empty)
Text: SMS text to be sent, right-click to insert text macros like {EVENT_SOURCE_TITLE}
Keep in mind the maximum possible SMS length when composing the message. Longer messages will be split into multiple SMS.
Send Event to Client
This action allows to send a push notification to all or specific client applications. This may be just a pop-up message, or an event in the channel notification area with a sound, or all of these combined.
Available settings:
Title: user-defined (custom) action name that will appear in the E&A Configurator
Message: notification body text (use the Insert field button to add text macros)
Display event in alerts: mark this if you want a message to be appended to the Macula Monitor log in the Alerts section
Display a warning message box: mark this if you want a dialog box to pop up on the Macula Monitor side (to be closed by the user)
Display event in notification panel: the message will be shown in the notification panel of the live view of a specific channel (you will have to set the channel when creating the rule)
Display event in mobile application: the message will be sent as a push notification to all Macula Mobile clients that have the target server configured
Play audio notification: play a sound on the Macula Monitor side; sounds themselves are defined in each Macula Monitor application
Audio notification: sound notification number, from 1 to 10 (here, you just specify the number, actual sound is defined per client and may not coincide in different application instances)
Send event to specific user or user group: show the notification only to a specific user or user group
Recording Related Actions
Several actions are related to recording: these can change main and secondary stream recording profiles, as well as append new items into the archive, such as bookmarks.
Activate Recording Profile
Any of the existing recording profiles can be activated for the device of your choice as a result of a triggered event. You can separately activate main stream and substream recording: use the Activate Recording Profile action for main stream and the Activate Substream Recording Profile action for secondary stream. Enter action details as follows:
Title: the user-defined action name
Target: the target device for which recording is to be activate
Recording profile: the pre-configured recording profile to be activated as an action; you will find profile configuration tips further in this section of the manual
The recording profiles are changed within the channel's recording configuration. Thus, for example, if the channel's recording configuration has a 3-second pre-recording duration, it will stay 3s for any recording profile you activate via E&A.
Recording profile activation cannot call off the default recording configuration (the one currently assigned to the target channel); rather, this action can only add more recordings. Thus, channel default recording configuration must define the minimum required recording scheme (based on a single profile or on a schedule) and E&A scenarios will add to that.
Example: a channel is set to record based on motion. There are two user buttons: one of them sets the channel to Constant recording, and the other sets the No recording profile. Triggering the first button will activate constant recording, and triggering the second button will return channel recording to its default state (which is Recording by motion) instead of disabling the recording at all.
Recording profile activation cannot call off the default recording configuration (the one currently assigned to the target channel); rather, this action can only add more recordings. Thus, channel default recording configuration must define the minimum required recording scheme (based on a single profile or on a schedule) and E&A scenarios will add to that.
Example: a channel is set to record based on motion. There are two user buttons: one of them sets the channel to Constant recording, and the other sets the No recording profile. Triggering the first button will activate constant recording, and triggering the second button will return channel recording to its default state (which is Recording by motion) instead of disabling the recording at all.
Recording Triggering Examples
When channel recording profile includes alert-based recording, recording can be activated as a result of a Generate Alert type action and its engagement time is determined by the profile's post-recording time parameter. In this case, actual recording profile is not changed and the current recording profile is used (the one assigned to the channel through its recording configuration). The default (built-in) recording profiles have post-recording intervals of 10 seconds, which may be fine when conducting, e.g., motion-based recording (video is recorded for 10s after motion event), but may not be suitable for other types of events. In such case, you can pre-configure any number of different recording profiles and use them for action setup.
If a recording profile is triggered by an Activate Recording Profile type action, the recording profile used for the target channel is complemented with the profile triggered from E&A, and recording duration can be controlled using action delay timers.
Scenario 1. The camera's recording configuration is normally motion-based. The action is intended to be used for recording based on digital input events, which are triggered when someone opens main entrance door; starting from that point, the video and audio streams will be recorded continuously for one minute.
channel base recording configuration: motion-based video recording
actions triggering recording profiles:
action #1 triggers a recording profile with continuous video + audio (e.g., built-in Continuous Recording profile)
action #2 triggers the built-in No Recording profile: as a result, channel recording is returned to its default (configured) state
action #2 is delayed for one minute using a Delay Timer
Scenario 2. The camera normally records continuous video with low FPS during the daytime, and does not record anything at night and during weekends. If camera VCA detects fire or smoke in the area, continuous recording at full frame rate will be conducted for 30 minutes.
channel base recording configuration: based on schedule, continuous recording at restricted FPS + no recording
action triggering recording profiles:
action #1 triggers continuous video recording without frame rate limitation
action #2 triggers the built-in No Recording profile: as a result, channel recording is returned to its default (configured) state
action #2 is delayed for thirty minutes using a Delay Timer
Create Bookmark
Bookmarks can be created by the server, based on any available event. This can be done either completely automatically or complemented with user input - from the users who are connected via Macula Monitor application.
Available settings:
Title: custom (user-defined) action name
Target: server to add the bookmark on (select none to make the action visible on all servers in the system)
Bookmark title: name that will appear in the archive and also displayed to users, if user description is requested (use the Insert field button to add text macros)
Description: extra information to be stored with the bookmark (use the Insert field button to add text macros)
Severity: bookmark severity level (info = lowest, critical = highest); you can change the severity level colors via server settings, Bookmark policy tab
Request user description: enable this if you want to obtain bookmark description from Macula Monitor users - this comes useful when you require feedback from users and/or when the description may differ from time to time
Request timeout: defines for how long the description request will be displayed on the Macula Monitor side
Request specific user or user group: display confirmation dialog box only to the target user or user group; if not defined, the request will be sent to all connected users
Note that the target channel is not specified at this step: you will have an option to specify it using the Target Channel button when you create a rule with this particular Add Bookmark action. If the source event of such a rule is channel-specific (e.g., Video Lost, Motion), the channel will be set automatically. Please see the Add Rules section for examples.
Scenario 1: fully automated
In the Add Bookmark action settings, do not enable the Request user description option. Instead, specify desired bookmark title and description. Now, when you use this action in a rule, a bookmark will be added automatically with the pre-defined description.
Scenario 2: bookmark with user confirmation
Enable the Request user description option and specify the bookmark title: make sure to make the title comprehensible as it will be displayed to the Macula Monitor user when prompting for the comment. Optionally, you can specify the description - it will be used when no user input is specified (users ignored or missed the description dialog box).
After you have added the action, you can go ahead and use it in the E&A Configurator: there, upon adding a rule, you will have an option to specify the target channel for the bookmark to be added to.
Other Actions
Actions having no special category are listed here.
External Service
For external services that have their own events, it is possible to trigger these as actions from Macula servers. You need to specify:
Title: user-defined action title
External service: external service (connected to the Macula system via HTTP API) to accept the data
Target action: choose one from the list of available items (availability is ensured on the external service side)
OPC Client Action
This action type uses an existing OPC client configuration to send write commands to an OPC server, thus changing values of its nodes.
You need to define:
Title: user-defined action name
Target: OPC client configuration (connection to an OPC server)
Action: operation to be performed with the data node value
Variable: target OPC server data node (choose one from the list), must be of compatible type and have a write permission
Value type: one of the standard data types, auto detected
Value: new value to be assigned to the variable, must match the variable value type
Run Program
The Run program option gives you the opportunity to define a third-party application (script, batch or a GUI application) that will be launched as a reaction to defined camera events. The following parameters should be specified:
Title: a user-defined action name
Target: target Macula server to execute program on
File Path: full path to the executable file
Parameters: input parameters, if the program launched accepts any (e.g., a batch file) (use the Insert field button to add text macros)
Run Mode: execution mode - hidden (silent, invisible to server user), minimized (minimized to taskbar) or normal (program will run in its default state)
Use the Insert Field button on the right-hand side (it appears when you have clicked inside the text area) or right-click the text area and choose Insert to add a text macro (see Action Parameters further in this topic for details) into the Parameters field.
Send HTTP Request
As a result of a triggered event, HTTP/CGI requests can be sent from Macula servers to any third-party servers or devices that can accept such commands. The target devices can be third-party software, Web servers, cameras or any access control hardware. This event is similar to the previous one, with the difference that here there is a single HTTP request, while using the Run Program action you can program multiple requests with necessary delays and internal logic.
This action supports both HTTP and HTTPS. For secure HTTP, use port 443 as default, or whichever port is configured on the remote service.
Things to be defined:
Title: user-defined action name, by default it is Send HTTP request [target host]
Target server: a server for the action to be available on; if no server is defined, the action will be available on all servers
Host: an IP or hostname that will be accepting the HTTP request (in case of HTTPS - add https:// before your IP address)
Port: port number to accept the request, port 80 is default
Username: a username to log into the target host, if necessary
Password: a password to log into the target host, if necessary; to change the password when editing the action, put a check mark on the Set password and define a password below
Request: HTTP command string
The resulting request link will be formed as a combination of the host and request fields with the specified port, plus username and password, if specified.
Use the Insert Field button on the right-hand side (it appears when you have clicked inside the text area) or right-click the text area and choose Insert to add a text macro (see Action Parameters further in this topic for details) to be passed as a parameter in the HTTP request.
SNMP Trap
This event allows Macula server to act as an SNMP agent and generate and send trap messages to a third-party SNMP manager.
You need to define:
Title: user-defined action name, by default it is [server] SNMP trap [host] [port]
Target: Macula server for the action to exist on; if none selected, the action will be visible on all servers
Host: target SMTP manager address
Port: target port
Community: SMTP community expected by the SMTP manager
Trap ID: automatically generated ID
Message: text message to be sent
Use the Insert Field button on the right-hand side (it appears when you have clicked inside the text area) or right-click the text area and choose Insert to add a text macro (see Action Parameters further in this topic for details) to be passed as a parameter.
Action Parameters (Macros)
Actions that handle text information (log messages, send emails and run third-party program) can accept macro commands. Currently, the available parameters are:
{EVENT_ID} - internal identifier of the triggered event
{EVENT_TITLE} - user-defined name of the triggered event
{EVENT_SOURCE_ID} - internal identifier of the event source
{EVENT_SOURCE_TITLE} - user-defined name of the event source
{EVENT_UTIME} - event UTC time
{EVENT_UDATE} - event UTC date
{EVENT_TIME} - event local time
{EVENT_DATE} - event local date
{EVENT_TIMESTAMP} - event UTC timestamp in a system-independent format YYYY-MM-DD hh:mm:ss.ms
{EVENT_TIMESTAMP_UNIX_MS} - event timestamp as Unix Epoch time
{ADDITION_INFORMATION} - extra information for Disk Excluding, Fallback activating and Recording Error events
{ACTION_ID} - internal identifier of the action
{ACTION_TITLE} - user-defined name of the action
{ACTION_TARGET_ID} - internal identifier of the action target (usually, a server)
{ACTION_TARGET_TITLE} - user-defined name of the action target (usually, a server)
{ACTION_PARAMETER_ID} -internal identifier of the additional action parameter (e.g., target channel defined in the rule)
{ACTION_PARAMETER_TITLE} - user-defined name of the additional action parameter (e.g., target channel defined in the rule)
{VALUE} - number plate value from the Tag Matched event
{CHANNEL_RECORDING_ID} - channel recording identifier, as displayed in the channel details when IDs are enabled in the Macula Console app settings; channel ID is used
Example of a text string containing a macro: "{EVENT_TITLE} event occurred on {EVENT_UDATE} at {EVENT_UTIME}".
Event sources are listed for every rule in the Rules section of Events & Actions; typically, these are servers, devices and other resources capable of generating events (e.g., user buttons). Action parameter is a supplementary item added to the rule, e.g., target channel for the text notification, source snapshot for the attaching snapshots to emails or exporting them.
The {ADDITION_INFORMATION} macro has support for parameters. These depend on the originating event. For example, for LPR events, try the following ones:
{ADDITION_INFORMATION:Plate} for the license plate number;
similarly, use Speed for the estimated vehicle speed
and Confidence to get the recognition accuracy,
Info1/Info2 fields are available for the Macula LPR external service.
For the face recognition events, additional parameters may be equal to Subject and Tag, as well as SubjectSimilarity (if a person was found in the DB)
When you have finished, click OK to save and close the dialog box. The newly created action will appear in the item list under Actions and will be available for configuration.
Last updated