MarkLogic 9 Product Documentation

Search Developer's Guide — Chapter 16

Alert-Admin Role

The alert-admin role is designed to give administrators of an alerting applications all of the privileges that are needed to create configurations (alert configs) with the Alerting API. It has a significant amount of privileges, including the ability to run code as any user that has a rule, so only trusted users (users who are assumed to be non-hostile, appropriately trained, and follow proper administrative procedures) should be granted the alert-admin role. Assign the alert-admin role to administrators of your alerting application.

Alert-User Role

The alert-user role is a minimally privileged role. It is used in the Alerting API to allow regular alert users (as opposed to alert-admin users) to be able to execute code in the Alerting API. Some of that code needs to read and update documents used by the alerting application (configuration files, rules, and so on), and this role provides a mechanism for the Alerting API to give the access needed (and no more access) to users of an alerting application.

The alert-user role only has privileges that are used by the Alerting API; it does not provide execute privileges to any functions outside the scope of the Alerting API. The Alerting API uses the alert-user role as a mechanism to amp more privileged operations in a controlled way. It is therefore reasonably safe to assign this role to any user whom you trust to use your alerting application.

Roles For Internal Use Only

There are also two other roles used by the Alerting API which you should not explicitly grant to any user or role: alert-internal and alert-execution. These roles are used to amp special privileges within the context of certain functions of the Alerting API, and giving these roles to any users would give them privileges on the system that you might not want them to have; do not grant these roles to any users.

Alert Config

The alert config is the XML representation of an alerting configuration for an alerting application. Typically, an alerting application needs only one alert config, although you can have many if you need them. The Alerting API defines an XML representation of an alert config, and that XML representation is returned from the alert:make-config function. You then persist the config in the database using the alert:config-insert function. The Alerting API also has setter and getter functions to manipulate an alert config. The alert config is designed to be created and updated by an administrator of the alerting application, and therefore users who manipulate the alert config must have the alert-admin role.

Actions to Execute When an Alert Fires

An action is some XQuery or JavaScript code to execute when an alert occurs. An action could be to update a document in the database, to send an email, or whatever makes sense for your application. The action is an XQuery main module, and the Alerting API defines an XML representation of an action, and that XML representation is returned from the alert:make-action function. The action XML representation points to the XQuery main module that performs the action. You then persist this XML representation of an alert action in the database using the alert:action-insert function. The Alerting API also has setter and getter functions to manipulate an alert action. Alert actions are designed to be created and updated by an administrator of the alerting application, and therefore users who manipulate alert actions must have the alert-admin role.

Alert actions are invoked or spawned with alert:invoke-matching-actions or alert:spawn-matching-actions, and the actions can accept the following external variables:

declare namespace alert = "http://marklogic.com/xdmp/alert";

declare variable $alert:config-uri as xs:string external;
declare variable $alert:doc as node() external;
declare variable $alert:rule as element(alert:rule) external;
declare variable $alert:action as element(alert:action) external;

These external variables are available to the action if it needs to use them. To use the variables, the above variable declarations must be in the prolog of the action module that is invoked or spawned.

Rules For Firing Alerts

A rule is the criteria for which a user is alerted combined with a reference to an action to perform if that criteria is met. For example, if you are interested in any new or changed content that matches a search for jelly beans, you can define a rule that fires an alert when a new or changed document comes in that has the term jelly beans in it. This might translate into the following cts:query:

cts:word-query("jelly beans")

The rule also has an action associated with it, which will be performed if the document matches the query. Alerting applications are designed to support very large numbers of rules with fast, scalable performance. The amount of work for each rule also depends on what the action is for each rule. For example, if you have an application that has an action to send an email for each matching rule, you must consider the impact of sending all of those emails if you have large numbers of matching rules.

The Alerting API defines an XML representation of a rule, and that XML representation is returned from the alert:make-rule function. You then persist the rule in the database using the alert:rule-insert function. Rules are designed to be created and updated by regular users of the alerting application. The Alerting API also has setter and getter functions to manipulate an alert rule. Because those regular users who create rules must have the needed privileges and permissions to perform certain tasks (such as reading and updating certain documents), a minimal set of privileges are required to insert a rule. Therefore users who create rules in an alerting application must have the alert-user role, which has a minimum set of privileges.

Set Up the Configuration (User With alert-admin Role)

The first step in using the Alerting API is to create an alert config. For details about an alert config, see Alert Config. You should create the alert config as an alerting application administrator (a user with the alert-admin role or the admin role). The following sample code demonstrates how to create an alert config:

(: run this a user with the alert-admin role :)
xquery version "1.0-ml";
import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

let $config := alert:make-config(
      "my-alert-config-uri",
      "My Alerting App",
      "Alerting config for my app",
        <alert:options/> )
return
alert:config-insert($config)

Set Up Actions (User With alert-admin Role)

An alerting application administrator must also set up actions to be performed when an alert occurs. An action is an XQuery main module and can be arbitrarily simple or arbitrarily complex. Alert actions can perform any action you can write in XQuery. For details about alert actions, see Actions to Execute When an Alert Fires.

In practice, setting up an alerting action requires a good understanding of what you are trying to accomplish in an alerting application. The following is an extremely simple action that sends a log message to the error log.

xdmp:log(fn:concat(xdmp:get-current-user(), " was alerted"))

You must install your action implementation in the modules database associated with your App Server. Once the implementation is installed, you can register it using the XQuery functions alert:make-action and alert:action-insert or the ServerSide JavaScript functions alert.makeAction and alert.actionInsert.

The following procedure outlines the steps for creating, installing, and registering an alerting action:

1. Implement your action in an XQuery library module. For example, the following is a simple action that logs a message to the error log:

   xquery version "1.0-ml";
   xdmp:log(fn:concat(xdmp:get-current-user(), " was alerted"))

2. Install your action module in the modules database associated with your App Server. For example, if your logging action is stored in a filesystem file with the path /my/action/log.xqy, then the following code installs it in the modules database with the URI /alerts/log.xqy when you run it against your App Server.

   xquery version "1.0-ml";
   xdmp:eval(
     'xdmp:document-load("/my/action/log.xqy",
         map:map() => map:with("uri", "/alerts/log.xqy")
                   => map:with("format", "text"))',
     (), map:map() => map:with("database", xdmp:modules-database())
   )

3. Associate your module with an alerting action using the XQuery function alert:action-insert or the Server-Side JavaScript function alert.actionInsert. This step must be performed as a user with the alert-admin role. For example:

   xquery version "1.0-ml";
   import module namespace alert = "http://marklogic.com/xdmp/alert" 
       at "/MarkLogic/alert.xqy";
   
   let $action := alert:make-action(
       "logalert", 
       "log to ErrorLog.txt",
       xdmp:modules-database(),
       xdmp:modules-root(), 
       "/alerts/log.xqy",
       <alert:options>put anything here</alert:options> )
   return
   alert:action-insert("my-alert-config-uri", $action)

You can also create and insert an action using the REST Management API. For details, see POST /manage/v2/databases/{id|name}/alert/actions.

For a more complex example of an alert logging action, see MARKLOGIC_INSTALL_DIR/Modules/MarkLogic/alert/log.xqy in your MarkLogic installation.

Create Rules (Users With alert-user Role)

To create a rule, use the XQuery functions alert:make-rule and alert:rule-insert, or the Server-Side JavaScript functions alert.makeRule and alert.ruleInsert.

You should set up the alerting application so that regular users of the application can create rules. You might have a form, for example, to assist users in creating the rules.

The following example inserts a rule named simple that will fire the action named logalert whenever the specified word query matches. (See Set Up Actions (User With alert-admin Role) for the implementation of the logalert action.) You must run this code as a user with the alert-user role or equivalent privileges. Note that equivalent production code will usually be much more complex, as this example has no user interface.

xquery version "1.0-ml";
import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

let $rule := alert:make-rule(
    "simple", 
    "hello world rule",
    0, (: equivalent to xdmp:user(xdmp:get-current-user()) :)
    cts:word-query("hello world"),
    "logalert",
    <alert:options/> )
return
alert:rule-insert("my-alert-config-uri", $rule)

If your action performs any privileged activities, including reading or creating documents in the database, you will need to add the appropriate execute privileges and URI privileges to users running the application.

Run the Rules Against Content

To make the application fire alerts (that is, execute the actions for rules), you must run the rules against some content. You can do this in several ways, including setting up triggers with the Alerting API (alert:create-triggers), using CPF and the Alerting pipeline, or creating your own mechanism to run the rules against content.

To run the rules manually, you can use the alert:spawn-matching-actions or alert:invoke-matching-actions APIs. These are useful to run alerts in any context, either within an application or as an easy way to test your rules. The alert:spawn-matching-actions is good when you have many alerts that might fire at once, because it will spawn the actions to the task server to execute asynchronously. The alert:invoke-matching-actions API runs the action immediately, so be careful using this if there can be large numbers of matching actions, as they will all be run in the same context. You can run these APIs as any user, and whether or not they produce an action will depend upon what each rule's owner has permissions to see. The following is a very simple example that fires the previously created alert:

xquery version "1.0-ml";
import module namespace alert = "http://marklogic.com/xdmp/alert" 
  at "/MarkLogic/alert.xqy";

alert:invoke-matching-actions("my-alert-config-uri", 
      <doc>hello world</doc>, <options/>)

If you created the config, action, and rule as described in the previous sections, this logs the following to your ErrorLog.txt file when running the code as a user named some-user who has the alert-user role (assuming this user created the rule):

some-user was alerted

If you have very large numbers of alerts, and if the actions for your rules are resource-intensive, invoking or spawning matching actions can produce a significant amount of query activity for your system. This is OK, as that is the purpose of an alerting application, but you should plan your resources accordingly.