This page was generated
January  28,  2016
4:07  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Client API - Alerting Functions

Use the /alert service to do the following:
  • Install rules that describe characteristics of documents you want to identify in the future.
  • Poll for new database content that matches pre-installed rules.
  • Test a transient document that is not stored in the database for matches against your pre-defined rules.

This feature relies on reverse queries and the MarkLogic Server Alerting API, so it requires a valid alerting license key.

When you use a query to identify documents to test against your rules, you should either define a query that matches only a small number of documents, or use the start and pageLength request parameters of /alert/match to limit the number of documents considered.

For details, see 'Alerting' in the REST Application Developer's Guide.

REST Resource Summary
GET /v1/alert/match Retrieve a list of rules (including the rule metadata) that match documents identified by a query or a list of URIs.
POST /v1/alert/match Retrieve a list of rules (including the rule metadata) that match either documents in the database identified by a document selection query defined in the request body or a transient document supplied in the request body.
GET /v1/alert/rules Retrieve the definition of all alert rules previously installed in this REST API instance using the /v1/alert/{name} service.
DELETE /v1/alert/rules/{name} Delete an alerting rule previously installed using PUT /v1/alert/rules/{name}.
GET /v1/alert/rules/{name} Retrieve the alerting rule definition installed with the given name.
HEAD /v1/alert/rules/{name} Test for the existence of a rule with the given name.
PUT /v1/alert/rules/{name} Install an alerting rule under the given name.
REST Resource Detail
GET /v1/alert/match
Summary:

Retrieve a list of rules (including the rule metadata) that match documents identified by a query or a list of URIs.

Parameters:
format? : The expected content type of the results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml.
uri* : Specifies the URI of a document to check for rule matches. This parameter can be specified mutiple times. You cannot use this parameter with the q or structuredQuery parameters. For details, see 'Identifying Input Documents Using URIs' in the REST Application Developer's Guide.
q? : A string query. For details, see 'Identifying Input Documents Using a Query' in the REST Application Developer's Guide. You cannot use this parameter with the uri parameter.
structuredQuery? : A structured query with which to select documents to compare to the rules. The query must be a serialized representation of a search:query element or a JSON equivalent. For details, see 'Identifying Input Documents Using a Query' in the REST Application Developer's Guide. You cannot use this parameter with the uri parameter.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service.
rule* : The name of an alerting rule previously installed using PUT /v1/alert/rules/{name}. This options may be given multiple times. If no rule is supplied, all installed rules are considered.
start? : The index of the first result returned by the document selection query to be considered when matching rules. This parameter and the pageLength parameter are used to limit the document search exactly as with /search, prior to applying search matches. Default: 1. You cannot use this parameter with the uri parameter.
pageLength? : The maximum number of documents to return from the document selection query. This parameter and the start parameter limit the document selection query results exactly as with /search. This limits the number of documents tested for rule matches. Default: 10, or the length configured by the query options. You cannot use this parameter with the uri parameter.

Request Headers:
Accept*: The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader


Response:

Upon success, MarkLogic Server returns a status 200 and a list of matching rules in the request body. For rule definition syntax, see 'Defining an Alerting Rule' in the REST Application Developer's Guide.

Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

For best performance, enable "fast reverse searches" on the database. Also, if selecting documents using a query, the query should either return a small number of documents or the number of results returned by the query should be limited using the start and/or pageLength request parameters.

Select the documents to consider for rule matches either by specifying a document selection query using the q and/or structuredQuery parameters, or by specifying one or more document URIs using the uri parameter. Additional methods are available using POST /v1/alerts/match. If you specify both a string query and a structured query, they are AND'd together to form the final search query.

When the set of documents to check for rule matches is determined by a query, you can specify query options using the options parameter. The options must have been previously installed using the /config/query service.

To specify a query in the request body instead of using request parameters, or to specify query options without pre-installing them, use POST /v1/alerts/match.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

For details, see 'Testing for Matches to Alerting Rules' in the REST Application Developer's Guide and 'Creating Alerting Applications' in the Search Developer's Guide.


Example:
$ curl --anyauth --user admin:adm1n -X GET -i -H "Accept: application/xml" \
    'http://localhost:8003/v1/alert/match?q=xdmp AND load'

==> The definitions of any rules matching the documents selected by
    the string query "xdmp AND load". MarkLogic Server responds with
    output similar to the following:

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 1033
Connection: Keep-Alive
Keep-Alive: timeout=5

<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rule>
    <rapi:name>example</rapi:name>
    <rapi:description>An example rule.</rapi:description>
    <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-metadata>
      <author>me</author>
    </rapi:rule-metadata>
  </rapi:rule>
</rapi:rules>
  
Example:
$ curl --anyauth --user admin:adm1n -X GET -i -H "Accept: application/json" \
    'http://localhost:8003/v1/alert/match?q=xdmp AND load'

==> The definitions of any rules matching the documents selected by
    the string query "xdmp AND load". MarkLogic Server responds with
    output similar to the following:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 378
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "rules": [
    { "rule": {
        "name": "example",
        "description": "An example rule.",
        "search": {
          "qtext": [ "xdmp" ],
          "options": {
            "term": { "term-option": [ "case-sensitive" ] }
          }
        },
        "rule-metadata": {
          "author": "me"
        }
    } }
] }
  

POST /v1/alert/match
Summary:

Retrieve a list of rules (including the rule metadata) that match either documents in the database identified by a document selection query defined in the request body or a transient document supplied in the request body.

Parameters:
format? : The expected content type of the results. This is equivalent to specifying the MIME type in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml.
options? : The name of query options previously created via a PUT or POST request to the /v1/config/query service. You can only use this parameter if the request body contains a structured or combined query.
start? : The index of the first result returned by the document selection query to be considered when matching rules. This parameter and the pageLength parameter are used to limit the document search exactly as with /search, prior to applying search matches. Default: 1. You can only use this parameter if the request body contains a structured or combined query.
pageLength? : The maximum number of documents to return from the document selection query. This parameter and the start parameter limit the document selection query results exactly as with /search. This limits the number of documents tested for rule matches. Default: 10, or the length configured by the query options. You can only use this parameter if the request body contains a structured or combined query.

Request Headers:
Accept*: The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.
Content-Type: The MIME type of the data in the POST body. Accepted values: application/json or application/XML.

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader


Response:

Upon success, MarkLogic Server returns a status 200 and a list of matching rules in the request body. The response body contains XML or JSON rule definitions.

Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

For best performance, enable "fast reverse searches" on the database. Also, if selecting documents using a query, the query should either return a small number of documents or the number of results returned by the query should be limited using the start and/or pageLength request parameters.

Select the documents to consider for rule matches either by specifying a document selection query in the request body, or by supplying a single transient document in the request body. The latter allows you compare a document to stored rules before inserting it into the database. For other forms of rule matching, use GET /v1/alert/match.

To select documents using a query, construct a request body containing either a structured query (search:query) or a combined query and options (search:search), as described in POST /v1/search. You can specify document selection query using either JSON or XML; set the Content-Type header appropriately.

When the set of documents to check for rule matches is determined by a query, you can use the start and pageLength parameters to constrain the query results to compare to the rules.

To test a transient document for rule matches, supply an XML or JSON document in the request body and set the Content-Type header to either application/xml or application/json.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

For details, see 'Testing for Matches to Alerting Rules' in the REST Application Developer's Guide and 'Creating Alerting Applications' in the Search Developer's Guide.


Example:
$ cat match-body.xml
<search xmlns="http://marklogic.com/appservices/search">
  <qtext>load</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" -H "Accept: application/xml" \
    'http://localhost:8003/v1/alert/match

==> The definitions of rules that match the documents selected by the
    combined query in the request body. MarkLogic Server responds with
    output similar to the following.

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 1033
Connection: Keep-Alive
Keep-Alive: timeout=5

<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rule>
    <rapi:name>example</rapi:name>
    <rapi:description>An example rule.</rapi:description>
    <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-metadata>
      <author>me</author>
    </rapi:rule-metadata>
  </rapi:rule>
</rapi:rules>
  
Example:
$ cat ./transient.xml
<function>
  <prefix>xdmp</prefix>
  <name>document-delete</name>
</function>

$ curl --anyauth --user user:password -X POST -d @./match-body.xml -i \
    -H "Content-type: application/xml" -H "Accept: application/xml" \
    'http://localhost:8003/v1/alert/match

==> The definitions of rules that match the transient XML document in
    the request body. The results are as JSON, as indicated by the
    Accept header.  MarkLogic Server responds with output similar to the 
    following.

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 378
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "rules": [
    { "rule": {
        "name": "example",
        "description": "An example rule.",
        "search": {
          "qtext": [ "xdmp" ],
          "options": {
            "term": { "term-option": [ "case-sensitive" ] }
          }
        },
        "rule-metadata": {
          "author": "me"
        }
    } }
] }
  

GET /v1/alert/rules
Summary:

Retrieve the definition of all alert rules previously installed in this REST API instance using the /v1/alert/{name} service.

Parameters:
format? : The expected content type of the results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted values: xml and json. Default: xml.

Request Headers:
Accept*: The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader


Response:

On success, MarkLogic Server responds with a 200 status. The data in the response body is definitions of all installed rules. Results can be returned as either XML or JSON, depending up on the format request parameter or the Accept header setting. For details on the format of rule definitions, see 'Defining an Alerting Rule' in the REST Application Developer's Guide.

If the Alerting API is not enabled, MarkLogic Server returns status 403.


Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.


Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/xml" \
    'http://localhost:8003/v1/alert/rules'

==> The definitions of all installed rules, as XML. MarkLogic Server
    responds with output similar to the following:

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 542
Connection: Keep-Alive
Keep-Alive: timeout=5

<rapi:rules xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:rule>
    <rapi:name>example</rapi:name>
    <rapi:description>An example rule.</rapi:description>
    <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-metadata>
      <author>me</author>
    </rapi:rule-metadata>
  </rapi:rule>
</rapi:rules>
  
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
    'http://localhost:8003/v1/alert/rules'

==> The definitions of all installed rules, as JSON. MarkLogic Server
    responds with output similar to the following:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 190
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "rules": [
    { "rule": {
        "name": "example",
        "description": "An example rule.",
        "search": {
          "qtext": [ "xdmp" ],
          "options": {
            "term": { "term-option": [ "case-sensitive" ] }
          }
        },
        "rule-metadata": { "author": "me" }
    } }
] }
  

DELETE /v1/alert/rules/{name}
Summary:

Delete an alerting rule previously installed using PUT /v1/alert/rules/{name}.

Required Privilege:

This operation requires the rest-writer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-writer


Response:

MarkLogic Server responds with status 204 (Deleted), even if there is no rule installed with the given name.

If the Alerting API is not enabled, MarkLogic Server returns status 403.


Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

For details, see 'Alerting' in the REST Application Developer's Guide and 'Creating Alerting Applications' in the Search Developer's Guide.


Example:
$ curl --anyauth --user user:password -X DELETE -i \
    'http://localhost:8003/v1/alert/rules/example'

==> The rule installed under the name "example" is deleted. MarkLogic
    Server responds with output similar to the following:

HTTP/1.1 204 Deleted
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
  

GET /v1/alert/rules/{name}
Summary:

Retrieve the alerting rule definition installed with the given name.

Parameters:
format? : The expected content type of the results. This is equivalent to specifying the format in the Accept header. The format parameter overrides the Accept header if both are present. Accepted value: xml and json. Default: xml.

Request Headers:
Accept*: The expected MIME type of the information in the response. Accepted types: application/json or application/xml. Ignored if the request includes a format parameter value.

Response Headers:
Content-type: The MIME type of the data in the response, either application/json or application/xml, depending upon the MIME type requested through the format parameter or Accept header on the request.

Required Privilege:

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader


Response:

On success, MarkLogic Server responds with a 200 status and the requested rule definition in the response body. Results are returned as either XML or JSON, depending up on the format request parameter or the Accept header setting.

If no rule matching {name} is installed, MarkLogic Server returns status code 404.

If the Alerting API is not enabled, MarkLogic Server returns status 403.


Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

The expected response type can be specified using either the format parameter or Accept header. One or the other must be supplied. If both are supplied and are different, the format parameter takes precedence.

For more information on the alerting features of the REST API, see 'Alerting' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/xml" \
    http://localhost:8003/v1/alert/rules/example

==> The definition of the rule installed under the name "example", in XML.
    MarkLogic Server responds with output similar to the following:

HTTP/1.1 200 OK
Content-type: application/xml; charset=utf-8
Server: MarkLogic
Content-Length: 499
Connection: Keep-Alive
Keep-Alive: timeout=5

<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>example</rapi:name>
  <rapi:description>An example rule.</rapi:description>
  <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-metadata>
    <author>me</author>
  </rapi:rule-metadata>
</rapi:rule>
  
Example:
$ curl --anyauth --user user:password -X GET -i -H "Accept: application/json" \
    http://localhost:8003/v1/alert/rules/example

==> The definition of the rule installed under the name "example", in JSON.
    MarkLogic Server responds with output similar to the following:

HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
Server: MarkLogic
Content-Length: 178
Connection: Keep-Alive
Keep-Alive: timeout=5

{ "rule": {
    "name": "example",
    "description": "An example rule.",
    "search": {
      "qtext": [ "xdmp" ],
      "options": {
        "term": { "term-option": [ "case-sensitive" ] }
      }
    },
    "rule-metadata": { "author": "me" }
} }
  

HEAD /v1/alert/rules/{name}
Summary:

Test for the existence of a rule with the given name.

Required Privilege:

This operation requires the rest-writer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-writer


Response:

If a rule with the given name was previously installed using PUT /v1/alert/rules/{name}, MarkLogic Server returns status 200. If no such rule exists, status 404 is returned.

If the Alerting API is not enabled, MarkLogic Server returns status 403.


Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

For more information, see 'Alerting' in the REST Application Developer's Guide.


Example:
$ curl --anyauth --user user:password -X HEAD -i \
    'http://localhost:8003/v1/alert/rules/json-example'

==> If the rule exists, MarkLogic Server responds with status code 200.
    If the rule does not exist, MarkLogic Server responds with status 404.
    A unsuccessful test returns output similar to the following:

HTTP/1.1 404 Not Found
Content-type: application/xml
Server: MarkLogic
Content-Length: 365
Connection: Keep-Alive
Keep-Alive: timeout=5

<rapi:error xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:status-code>404</rapi:status-code>
  <rapi:status>Not Found</rapi:status>
  <rapi:message-code>RESTAPI-NODOCUMENT</rapi:message-code>
  <rapi:message>RESTAPI-NODOCUMENT: (err:FOER0000) Resource or document 
   does not exist:  category: alert-rules message: Rule named 'example' 
   not found
  </rapi:message>
</rapi:error>
  

PUT /v1/alert/rules/{name}
Summary:

Install an alerting rule under the given name.

Parameters:
format? : The content type of the data in the request body. Specifying a format overrides the Content-Type request header value.

Request Headers:
Content-type: The MIME type of the data in the request body, either application/json or application/xml. If the format request parameter is given, it takes precedence over this header.

Required Privilege:

This operation requires the rest-writer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-writer


Response:

Upon success, MarkLogic Server returns status 201 (Created) or 204 (Updated), depending on whether or not the named rule already exists.

If the payload is invalid, MarkLogic Server responds with status 400 by default. If no rule matching {name} is installed, MarkLogic Server returns status code 404.

If the Alerting API is not enabled, MarkLogic Server returns status 403.


Usage Notes:

Alerting applications require a valid alerting license key. The license key is required to use the reverse index and to use the Alerting API.

After installing one or more rules, use the /alert/match service to poll for documents that match rules. This allows you to create an alerting application using a pull model. To use a push model, you must use an XQuery implementation in MarkLogic Server, as described in 'Creating Alerting Applications' in the Search Developer's Guide.

For more information, see 'Defining an Alerting Rule' in the REST Application Developer's Guide.


Example:
  
Example:
$ cat ./rule.xml
<rapi:rule xmlns:rapi="http://marklogic.com/rest-api">
  <rapi:name>example</rapi:name>
  <rapi:description>An example rule.</rapi:description>
  <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-metadata>
    <author>me</author>
  </rapi:rule-metadata>
</rapi:rule>

$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/alert/rules/example

==> The rule defined in the file ./rule.xml is installed under the
    name "example". MarkLogic Server responds with output similar
    to the following:

HTTP/1.1 204 Updated
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5
  
Example:
$ curl --anyauth --user user:password -X PUT -d @./rule.xml -i \
    -H "Content-type: application/xml" \
    http://localhost:8003/v1/alert/rules/json-example

==> The rule defined in the file ./rule.xml is installed under the
    name "example". MarkLogic Server responds with output similar
    to the following:

HTTP/1.1 201 Created
Location:
Server: MarkLogic
Content-Length: 0
Connection: Keep-Alive
Keep-Alive: timeout=5

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