MarkLogic Server 11.0 Product DocumentationREST Application Developer's Guide — Chapter 7
Alerting
The following topics are covered:
- Summary of /alert Services
- Alerting Pre-Requisites
- Alerting Concepts
- Defining an Alerting Rule
- Installing an Alerting Rule
- Testing for Matches to Alerting Rules
- Retrieving Rule Definitions
- Testing for the Existence of Rule
- Deleting a Rule
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.
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
Basic Steps
To test one or more documents for a match against the rules, send a GET or POST request to the /alert/match service with a URL of the following form:
http://host:port/version/alert/match
The following example command returns all rules that match the document with the URI /example/doc.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/match?uri=/example/doc.xml'
You must use one of the following methods to select the document(s) to test for a match:
- Query: Use a string, structured, or combined query to select documents in the database. For details, see Identifying Input Documents Using a Query. Use one of the following forms of request:
GET http://host:port/version/alert/match?q=q1&structuredQuery=q2&options=query-optionsPOST http://host:port/version/alert/match (post body contains a combined query)
- URI: Use one or more document URIs to select documents in the database. For details, see Identifying Input Documents Using URIs. Use a request of the following form:
GET http://host:port/version/alert/match?uri=document-uri
- Content: Supply a transient document in the request body instead of using documents in the database. For details, see Matching Against a Transient Document. Use a request of the following form:
POST http://host:port/version/alert/match (request body contains an XML document)
The response is a rules object that contains the definition of every rule that matches at least one of the input documents. You can request output in either XML or JSON using the HTTP Accept header. The data in the response body has the following form:
For the structure of a rule definition, see Defining an Alerting Rule.
The results do not indicate which input documents match each rule. If you need to know this, you should match against one document at a time.
Identifying Input Documents Using a Query
To use a query to select the documents to test for rule matches, do one of the following:
- Make a GET request that includes a string query in the
qrequest parameter and/or a structured query in thestructuredQueryrequest parameter. If you include both, the two queries are AND'd together. - Make a POST request that includes a combined query in the request body.
The syntax and semantics of the queries are the same as when making a GET or POST request to the /search service. For details, see Querying Documents and Metadata and Specifying Dynamic Query Options with Combined Query.
The following example GET request uses a string query to select all documents that contain the search terms cat and dog. The search is performed using the persistent query options stored under the name my-options.
# 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'
The following example POST request uses a combined query to perform a similar match. Note that query options can be defined at request time when you use a combined query.
$ 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/matchTo express the combined query in JSON, use a query and command similar to the following:
$ 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/matchIdentifying Input Documents Using URIs
To specify the input documents for an alert match using URIs, include one or more uri request parameters in a GET request to /alert/match. Each URI must identify a document, not a database directory.
The following example command tests the documents /example/doc1.xml and /example/doc2.xml for rule matches.
# 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'
Matching Against a Transient Document
You can test for rules matches against a document that is not stored in the database by making a POST request to /alert/match with the document in the request body.
The following example command tests which rules match the content in the local file transient.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'
You can use either an XML or JSON document as input. The following example command use JSON input:
$ curl --anyauth --user user:password -X POST \ -i -H "Content-type: application/json" -d @./transient.json \ 'http://localhost:8000/LATEST/alert/match'
Filtering Match Results
By default, the response to an alert match includes all matching rules. Use the rule request parameter to limit the results to a subset of the matching rules. For example, the response to the following command will include at most the definition of the rules named one and two, even if more rules match the input document.
# 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>
The following is the equivalent command using JSON output.
$ 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"] } } } ] }
Transforming Match Results
You can make arbitrary changes to the response from match request by applying a user-defined XQuery transformation function to the response. This section covers the following topics:
Writing a Match Result Transform
Alert match transforms use the same interface and framework as content transformations applied during document ingestion, described in Working With Content Transformations.
Your transform function receives the raw XML match result data as input, such as a document with a <rapid:rules/> root element. For example:
<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>
If your function produces XML output and the client application requested JSON output, MarkLogic Server will transform your output to JSON only if one of the following conditions are met.
- Your function produces an XML document that conforms to the normal output from the search operation. For example, a document with a
<rapi:rules/>root element whose contents are changed in a way that preserves the normal structure. - Your function produces an XML document with a root element in the namespace
http://marklogic.com/xdmp/json/basicthat can be transformed byjson:transform-to-json.
Under all other circumstances, the response body contains exactly the output returned by your transform function.
Using a Match Result Transform
Follow this procedure to apply a transformation:
- Create a transform function according to the interface described in Writing Transformations.
- Install your transform function on the REST API instance following the instructions in Installing Transformations.
- Apply your transform to a request to the
/alert/matchservice by specifying the name in thetransformrequest parameter, as described in Applying Transformations.
If the transform function expects additional parameters, specify them by name using trans:{name} request parameters.
The following example command performs an alert match using the document with URI /example/doc.xml as input. The match results are transformed by calling the XQuery transform function installed with the name my-alert-txfm. A single parameter named my-param is passed into the transform function.
# 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}