Skip navigation
All Places > Products > RSA NetWitness Platform > RSA NetWitness Platform Online Documentation > Documents
Log in to create and rate content, and to follow, bookmark, and share content with other members.

Alerting: ESA Annotations

Document created by RSA Information Design and Development Employee on Jan 30, 2020Last modified by RSA Information Design and Development Employee on Jul 14, 2020
Version 3Show Document
  • View in full screen mode

This topic describes annotations that NetWitness Platform provides to use in advanced EPL rules.

For best practices on writing advanced EPL rules, see ESA Rule Writing Best Practices.

@RSAAlert Annotation

The @RSAAlert annotation is used to mark which EPL statements are linked to generating alert notifications. It is designed to work with the alert notification suppression feature in the Rule Builder user interface.

The @RSAAlert annotation can be useful when working with alert notifications, especially if you want to filter notifications, such as sending one notification for each user that triggers an alert.

For example, suppose you want to generate alert notifications for login failures. You could add the following statement:

@RSAAlert select * from event(msg_id=“login_fail")


Event numberMessage IDusernamesrc_IPTime


For the above statement, five alert notifications are generated.

However, suppose you wanted to modify the statement to generate one alert for each separate username. You can use the identifier attribute. For example, the statement @RSAAlert(identifier={”username”}) SELECT* FROM Event(msg_id=”login_fail”) generates one notification for the first alert for “bob” and one for the first alert for “alice." Subsequent alerts for “bob” and “alice” are ignored.

You can further distinguish the users by adding details via the identifier variable. For example, you can distinguish by user and IP address using the following statement: @RSAAlert(identifier={”username”, "src_ip"}) SELECT* FROM Event(msg_id=”login_fail”). Then, you would see notifications generated by user name and IP address (one alert for "alice" at, another alert for "alice" at, and an alert for "bob" at

To use identifiers with Alert Notification Suppression:

The @RSAAlert annotation is designed to work with the alert notification suppression feature in the Rule Builder user interface. To do this:

  1. Create a rule in the Rule Builder user interface, and select the alert suppression feature when configuring notifications.

Notification Suppression

  1. Copy the code from the Rule Builder rule into a new advanced rule.

  2. Configure the advanced rule to include identifiers (as described above) and save the advanced rule.

  3. Delete the original rule builder rule.

@RSAPersist Annotation

The @RSAPersist annotation is used to mark a named window as an ESA managed window for persistence. By marking the named window as an ESA managed window, ESA periodically writes the contents of the window to disk and restores them back if the window is un-deployed and re-deployed. The systems take a snapshot just before the module is un-deployed and the window is removed. Conversely, it restores the window contents from the snapshot just after the module is re-deployed. This ensures that the contents of the window are not lost if the module state is altered or if the ESA service goes down.

For example, consider a named window, DHCPTracker that holds a mapping from IP addresses to each assigned hostname.You can annotate the statement with the @RSAPersist annotation as:

create window DHCPTracker.std:unique(ip_src) as (ip_src string, alias_host string);
insert into DHCPTracker select IP as ip_src, HostName as alias_host from DHCPAssignment(ID=32);

Note: All windows definitions are not suitable for persistence. @RSAPersist annotation must be used with care. If the window has timed-records or if it depends on time based constraints it is very likely that the reverted snapshots will not restore it to the correct state. Also, any changes to the window definition will invalidate the snapshots and reset the window to a blank state. The system does not do any semantic analysis to determine if the changes to the window definition are conflicting or not. Note that other parts of a module (that is, other than the particular CREATE WINDOW call that defines the window) may change, without invalidating the snapshots.

@UsesEnrichment ( and later)

The @UsesEnrichment can be used in advanced EPL rules to reference enrichments. In order to synchronize enrichments with ESA, all enrichment dependencies in EPL rules must be referenced with the @UsesEnrichment annotation.

The @UsesEnrichment annotation uses the following format:

@UsesEnrichment(name= '<enrichment_name>')

For example, the following EPL references a whitelist enrichment:

@UsesEnrichment(name = 'Whitelist')


SELECT * FROM Event(ip_src NOT IN (SELECT ip_address FROM Whitelist))


The @Name is the statement name defined in ESA advanced rules. It is used to dynamically generate statement names in ESA alerts. The statement name of only an alert triggering statement is displayed. This annotation has meta keys enclosed in curly brackets.

The @Name annotation uses the following format:

@Name("<static_part_of_statement_name> {meta_key1} {meta_key2}…")

For example, the following EPL references meta keys ip_src and user_name whose values will be dynamically generated.

@Name(“Login Event to {ip_src} by {user_name}”)

Note: You can specify any number of meta keys in the statement for dynamic statement name generation.
The length of individual meta key is limited to 64, after which the value is truncated and appended with “…”.
The length of the dynamic generation of statement name is limited to 128, after which the value is truncated to 128 and appended with “…”. All the remaining values post truncation will be treated as static values.

You are here
Table of Contents > Add an Advanced EPL Rule > ESA Annotations