MarkLogic Server 11.0 Product Documentation

REST Application Developer's Guide — Chapter 7

Summary of /alert Services

The table below provides a brief summary of the alerting services provided by REST Client API:

Alerting Pre-Requisites

You should also enable fast reverse searches on the content database associated with your REST API instance. Enable fast reverse searches using the Admin Interface, as described in Indexes for Reverse Queries in Search Developer's Guide, or using the XQuery function admin:database-set-fast-reverse-searches.

The rest-writer role or equivalent privileges is required to create and delete alerting rules. All other operations require the rest-reader or equivalent privileges. Additional privileges may be required to access input documents during rule match operations.

Alerting Concepts

An alerting application is one that takes action whenever content matches a pre-defined set of criteria. For example, send an email notification to a user whenever a document about influenza is added to the database. In this case, the criteria might be the abstract contains the word influenza, and the action is send an email.

MarkLogic Server supports server-side alerting through the XQuery API and Content Processing Framework (CPF), and client-side alerting through the REST and Java APIs.

A server-side alerting application usually uses a push model. You register alerting rules and XQuery action functions with MarkLogic Server. Whenever content matches the rules, MarkLogic Server evaluates the action functions. For details, see Creating Alerting Applications in Search Developer's Guide.

By contrast, a client-side alerting application uses a pull alerting model. You register alerting rules with MarkLogic Server, as in the push model. However, your application must poll MarkLogic Server for matches to the configured rules, and the application initiates actions in response to matches. This is the model used by the REST Client API.

An alerting rule is a query used in a reverse query to determine whether or not a search using that query would match a given document. A normal search query asks What documents match these search criteria? A reverse query asks What criteria match this document? In the influenza example above, you might define a rule that is a word query for influenza, with an element constraint of <abstract/>. Queries associated with alerting rules are stored in the database.

MarkLogic Server provides fast, scalable rule matching by storing queries in alerting rules in the database and indexing them in the reverse query index. You must explicitly enable fast reverse searches on your content database to take advantage of the reverse query index. For details, see Indexes for Reverse Queries in Search Developer's Guide.

Use the procedures described in this chapter to create and maintain search rules and to test documents for matches to the rules installed in your REST API instance. Determining what actions to take in response to a match and initiating those actions is left to the application.

Defining an Alerting Rule

An alerting rule is defined by a name, a query, and optional metadata. The core of a rule is the combined query that describes the search criteria to use in future match operation. A combined query is a search wrapper around a string and/or structured query plus query options; for details, see Specifying Dynamic Query Options with Combined Query.

All rules must have a name. You can either specify the name explicitly in the rule definition, or have MarkLogic Server internally add a name derived from the name path step in the URI used to install the rule in the REST API instance. If you specify an explicit name in the definition, it must match the name in the PUT request URI.

Use the following template for defining the rule in the request body.

<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>rule-name</rapi:name>
  <rapi:description>optional description</rapi:description">
  <rapi:rule-metadata>
    optional user-defined metadata
  </rapi:rule-metadata>
  <!-- required combined query -->
</rapi:rule>

{"rule":
  "name": "rule-name",
  "description": "optional description",
  "rule-metadata": optional user-defined metadata,
  "search" : a combined query
} 

For example, the following rule enables you to test whether a document or a set of documents matches the string query xdmp in a case-sensitive search.

<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>Example Rule</rapi:name>
  <search:search
      xmlns:search="http://marklogic.com/appservices/search">
    <search:qtext>xdmp</search:qtext>
    <search:options>
      <search:term>
        <search:term-option>case-sensitive</search:term-option>
      </search:term>
    </search:options>
  </search:search>
</rapi:rule>

You can include an optional description and metadata. This data is not used by MarkLogic Server, but it is returned in match results and when you fetch back a rule definition. The structure of the rule metadata is user-defined. The following example rule adds a description and an author to the above rule:

<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>Example Rule</rapi:name>
  <search:search
      xmlns:search="http://marklogic.com/appservices/search">
    <search:qtext>xdmp</search:qtext>
    <search:options>
      <search:term>
        <search:term-option>case-sensitive</search:term-option>
      </search:term>
    </search:options>
  </search:search>
  <rapi:description>An example rule.</rapi:description>
  <rapi:rule-metatdata>
    <author>me</author>
  </rapi:rule-metadata>
</rapi:rule>

The following example shows an equivalent rule expressed as JSON.

{ "rule": {
  "name" : "json-example",
  "search" : {
    "qtext" : "xdmp",
    "options" : {
      "term" : { "term-option" : "case-sensitive" }
    }
  },
  "description": "A JSON example rule.",
  "rule-metadata" : { "author" : "me" }
}}

If you insert metadata as JSON and retrieve it as XML, reference the XML metadata elements in the namespace http://marklogic.com/rest-api.

Installing an Alerting Rule

Before you can perform a match operation against an alerting rule, you must install the rule in your REST API instance. To persist a rule in your REST API instance, send a PUT request to the /alert/rules/{name} service with a URL of the following form. The request body must contain an XML or JSON rule definition of the form described in Defining an Alerting Rule.

http://host:port/version/alert/rules/name

Where name is the name of the rule. If you specify an explicit name in the rule definition, it must match name in the PUT request URI. If you do not specify an explicit name in the rule definition, MarkLogic Server adds a name corresponding to the name in the request URI.

The following example command installs a rule under the name example, assuming the file rule.xml contains the rule definition:

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X PUT -d @./rule.xml \
    -i -H "Content-type: application/xml" \
    'http://localhost:8000/LATEST/alert/rules/example'

To install a rule expressed as JSON, set the Content-type header to application/json or set the format request parameter to json. For example:

$ curl --anyauth --user user:password -X PUT -d @./rule.json \
    -i -H "Content-type: application/json" \
    'http://localhost:8000/LATEST/alert/rules/json-example'

Testing for Matches to Alerting Rules

Once you install alerting rules in your REST API instance, use the /alert/match service to determine which rules match one or more input documents. You can select the input documents using a database query or database URIs, or by passing a transient document.

This section covers the following topics:

• Basic Steps
• Identifying Input Documents Using a Query
• Identifying Input Documents Using URIs
• Matching Against a Transient Document
• Filtering Match Results
• Transforming Match Results

http://host:port/version/alert/match

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/xml" \
    'http://localhost:8000/LATEST/alert/match?uri=/example/doc.xml'

<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rule>rule definition</rapi:rule>
  <rapi:rule>rule definition</rapi:rule>
</rapi:rules>

{"rules": [
  {"rule": { rule definition },
  {"rule": { rule definition }
] }

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/xml" \
    'http://localhost:8000/LATEST/alert/match?options=my-options&q=cat AND dog'

$ cat match-body.xml
<search xmlns="http://marklogic.com/appservices/search">
  <qtext>xdmp</qtext>
  <options>
    <term>
      <term-option>case-sensitive</term-option>
    </term>
  </options>
</search>
$ curl --anyauth --user user:password -X POST -d @./match-body.xml \
    -i -H "Content-type: application/xml" \
    http://localhost:8000/LATEST/alert/match

$ cat match-body.json
{ "search" : {
    "qtext" : "xdmp",
    "options" : {
      "term" : { "term-option" : "case-sensitive" }
    }
}}
$ curl --anyauth --user user:password -X POST -d @./match-body.json \
    -i -H "Content-type: application/json" \
    http://localhost:8000/LATEST/alert/match

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/xml" \
    'http://localhost:8000/LATEST/alert/match?uri=/example/doc1.xml&uri=/example/doc2.xml'

$ cat > transient.xml
<function>
  <prefix>xdmp</prefix>
  <name>document-delete</name>
</function>
# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X POST \
    -i -H "Content-type: application/xml" -d @./transient.xml \
    'http://localhost:8000/LATEST/alert/match'

$ curl --anyauth --user user:password -X POST \
    -i -H "Content-type: application/json" -d @./transient.json \
    'http://localhost:8000/LATEST/alert/match'

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/xml" \
    'http://localhost:8000/LATEST/alert/match?uri=/example/doc.xml&rule=one&rule=two'
...
<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rule>
    <rapi:name>one</rapi:name>
    <rapi:description>Rule 1</rapi:description>
    <search:search
        xmlns:search="http://marklogic.com/appservices/search">
      <search:qtext>xdmp</search:qtext>
    </search:search>
  </rapi:rule>
</rapi/rules>

$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/json" \
    'http://localhost:8000/LATEST/alert/match?uri=/example/doc.xml&rule=one&rule=two'
...
{ "rules": [
    { "rule": {
        "name": "one",
        "description": "Rule 1",
        "search": { "qtext": ["xdmp"] }
    } }
] }

<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rule>
    <rapi:name>one</rapi:name>
    <rapi:description>Rule 1</rapi:description>
    <search:search
        xmlns:search="http://marklogic.com/appservices/search">
      <search:qtext>xdmp</search:qtext>
    </search:search>
  </rapi:rule>
</rapi/rules>

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/xml" \
    'http://localhost:8000/LATEST/alert/match?uri=/example/doc.xml&transform=my-alert-txfm&trans:my-param=value'

Retrieving Rule Definitions

You can retrieve the definition of all installed rules or the definition of a single installed rule identified by name.

To retrieve the definitions of all installed rules, send a GET request to the /alert/rules service with a URL of the following form:

http://host:port/version/alert/rules

To retrieve the definition of a single rule by name, send a GET request to the /alert/rules/{name} service with a URL of the following form:

http://host:port/version/alert/rules/{name}

Use the HTTP Accept header or the format request parameter to request results in either XML or JSON.

The following example command returns the definition of the rule named Rule1, in XML:

# Windows users, see Modifying the Example Commands for Windows 
$ curl --anyauth --user user:password -X GET \
    -i -H "Accept: application/xml" \
    'http://localhost:8000/LATEST/alert/rules/Rule1'
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>Rule1</rapi:name>
  <search:search
      xmlns:search="http://marklogic.com/appservices/search">
    <search:qtext>xdmp</search:qtext>
  </search:search>
</rapi:rule>

Testing for the Existence of Rule

To test for the existence of a particular rule without fetching back the defining, send a HEAD request to the /alert/rules/{name} service with a URL of the following form:

http://host:port/version/alert/rules/{name}

If the named rule exists, MarkLogic Server responds with status code 200 (OK). If no such rule exists, MarkLogic Server responds with status 404 (Not Found).

Deleting a Rule

To delete a previously installed rule, send a DELETE request to the /alert/rules/{name} service with a URL of the following form:

http://host:port/version/alert/rules/{name}