<apidoc:module name="AlertModule" category="Alerting" lib="alert" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc" xmlns="http://www.w3.org/1999/xhtml">
	<apidoc:summary>
		<p>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:</p>
	<ul>
      <li><code><em>install_dir</em>/Modules/MarkLogic/alert.xqy</code></li>
      </ul>
      <p>where <code><em>install_dir</em></code> is the directory in which 
	      MarkLogic Server is installed.</p>
      <p> To use the alert.xqy module in your own XQuery modules, include the 
	      following line in your XQuery prolog:</p>
      <p><code>import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";</code></p>
      <p>The library uses the <code>alert:</code> namespace, which is 
	      <code>not</code> predefined in the server.</p>
      <p>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. 
      </p>
   </apidoc:summary>

  <apidoc:function name="make-config" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc: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
		  <code>alert:config-insert</code>. This URI will also be 
		  used as a directory for all documents (config, actions, 
		  and rules) associated with the config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="uri" type="xs:string">The URI for this alerting 
		    config.</apidoc:param>
	    <apidoc:param name="name" type="xs:string">The name for this 
		    alerting config.</apidoc:param>
	    <apidoc:param name="description" type="xs:string">A description for 
		    this alerting config.</apidoc:param>
	    <apidoc:param name="options" type="element(alert:options)">
		    Additional options available to an alerting application 
		    for extra state.</apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:privilege>The <code>alert-admin</code> role is required to run
	    this function (or all of the privileges in the 
	    <code>alert-admin</code> role).
    </apidoc:privilege>
    <apidoc:usage>
	    If you add the 
	    <code>&lt;alert:unfiltered&gt;true&lt;/alert:unfiltered&gt;</code>
	    option to the <code>$options</code> parameter, it will cause all
	    <code>cts:search</code> operations that use this config to 
	    run unfiltered.  This applies to the functions in the 
	    Alerting API that use <code>cts:search</code> (for example, 
	    <code>alert:find-matching rules</code>). 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.
    </apidoc:usage>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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/>
    )
    ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-insert" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc: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.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">the config to insert</apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
</pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-get" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>Gets the config associated with the specified URI. The user must have the alert-user privilege to call this function.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string">The URI of the alerting config.</apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)?</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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")
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-delete" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc: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.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="uri" type="xs:string">The URI of the alerting config.</apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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")
  </pre></apidoc:example>
  </apidoc:function>

    <apidoc:function name="config-get-id" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	    <apidoc:summary>This function provides convenient 
		    access to the specified sub-element within an 
		    alerting config.
	    </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-get-id($config)

  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="config-set-uri" lib="alert" category="Alerting" 
	  bucket="XQuery Library Modules" hidden="true">
    <apidoc:summary>This function provides convenient access to the specified sub-element within an alerting config.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">The specified alerting configuration</apidoc:param>
      <apidoc:param name="uri" type="xs:string">The URI of the specified configuration.</apidoc:param>
    </apidoc:params>
    <apidoc:return>element (alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-set-uri($config, "http://acme.com/alert/message-board")
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="config-get-uri" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function provides convenient access to the specified sub-element within an alerting config.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">The specified alerting configuration</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-get-uri($config)

  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="config-get-name" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function provides convenient access to the specified sub-element within an alerting config.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">The specified alerting configuration</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-get-name($config)

  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-set-name" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function provides convenient access to the specified sub-element within an alerting config.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">The specified alerting configuration</apidoc:param>
      <apidoc:param name="name" type="xs:string">The name of the specified configuration.</apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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")
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-get-description" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function provides convenient access to the specified sub-element within an alerting config.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">The specified alerting configuration</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-get-description($config)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-set-description" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function provides convenient access to the
		  specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
      <apidoc:param name="description" type="xs:string">The 
	      description of the specified configuration.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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")
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-get-trigger-ids" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function provides convenient access to the specified sub-element within an alerting config.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="config" type="element(alert:config)">The specified alerting configuration</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-set-trigger-ids" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function provides convenient access to 
		  the specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
      <apidoc:param name="ids" type="xs:unsignedLong*">The trigger IDs 
	      of the specified configuration.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-get-cpf-domain-ids" lib="alert" category="Alerting" bucket="XQuery Library Modules" hidden="true">
	  <apidoc:summary>This function provides convenient access to 
		  the specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-get-cpf-domain-ids($config)
  </pre></apidoc:example>
  </apidoc:function>


  <apidoc:function name="config-get-cpf-domain-names" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function provides convenient access 
		  to the specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>



  <apidoc:function name="config-set-cpf-domain-names" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function provides convenient access to the 
		  specified sub-element within an alerting 
		  config.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.</apidoc:param>
	    <apidoc:param name="names" type="xs:string*">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. 
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-set-cpf-domain-ids" lib="alert" category="Alerting" bucket="XQuery Library Modules" hidden="true">
	  <apidoc:summary>This function provides convenient access 
		  to the specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
      <apidoc:param name="ids" type="xs:unsignedLong*">The CPF domain 
	      IDs of the specified configuration.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-set-cpf-domain-ids($config, $domain-ids)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-get-options" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function provides convenient access to 
		  the specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:options)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:config-get-options($config)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="config-set-options" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function provides convenient access to 
		  the specified sub-element within an alerting config.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config" type="element(alert:config)">The 
		    specified alerting configuration.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(alert:options)">The 
		    options of the specified configuration.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:config)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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 />)
  ]]></pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="create-triggers" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>Create triggers that invoke the standard alerting 
		  trigger module. The caller must have the 
		  <code>alert-admin</code> privilege. The returned 
		  trigger IDs must be associated with the config using 
		  <code>alert:config-set-trigger-ids</code> and then 
		  saving the updated config with 
		  <code>alert:config-insert</code>.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="uri" type="xs:string">The URI specified 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
	    <apidoc:param name="events" type="element(trgr:data-event)*">Events 
		    for which to create triggers.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="remove-triggers" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc: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 
		  <code>admin:delete-config</code>, for example), you should
		  do so in another transaction. 
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="uri" type="xs:string">The URI 
		    specified to <code>alert:make-config</code>.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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")
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="find-matching-rules" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>Returns a list of all rules associated with 
		  the specified config that match the specified document. 
		  You must have the <code>alert-admin</code> privilege 
		  to call this function.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config-uri" type="xs:string">The alerting 
		    configuration from which to match rules.
	    </apidoc:param>
	    <apidoc:param name="doc" type="node()">The document 
		    to match against.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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"))
  ]]></pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="invoke-matching-actions" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc: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.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config-uri" type="xs:string">The alerting 
		    configuration from which to match rules.
	    </apidoc:param>
	    <apidoc:param name="doc" type="node()">The document 
		    to match against.
	    </apidoc:param>
	    <apidoc:param name="options" type="node()">The options node
		    to pass to <code>xdmp:invoke</code> when invoking 
		    each action. The options node should be in the 
		    <code>xdmp:eval</code> namespace.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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/>)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="spawn-matching-actions" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc: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.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="config-uri" type="xs:string">The alerting 
		    configuration from which to match rules.
	    </apidoc:param>
	    <apidoc:param name="doc" type="node()">The document to 
		    match against.
	    </apidoc:param>
	    <apidoc:param name="options" type="node()">The options mode 
		    to pass to <code>xdmp:spawn</code> when spawning each 
		    action. The options node should be in the 
		    <code>xdmp:eval</code> namespace.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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"/>)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="make-rule" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function creates the XML representing a rule. 
		  If the caller does not have the <code>alert-admin</code>
		  privilege then <code>$user-id</code> must be the ID
		  of the current user from the security database.  
		  If <code>$user-id</code> is 0, it will be automatically 
		  replaced with the current user's ID.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="name" type="xs:string">The name given to 
		    the rule.</apidoc:param>
	    <apidoc:param name="description" type="xs:string">A text 
		    description of the rule.</apidoc:param>
	    <apidoc:param name="user-id" type="xs:unsignedLong">The user 
		    ID from the security database of the user who will 
		    be notified of matches.
	    </apidoc:param>
	    <apidoc:param name="query" type="cts:query">The query that 
		    the rule will be matched against for alerting.
	    </apidoc:param>
	    <apidoc:param name="action" type="xs:string">The name of the 
		    action to occur upon the matching of the rule.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(alert:options)">
		    Information specific to the application for the rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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>
  )
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-insert" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc: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.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="rule-remove" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function removes the XML representing the 
		  rule from the collection. A user must have the 
		  <code>alert-user</code> privilege to call this function. 
		  An exception is thrown if the rule does not exist. A user 
		  must have the <code>alert-admin</code> privilege to delete 
		  other users' rules.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
	    <apidoc:param name="id" type="xs:unsignedLong">The ID of the 
		    rule to be removed.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>

    <apidoc:function name="get-all-rules" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	    <apidoc:summary>This function returns all rules visible to the 
		    current user.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
	    <apidoc:param name="query" type="cts:query">The 
		    <code>cts:query</code> with which to restrict the 
		    rules that are returned.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)*</apidoc:return>
    <apidoc:privilege>
	    <code>http://marklogic.com/xdmp/privileges/xdmp-alert-user</code>
    </apidoc:privilege>
    <apidoc:example><pre xml:space="preserve">
  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"))
  </pre></apidoc:example>
  </apidoc:function>

      <apidoc:function name="get-my-rules" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	    <apidoc:summary>This function returns all rules associated with the 
		    current user.
	    </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
	    <apidoc:param name="query" type="cts:query">The 
		    <code>cts:query</code> with which to restrict the 
		    rules that are returned.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)*</apidoc:return>
    <apidoc:privilege>
	    <code>http://marklogic.com/xdmp/privileges/xdmp-alert-user</code>
    </apidoc:privilege>
    <apidoc:example><pre xml:space="preserve">
  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"))
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="rule-id-query" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function creates a query to find rules 
		  with any of the specified IDs.  Returns a query to 
		  be passed to <code>alert:get-my-rules</code> or
		  <code>alert:get-all-rules</code>.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="ids" type="xs:unsignedLong*">A list of 
		    IDs for the rules to be retrieved.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>cts:query</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-name-query" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function creates a query to find rules 
		  with any of the specified names.  Returns a query to 
		  be passed to <code>alert:get-my-rules</code> or
		  <code>alert:get-all-rules</code>.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="names" type="xs:string*">A list of names 
		    for the rules to be retrieved.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>cts:query</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-user-id-query" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function creates a query to find rules 
		  with any of the specified user IDs.  Returns a query to 
		  be passed to <code>alert:get-my-rules</code> or
		  <code>alert:get-all-rules</code>.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="user-ids" type="xs:unsignedLong*">A list of user
		    IDs for the rules to be retrieved.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>cts:query</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-action-query" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function creates a query to find rules 
		  with any of the specified actions.  Returns a query 
		  to be passed to <code>alert:get-my-rules</code> or
		  <code>alert:get-all-rules</code>.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="actions" type="xs:string*">A list of action 
		    names for the rules to be retrieved.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>cts:query</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-id" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the ID of a 
		  given rule.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:rule-get-id($rule)
  => 4363547345
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-user-id" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the user ID
		  of a given rule.
	  </apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-set-user-id" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the rule with the user ID 
		  updated. If the caller does not have the 
		  <code>alert-config</code> privilege, an exception will be 
		  thrown if the caller attempts to save a rule for a user other 
		  than himself.
	  </apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
	    <apidoc:param name="user-id" type="xs:unsignedLong">The user ID 
		    value to set for the given rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-action" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the action of a 
		  given rule.
	  </apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:rule-get-action($rule)
  => sms
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-set-action" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the rule with the action updated.</apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
	    <apidoc:param name="action" type="xs:string">The action value 
		    to set for the given rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-name" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the name of a given rule.</apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-set-name" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the rule with the name of the rule updated.</apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
	    <apidoc:param name="name" type="xs:string">The name value to 
		    set for the given rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-description" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the description of a given rule.</apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-set-description" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the rule with the
		  description of the rule updated.
	  </apidoc:summary>
    <apidoc:params>
            <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of a rule.
	    </apidoc:param>
	    <apidoc:param name="description" type="xs:string">The 
		    description value to set for the given rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-query" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>Get the <code>cts:query</code> corresponding to 
		  the rule's query expression.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of the rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>cts:query</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-set-query" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>Set the cts:query corresponding to the rule's query expression.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of the rule.
	    </apidoc:param>
	    <apidoc:param name="query" type="cts:query">The serialized version 
		    of the query for documents to match on.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-get-options" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the options of a 
		  given rule.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of the rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:options)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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>
     ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="rule-set-options" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the rule with the 
		  options of the rule updated.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="rule" type="element(alert:rule)">The 
		    XML representation of the rule.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(alert:options)">The 
		    options to set for the given rule.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:rule)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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>
   ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-get-name" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the name of a 
		  given action.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="action" type="element(alert:action)">The 
		    xml representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  xquery version "1.0-ml";
  import module namespace alert = "http://marklogic.com/xdmp/alert" 
		  at "/MarkLogic/alert.xqy";

  alert:action-get-name($action)
  => sms
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-set-name" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the action with the name of 
		  the action updated.
	  </apidoc:summary>
    <apidoc:params>
       	    <apidoc:param name="action" type="element(alert:action)">The 
		    xml representation of an action.
	    </apidoc:param>
	    <apidoc:param name="name" type="xs:string">The name value to set 
		    for the given action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-get-description" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the description of 
		  a given action.
	  </apidoc:summary>
    <apidoc:params>
	     <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-set-description" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the action with the 
		  description of the action updated.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
	    <apidoc:param name="description" type="xs:string">The 
		    description value to set for the given action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="action-get-module-db" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the module database 
		  of a given action.
	  </apidoc:summary>
    <apidoc:params>
     <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-set-module-db" lib="alert" category="Alerting" bucket="XQuery Library Modules">
    <apidoc:summary>This function sets the module database of a given action.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
	    <apidoc:param name="module-db" type="xs:unsignedLong">The ID of 
		    the database containing the module of the action. 
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"))
  </pre></apidoc:example>
  </apidoc:function>


    <apidoc:function name="action-get-module-root" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	    <apidoc:summary>This function returns the module root of a 
		    given action.</apidoc:summary>
    <apidoc:params>
     <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-set-module-root" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function sets the module root of a 
		  given action.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
	    <apidoc:param name="module-root" type="xs:string">The new 
		    modules root for the action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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/")
  </pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="action-get-module" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the module of a 
		  given action.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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)
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-set-module" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the action with the 
		  module of the action updated.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
	    <apidoc:param name="module" type="xs:string">The module value 
		    to set for the given action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-get-options" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the options of a
		  given action.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:options)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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>
]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-set-options" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the action with the 
		  options of the action updated.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
	    <apidoc:param name="options" type="element(alert:options)">The 
		    options to set for the given action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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>
]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="make-action" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary><p>
		  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: </p><pre xml:space="preserve">
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;</pre>
    <p>All actions must accept these external variables.</p>
</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string">The name give to 
	    the action.
      </apidoc:param>
      <apidoc:param name="description" type="xs:string">A text description 
	      of the action.
      </apidoc:param>
      <apidoc:param name="module-db" type="xs:unsignedLong">The database ID
	      where the XQuery modules reside.  Use 
	      <code>xdmp:module-database()</code> to specify the
	      configured database.
      </apidoc:param>
      <apidoc:param name="module-root" type="xs:string">The path to the module 
	      root.  Use <code>xdmp:module-root()</code> to specify the
	      configured root.
      </apidoc:param>
      <apidoc:param name="module" type="xs:string">The URI of the module 
	      to invoke.
      </apidoc:param>
      <apidoc:param name="options" type="element(alert:options)">Optional 
	      information specific to the action.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  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
]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="make-log-action" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary><p>Create a standard logging action named "log". 
			  Rules that reference this action must provide an 
			  <code>&lt;alert:directory/&gt;</code> 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. </p>
		  Rules that reference this action may also provide options
		  with an <code>&lt;alert:permissions&gt;</code> element 
		  containing a series of <code>&lt;sec:permission&gt;</code>
		  elements and/or an <code>&lt;alert:collections&gt;</code> 
		  element containing <code>&lt;alert:collection&gt;</code>
		  elements that specify the permissions and collections for
		  the log document. This information is simply passed through
		  to <code>xdmp:document-insert</code>.
		An example of the rule's options is as follows:
				<pre><![CDATA[
<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.]]></pre>
</apidoc:summary>
    <apidoc:params>
    </apidoc:params>
    <apidoc:return>element(alert:action)</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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())
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-insert" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function inserts the xml representing the action 
		  into the collection. The caller must have the 
		  <code>alert-admin</code> privilege to call this 
		  function.</apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
            <apidoc:param name="action" type="element(alert:action)">The 
		    XML representation of an action.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:privilege>
<code>http://marklogic.com/xdmp/privileges/xdmp-alert-admin</code>, 
<code>http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change</code> 
(if changing the modules database), 
<code>http://marklogic.com/xdmp/privileges/xdmp-invoke-modules-change-fs</code>
(if changing the modules db to someplace on the filesystem)
    </apidoc:privilege>
    <apidoc:example><pre xml:space="preserve">
  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
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="action-remove" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc: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 <code>alert-admin</code>
		  privilege to call this function.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
	    <apidoc:param name="name" type="xs:string">The name of the 
		    action to be removed.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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"
  </pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-actions" lib="alert" category="Alerting" bucket="XQuery Library Modules">
	  <apidoc:summary>This function retrieves all the named 
		  actions in the specified config URI.  Returns a 
		  list of actions.
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="collection-uri" type="xs:string">The URI passed 
		    to <code>alert:make-config</code>.
	    </apidoc:param>
	    <apidoc:param name="names" type="xs:string*">The names of the 
		    actions to retrieve, possibly using wildcards.
	    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(alert:action)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve">
  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
  </pre></apidoc:example>
  </apidoc:function>
</apidoc:module>
