| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 6:00 AM | XQuery & XSLT Built-In & Modules Function Reference
Module: Alerting
The Alerting API function module is used to create alerting applications. The Alerting API abstracts the security considerations and the reverse search functionality from the developer. The Alerting API is installed as the following file: `install_dir/Modules/MarkLogic/alert.xqy` where `install_dir` is the directory in which MarkLogic Server is installed. To use the alert.xqy module in your own XQuery modules, include the following line in your XQuery prolog: `import module namespace alert = "http://marklogic.com/xdmp/alert" at "/MarkLogic/alert.xqy";` The library uses the `alert:` namespace, which is `not` predefined in the server. The Alerting API requires a valid alerting license key. Without a valid license key, the functions in the Alerting API will throw an exception. Additionally, a valid alerting license key is required to use the reverse index.
Function Summary
alert:action-get-description | This function returns the description of a given action.
alert:action-get-module | This function returns the module of a given action.
alert:action-get-module-db | This function returns the module database of a given action.
alert:action-get-module-root | This function returns the module root of a given action.
alert:action-get-name | This function returns the name of a given action.
alert:action-get-options | This function returns the options of a given action.
alert:action-insert | This function inserts the xml representing the action into the collection.
alert:action-remove | This function removes the named action from the database or throws an exception if the action does not exist.
alert:action-set-description | This function returns the action with the description of the action updated.
alert:action-set-module | This function returns the action with the module of the action updated.
alert:action-set-module-db | This function sets the module database of a given action.
alert:action-set-module-root | This function sets the module root of a given action.
alert:action-set-name | This function returns the action with the name of the action updated.
alert:action-set-options | This function returns the action with the options of the action updated.
alert:config-delete | Remove an alerting configuration identified by the specified URI.
alert:config-get | Gets the config associated with the specified URI.
alert:config-get-cpf-domain-names | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-get-description | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-get-id | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-get-name | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-get-options | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-get-trigger-ids | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-get-uri | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-insert | Inserts a config into the database.
alert:config-set-cpf-domain-names | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-set-description | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-set-name | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-set-options | This function provides convenient access to the specified sub-element within an alerting config.
alert:config-set-trigger-ids | This function provides convenient access to the specified sub-element within an alerting config.
alert:create-triggers | Create triggers that invoke the standard alerting trigger module.
alert:find-matching-rules | Returns a list of all rules associated with the specified config that match the specified document.
alert:get-actions | This function retrieves all the named actions in the specified config URI.
alert:get-all-rules | This function returns all rules visible to the current user.
alert:get-my-rules | This function returns all rules associated with the current user.
alert:invoke-matching-actions | Finds the rules that match the specified document and invokes their associated actions.
alert:make-action | This function creates the xml representing an action.
alert:make-config | Create an alerting configuration associated with a particular URI.
alert:make-log-action | Create a standard logging action named "log".
alert:make-rule | This function creates the XML representing a rule.
alert:remove-triggers | Remove triggers whose IDs are listed in the config.
alert:rule-action-query | This function creates a query to find rules with any of the specified actions.
alert:rule-get-action | This function returns the action of a given rule.
alert:rule-get-description | This function returns the description of a given rule.
alert:rule-get-id | This function returns the ID of a given rule.
alert:rule-get-name | This function returns the name of a given rule.
alert:rule-get-options | This function returns the options of a given rule.
alert:rule-get-query | Get the cts:query corresponding to the rule's query expression.
alert:rule-get-user-id | This function returns the user ID of a given rule.
alert:rule-id-query | This function creates a query to find rules with any of the specified IDs.
alert:rule-insert | This function inserts rule into the database associated with the specified alerting configuration.
alert:rule-name-query | This function creates a query to find rules with any of the specified names.
alert:rule-remove | This function removes the XML representing the rule from the collection.
alert:rule-set-action | This function returns the rule with the action updated.
alert:rule-set-description | This function returns the rule with the description of the rule updated.
alert:rule-set-name | This function returns the rule with the name of the rule updated.
alert:rule-set-options | This function returns the rule with the options of the rule updated.
alert:rule-set-query | Set the cts:query corresponding to the rule's query expression.
alert:rule-set-user-id | This function returns the rule with the user ID updated.
alert:rule-user-id-query | This function creates a query to find rules with any of the specified user IDs.
alert:spawn-matching-actions | Finds the rules that match the specified document and spawns their associated actions.
Function Detail
alert:action-get-description(
| $action as element(alert:action)
) as xs:string
Summary: This function returns the description of a given action.
Parameters:
$action : The XML representation of an action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-get-description($action)
      => "Sends basic SMS text message"
alert:action-get-module(
| $action as element(alert:action)
) as xs:string
Summary: This function returns the module of a given action.
Parameters:
$action : The XML representation of an action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action := alert:get-actions("my-alert-config-uri", "my-action")
      return
      alert:action-get-module($action)
      => /modules/sms.xqy (or whatever is the path to the module)
alert:action-get-module-db(
| $action as element(alert:action)
) as xs:unsignedLong
Summary: This function returns the module database of a given action.
Parameters:
$action : The XML representation of an action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action := alert:get-actions("my-alert-config-uri", "my-action")
      return
      alert:action-get-module-db($action)
alert:action-get-module-root(
| $action as element(alert:action)
) as xs:string
Summary: This function returns the module root of a given action.
Parameters:
$action : The XML representation of an action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action := alert:get-actions("my-alert-config-uri", "my-action")
      return
      alert:action-get-module-root($action)
alert:action-get-name(
| $action as element(alert:action)
) as xs:string
Summary: This function returns the name of a given action.
Parameters:
$action : The xml representation of an action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-get-name($action)
      => sms
alert:action-get-options(
| $action as element(alert:action)
) as element(alert:options)
Summary: This function returns the options of a given action.
Parameters:
$action : The XML representation of an action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-get-options($action)
      => <alert:options>
    	  <sms:provider name="Verizon" domain="vtext.com"/>
         </alert:options>
alert:action-insert(
| $collection-uri as xs:string,
| $action as element(alert:action)
) as empty-sequence()
Summary: This function inserts the xml representing the action into the collection. The caller must have the `alert-admin` privilege to call this function.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$action : The XML representation of an action.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-alert-admin`, `http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change` (if changing the modules database), `http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change-fs` (if changing the modules db to someplace on the filesystem)
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action := alert:make-action("")
      return alert:action-insert("http://acme.com/alert/message-board", $action)
      => Inserts the XML for the action into the database
alert:action-remove(
| $collection-uri as xs:string,
| $name as xs:string
) as empty-sequence()
Summary: This function removes the named action from the database or throws an exception if the action does not exist. The caller must have the `alert-admin` privilege to call this function.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$name : The name of the action to be removed.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-remove("http://acme.com/action/message-board", "sms")
      => Removes the action with name "sms" from the
         collection "http://acme.com/message-board"
alert:action-set-description(
| $action as element(alert:action),
| $description as xs:string
) as element(alert:action)
Summary: This function returns the action with the description of the action updated.
Parameters:
$action : The XML representation of an action.
$description : The description value to set for the given action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-set-description($action, "Sends basic SMS text message")
      => Returns the XML representation of the action with the
         description updated to "Sends basic SMS text message"
alert:action-set-module(
| $action as element(alert:action),
| $module as xs:string
) as element(alert:action)
Summary: This function returns the action with the module of the action updated.
Parameters:
$action : The XML representation of an action.
$module : The module value to set for the given action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-set-module($action, "/modules/sms.xqy")
      => Returns the XML representation of the action with the module
         updated to "/modules/sms.xqy"
alert:action-set-module-db(
| $action as element(alert:action),
| $module-db as xs:unsignedLong
) as element(alert:action)
Summary: This function sets the module database of a given action.
Parameters:
$action : The XML representation of an action.
$module-db : The ID of the database containing the module of the action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action := alert:get-actions("my-alert-config-uri", "my-action")
      return
      alert:action-set-module-db($action, xdmp:database("my-new-database"))
alert:action-set-module-root(
| $action as element(alert:action),
| $module-root as xs:string
) as element(alert:action)
Summary: This function sets the module root of a given action.
Parameters:
$action : The XML representation of an action.
$module-root : The new modules root for the action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action := alert:get-actions("my-alert-config-uri", "my-action")
      return
      alert:action-set-module-root($action, "/newroot/")
alert:action-set-name(
| $action as element(alert:action),
| $name as xs:string
) as element(alert:action)
Summary: This function returns the action with the name of the action updated.
Parameters:
$action : The xml representation of an action.
$name : The name value to set for the given action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-set-name($action, "sms")
      => Returns the XML representation of the action with the name updated to "sms"
alert:action-set-options(
| $action as element(alert:action),
| $options as element(alert:options)
) as element(alert:action)
Summary: This function returns the action with the options of the action updated.
Parameters:
$action : The XML representation of an action.
$options : The options to set for the given action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $action :=
        alert:action-set-options(
            $action,
    	<alert:options><sms:provider name="Verizon" domain="vtext.com"/>
    	</alert:options>
        )
        => Returns the XML representation of the action with the options
           updated to <alert:options>
    	             <myns:provider>Verizon</myns:provider>
    	          </alert:options>
alert:config-delete(
| $uri as xs:string
) as empty-sequence()
Summary: Remove an alerting configuration identified by the specified URI. If the config does not exist, an exception will be thrown. Any triggers associated with the alerting configuration will be automatically removed. Any actions and/or rules associated by the config will also be removed as well as the protected collection. The caller must have the alert-admin privilege to call this function.
Parameters:
$uri : The URI of the alerting config.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-delete("http://acme.com/alert/message-board")
alert:config-get(
| $uri as xs:string
) as element(alert:config)?
Summary: Gets the config associated with the specified URI. The user must have the alert-user privilege to call this function.
Parameters:
$uri : The URI of the alerting config.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get("http://acme.com/alert/message-board")
alert:config-get-cpf-domain-names(
| $config as element(alert:config)
) as xs:string*
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get-cpf-domain-names($config)
alert:config-get-description(
| $config as element(alert:config)
) as xs:string
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get-description($config)
alert:config-get-id(
| $config as element(alert:config)
) as xs:unsignedLong
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get-id($config)
alert:config-get-name(
| $config as element(alert:config)
) as xs:string
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get-name($config)
alert:config-get-options(
| $config as element(alert:config)
) as element(alert:options)
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get-options($config)
alert:config-get-trigger-ids(
| $config as element(alert:config)
) as xs:unsignedLong*
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $trigger-ids := alert:config-get-trigger-ids($config)
alert:config-get-uri(
| $config as element(alert:config)
) as xs:string
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-get-uri($config)
alert:config-insert(
| $config as element(alert:config)
) as empty-sequence()
Summary: Inserts a config into the database. If this is the first time the config has been inserted, a protected collection will be created for the config's URI. A user must have the alert-admin privilege to call this function.
Parameters:
$config : the config to insert
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $config := alert:make-config(...)
      return alert:config-insert($config)
alert:config-set-cpf-domain-names(
| $config as element(alert:config),
| $names as xs:string*
) as element(alert:config)
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
$names : The name(s) of the domains to use with this alerting config. The names must be valid domain names for the the database in which the alerting config references.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-set-cpf-domain-names($config, $domain-names)
alert:config-set-description(
| $config as element(alert:config),
| $description as xs:string
) as element(alert:config)
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
$description : The description of the specified configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-set-description($config, "The message board configuration")
alert:config-set-name(
| $config as element(alert:config),
| $name as xs:string
) as element(alert:config)
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration
$name : The name of the specified configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-set-name($config, "message-board")
alert:config-set-options(
| $config as element(alert:config),
| $options as element(alert:options)
) as element(alert:config)
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
$options : The options of the specified configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:config-set-options($config, <alert:options />)
alert:config-set-trigger-ids(
| $config as element(alert:config),
| $ids as xs:unsignedLong*
) as element(alert:config)
Summary: This function provides convenient access to the specified sub-element within an alerting config.
Parameters:
$config : The specified alerting configuration.
$ids : The trigger IDs of the specified configuration.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $ids := (xs:unsignedLong(123456789), xs:unsignedLong(987654321))
      return alert:config-set-trigger-ids($config, $ids)
alert:create-triggers(
| $uri as xs:string,
| $events as element(trgr:data-event)*
) as xs:unsignedLong*
Summary: Create triggers that invoke the standard alerting trigger module. The caller must have the `alert-admin` privilege. The returned trigger IDs must be associated with the config using `alert:config-set-trigger-ids` and then saving the updated config with `alert:config-insert`.
Parameters:
$uri : The URI specified to `alert:make-config`.
$events : Events for which to create triggers.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $uri := "http://acme.com/alert/message-board"
      let $trigger-ids :=
        alert:create-triggers (
            $uri,
            trgr:trigger-data-event(
                trgr:directory-scope("/", "infinity"),
                trgr:document-content(("create", "modify")),
                trgr:pre-commit())))
      let $config := alert:config-get($uri)
      let $new-config := alert:config-set-trigger-ids($config, $trigger-ids)
      return alert:config-insert($new-config)
alert:find-matching-rules(
| $config-uri as xs:string,
| $doc as node()
) as element(alert:rule)*
Summary: Returns a list of all rules associated with the specified config that match the specified document. You must have the `alert-admin` privilege to call this function.
Parameters:
$config-uri : The alerting configuration from which to match rules.
$doc : The document to match against.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:find-matching-rules("http://myconfig/uri/",
               fn:doc("/mydocs/doc.xml"))
alert:get-actions(
| $collection-uri as xs:string,
| $names as xs:string*
) as element(alert:action)*
Summary: This function retrieves all the named actions in the specified config URI. Returns a list of actions.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$names : The names of the actions to retrieve, possibly using wildcards.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-actions("http://acme.com/alert/message-board", ("sms", "email"))
      => Returns the XML representation of the actions for SMS and email
      alert:get-actions("http://acme.com/alert/message-board",("*"))
      => Returns all actions in the specified alerting configuration
alert:get-all-rules(
| $collection-uri as xs:string,
| $query as cts:query
) as element(alert:rule)*
Summary: This function returns all rules visible to the current user.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$query : The `cts:query` with which to restrict the rules that are returned.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-alert-user`
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-all-rules("my-collection", cts:word-query("my query"))
alert:get-my-rules(
| $collection-uri as xs:string,
| $query as cts:query
) as element(alert:rule)*
Summary: This function returns all rules associated with the current user.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$query : The `cts:query` with which to restrict the rules that are returned.
Required Privilege: `http://marklogic.com/xdmp/privileges/xdmp-alert-user`
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-my-rules("my-collection", cts:word-query("my query"))
alert:invoke-matching-actions(
| $config-uri as xs:string,
| $doc as node(),
| $options as node()
) as empty-sequence()
Summary: Finds the rules that match the specified document and invokes their associated actions. The actions will be invoked as the user who owns each rule. The caller can use options to control whether the actions run in the same or a different transaction.
Parameters:
$config-uri : The alerting configuration from which to match rules.
$doc : The document to match against.
$options : The options node to pass to `xdmp:invoke` when invoking each action. The options node should be in the `xdmp:eval` namespace.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:invoke-matching-actions("http://myconfig/uri/",
               fn:doc("/mydocs/doc.xml"), <options/>)
alert:make-action(
| $name as xs:string,
| $description as xs:string,
| $module-db as xs:unsignedLong,
| $module-root as xs:string,
| $module as xs:string,
| $options as element(alert:options)
) as element(alert:action)
Summary: This function creates the xml representing an action. When a rule associated with the action matches a document, the action's module will be invoked with the following external variables set:
    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;
All actions must accept these external variables.
Parameters:
$name : The name give to the action.
$description : A text description of the action.
$module-db : The database ID where the XQuery modules reside. Use `xdmp:module-database()` to specify the configured database.
$module-root : The path to the module root. Use `xdmp:module-root()` to specify the configured root.
$module : The URI of the module to invoke.
$options : Optional information specific to the action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:make-action(
        "sms",
        "Sends basic SMS text message",
        xdmp:modules-database(),
        xdmp:modules-root(),
        "/modules/sms.xqy",
        <alert:options>
            <provider name="T-Mobile" domain="tmomail.net"/>
            <provider name="Virgin" domain="vmobl.com"/>
            <provider name="Cingular" domain="cingularme.com"/>
            <provider name="Sprint" domain="messaging.sprintpcs.com"/>
            <provider name="Verizon" domain="vtext.com"/>
            <provider name="Nextel" domain="messaging-nextel.com"/>
        </alert:options>
      )
      => Returns the XML representing an action with the specified information
alert:make-config(
| $uri as xs:string,
| $name as xs:string,
| $description as xs:string,
| $options as element(alert:options)
) as element(alert:config)
Summary: Create an alerting configuration associated with a particular URI. The URI will be used to create a protected collection when the config is inserted into the database with `alert:config-insert`. This URI will also be used as a directory for all documents (config, actions, and rules) associated with the config.
Parameters:
$uri : The URI for this alerting config.
$name : The name for this alerting config.
$description : A description for this alerting config.
$options : Additional options available to an alerting application for extra state.
Required Privilege: The `alert-admin` role is required to run this function (or all of the privileges in the `alert-admin` role).
Usage Notes: If you add the `<alert:unfiltered>true</alert:unfiltered>` option to the `$options` parameter, it will cause all `cts:search` operations that use this config to run unfiltered. This applies to the functions in the Alerting API that use `cts:search` (for example, `alert:find-matching rules`). The default is for them to run filtered. Unfiltered searches skip the filtering stage of query processing, relying on the index resolution for the accuracy of the results. The unfiltered option can give a performance boost to configurations whose index settings do not require results to be filtered.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:make-config(
    	 "http://acme.com/alert/message-board",
            "Message Board",
            "Alerting config for messages on the message board",
            <alert:options/>
        )
alert:make-log-action( ) as element(alert:action)
Summary: Create a standard logging action named "log". Rules that reference this action must provide an `<alert:directory/>` element that specifies where the log file should be created. The inserted document will have a random long integer ID and its filename will be ID.xml within the specified directory. Rules that reference this action may also provide options with an `<alert:permissions>` element containing a series of `<sec:permission>` elements and/or an `<alert:collections>` element containing `<alert:collection>` elements that specify the permissions and collections for the log document. This information is simply passed through to `xdmp:document-insert`. An example of the rule's options is as follows:
    <alert:options>
      <alert:directory>/some/directory</alert:directory>
      <alert:permissions>
        <sec:permission>
          <sec:capability>read</sec:capability>
          <sec:role-id>129382323</sec:role-id>
        </sec:permission>
      </alert:permissions>
      <alert:collections>
        <alert:collection>http://acme.com/alert-log</alert:collection>
      </alert:collections>
    </alert:options>

    The log document has the following structure:

    <alert:log>
      <alert:log-id>82388423</alert:log-id>
      <alert:config-uri>http://acme.com/alert/message-board</alert:config-uri>
      <alert:rule-id>12352</alert:rule-id>
      <alert:user-id>8271938239</alert:user-id>
      <alert:document-uri>/the/URI/of/the/matching/document</alert:document-uri>
      <alert:timestamp>2008-05-31T08:20:00-08:00</alert:timestamp>
    </alert:log>

    The log document insertion will be performed as the user who created
    the rule, and the user must have permission to create documents in any
    collections they specify. The log-id is a random number chosen by
    the action.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:action-insert(alert:make-log-action())
alert:make-rule(
| $name as xs:string,
| $description as xs:string,
| $user-id as xs:unsignedLong,
| $query as cts:query,
| $action as xs:string,
| $options as element(alert:options)
) as element(alert:rule)
Summary: This function creates the XML representing a rule. If the caller does not have the `alert-admin` privilege then `$user-id` must be the ID of the current user from the security database. If `$user-id` is 0, it will be automatically replaced with the current user's ID.
Parameters:
$name : The name given to the rule.
$description : A text description of the rule.
$user-id : The user ID from the security database of the user who will be notified of matches.
$query : The query that the rule will be matched against for alerting.
$action : The name of the action to occur upon the matching of the rule.
$options : Information specific to the application for the rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:make-rule(
        "nucleic acids email",
        "Alert me to anything concerning nucleic acids",
        0,
        cts:or-query((
            cts:word-query("dna"),
            cts:word-query("rna")
           )),
        "email",
        <alert:options>
            <alert:email-address>me@somedomain.com</alert:email-address>
        </alert:options>
      )
alert:remove-triggers(
| $uri as xs:string
) as empty-sequence()
Summary: Remove triggers whose IDs are listed in the config. The caller must have the alert-admin privilege. This function writes the updated configuration to the database, so if you need to delete the configuration as well (using `admin:delete-config`, for example), you should do so in another transaction.
Parameters:
$uri : The URI specified to `alert:make-config`.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:remove-triggers("http://acme.com/alert/message-board")
alert:rule-action-query(
| $actions as xs:string*
) as cts:query
Summary: This function creates a query to find rules with any of the specified actions. Returns a query to be passed to `alert:get-my-rules` or `alert:get-all-rules`.
Parameters:
$actions : A list of action names for the rules to be retrieved.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-all-rules("my-alert-config",
    	  alert:rule-action-query(("email", "sms")))
      =>Returns the rules with actions "email" and "sms"
alert:rule-get-action(
| $rule as element(alert:rule)
) as xs:string
Summary: This function returns the action of a given rule.
Parameters:
$rule : The XML representation of a rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-get-action($rule)
      => sms
alert:rule-get-description(
| $rule as element(alert:rule)
) as xs:string
Summary: This function returns the description of a given rule.
Parameters:
$rule : The XML representation of a rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-get-description($rule)
      => "Email when new article about DNA"
alert:rule-get-id(
| $rule as element(alert:rule)
) as xs:unsignedLong
Summary: This function returns the ID of a given rule.
Parameters:
$rule : The XML representation of a rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-get-id($rule)
      => 4363547345
alert:rule-get-name(
| $rule as element(alert:rule)
) as xs:string
Summary: This function returns the name of a given rule.
Parameters:
$rule : The XML representation of a rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-get-name($rule)
      => "nucleic acids email"
alert:rule-get-options(
| $rule as element(alert:rule)
) as element(alert:options)
Summary: This function returns the options of a given rule.
Parameters:
$rule : The XML representation of the rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-get-options($rule)
      => <alert:options>
           <alert:email-address>me@somedomain.com</alert:email-address>
         </alert:options>
alert:rule-get-query(
| $rule as element(alert:rule)
) as cts:query
Summary: Get the `cts:query` corresponding to the rule's query expression.
Parameters:
$rule : The XML representation of the rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";
alert:rule-get-user-id(
| $rule as element(alert:rule)
) as xs:unsignedLong
Summary: This function returns the user ID of a given rule.
Parameters:
$rule : The XML representation of a rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-get-user-id($rule)
      => 123456789
alert:rule-id-query(
| $ids as xs:unsignedLong*
) as cts:query
Summary: This function creates a query to find rules with any of the specified IDs. Returns a query to be passed to `alert:get-my-rules` or `alert:get-all-rules`.
Parameters:
$ids : A list of IDs for the rules to be retrieved.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-my-rules(alert:rule-id-query((987654321, 987654322)))
      =>Returns the rules with IDs 987654321 and 987654322
alert:rule-insert(
| $collection-uri as xs:string,
| $rule as element(alert:rule)
) as empty-sequence()
Summary: This function inserts rule into the database associated with the specified alerting configuration. A user must have the alert-user privilege to call this function.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$rule : The XML representation of a rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      let $rule := alert:make-rule("")
      return alert:rule-insert("http://acme.com/alert/message-board", $rule)
alert:rule-name-query(
| $names as xs:string*
) as cts:query
Summary: This function creates a query to find rules with any of the specified names. Returns a query to be passed to `alert:get-my-rules` or `alert:get-all-rules`.
Parameters:
$names : A list of names for the rules to be retrieved.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-all-rules("my-alert-config",
    	  alert:rule-name-query(("dna-alert", "rna-alert")))
      =>Returns the rules with names "dna-alert" or "rna-alert"
alert:rule-remove(
| $collection-uri as xs:string,
| $id as xs:unsignedLong
) as empty-sequence()
Summary: This function removes the XML representing the rule from the collection. A user must have the `alert-user` privilege to call this function. An exception is thrown if the rule does not exist. A user must have the `alert-admin` privilege to delete other users' rules.
Parameters:
$collection-uri : The URI passed to `alert:make-config`.
$id : The ID of the rule to be removed.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-remove("http://acme.com/alert/message-board", 987654321)
alert:rule-set-action(
| $rule as element(alert:rule),
| $action as xs:string
) as element(alert:rule)
Summary: This function returns the rule with the action updated.
Parameters:
$rule : The XML representation of a rule.
$action : The action value to set for the given rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-set-action($rule, "sms")
      => Returns the XML representation of the rule with the new action
      updated to "sms"
alert:rule-set-description(
| $rule as element(alert:rule),
| $description as xs:string
) as element(alert:rule)
Summary: This function returns the rule with the description of the rule updated.
Parameters:
$rule : The XML representation of a rule.
$description : The description value to set for the given rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-set-description($rule, "Email when new article about DNA")
      => Returns the XML representation of the rule with the description
         updated to "Email when new article about DNA"
alert:rule-set-name(
| $rule as element(alert:rule),
| $name as xs:string
) as element(alert:rule)
Summary: This function returns the rule with the name of the rule updated.
Parameters:
$rule : The XML representation of a rule.
$name : The name value to set for the given rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-set-name($rule, "nucleic acids email")
      => Returns the XML representation of the rule with the name updated
      to "nucleic acids email"
alert:rule-set-options(
| $rule as element(alert:rule),
| $options as element(alert:options)
) as element(alert:rule)
Summary: This function returns the rule with the options of the rule updated.
Parameters:
$rule : The XML representation of the rule.
$options : The options to set for the given rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-set-options(
      $rule,
      <alert:options>
        <alert:email-address>me@somedomain.com</alert:email-address>
      </alert:options>)
      => Returns the XML representation of the rule with the options
      updated to <alert:options>
    	       <myns:title>Nucleic Acids Alert</myns:title>
                 </alert:options>
alert:rule-set-query(
| $rule as element(alert:rule),
| $query as cts:query
) as element(alert:rule)
Summary: Set the cts:query corresponding to the rule's query expression.
Parameters:
$rule : The XML representation of the rule.
$query : The serialized version of the query for documents to match on.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";
alert:rule-set-user-id(
| $rule as element(alert:rule),
| $user-id as xs:unsignedLong
) as element(alert:rule)
Summary: This function returns the rule with the user ID updated. If the caller does not have the `alert-config` privilege, an exception will be thrown if the caller attempts to save a rule for a user other than himself.
Parameters:
$rule : The XML representation of a rule.
$user-id : The user ID value to set for the given rule.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:rule-set-user-id($rule, 123456789)
      => Returns the XML representation of the rule with the
         new user ID updated to 123456789
alert:rule-user-id-query(
| $user-ids as xs:unsignedLong*
) as cts:query
Summary: This function creates a query to find rules with any of the specified user IDs. Returns a query to be passed to `alert:get-my-rules` or `alert:get-all-rules`.
Parameters:
$user-ids : A list of user IDs for the rules to be retrieved.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:get-all-rules("my-alert-config",
    	  alert:rule-user-id-query((192837465, 192837466)))
      =>Returns the rules with user IDs 192837465 or 192837466
alert:spawn-matching-actions(
| $config-uri as xs:string,
| $doc as node(),
| $options as node()
) as empty-sequence()
Summary: Finds the rules that match the specified document and spawns their associated actions. The spawned tasks will run as the user that owns the rule.
Parameters:
$config-uri : The alerting configuration from which to match rules.
$doc : The document to match against.
$options : The options mode to pass to `xdmp:spawn` when spawning each action. The options node should be in the `xdmp:eval` namespace.
Example:
      xquery version "1.0-ml";
      import module namespace alert = "http://marklogic.com/xdmp/alert"
    		  at "/MarkLogic/alert.xqy";

      alert:spawn-matching-actions("http://myconfig/uri/",
               fn:doc("/mydocs/doc.xml"), <options xmlns="xdmp:eval"/>)

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.