MarkLogic Server
XQUERY API DOCUMENTATION
4.0
All XQuery Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
 W3C XQuery Reference
W3C XQuery Functions
W3C XQuery Language
This page was generated
July 7, 2010
4:03 PM
XQuery Built-In and Modules Function Reference

Module: Triggers

The triggers function module is installed as the following file:

  • install_dir/Modules/MarkLogic/triggers.xqy

where install_dir is the directory in which MarkLogic Server is installed.

To use the triggers.xqy module in your own XQuery modules, include the following line in your XQuery prolog:

import module namespace trgr="http://marklogic.com/xdmp/triggers" at "/MarkLogic/triggers.xqy"

The triggers module is used for manually creating and managing triggers. If you use the Content Processing Framework, it automatically creates and manages the triggers.

The function to create the a new trigger, trgr:create-trigger, uses the other trigger functions to construct the trigger XML document and insert it into the triggers database. The trigger functions should all be run against the triggers database for the database in which the content is stored.

Function Summary
trgr:any-property-content Returns the representation of an all-properties part to a triggering event.
trgr:collection-scope Returns the representation of a collection scope.
trgr:create-trigger Creates a new trigger in the context database.
trgr:directory-scope Returns the representation of a directory scope.
trgr:document-content Returns the representation of a document part to a triggering event.
trgr:document-scope Returns the representation of a document scope.
trgr:get-trigger Returns the xml representation of the trigger named $trigger-name.
trgr:get-trigger-by-id Returns the xml representation of the trigger that has a trigger-id of $trigger-id.
trgr:post-commit Returns the representation of a post-commit trigger timing.
trgr:pre-commit Returns the representation of a pre-commit trigger timing.
trgr:property-content Returns the representation of a property part to a triggering event.
trgr:remove-trigger Remove the trigger named $trigger-name.
trgr:trigger-add-permissions Add $permissions to the set of permissions on the trigger named $trigger.
trgr:trigger-data-event Returns the representation of a triggering event.
trgr:trigger-database-online-event Returns the representation of a database coming online event.
trgr:trigger-disable Disable the trigger named $trigger-name.
trgr:trigger-enable Enable the trigger named $trigger-name.
trgr:trigger-get-permissions Get the set of permissions of the trigger named $trigger-name.
trgr:trigger-module Returns the representation of a trigger module invocation.
trgr:trigger-remove-permissions Remove $permissions from the set of permissions on the trigger named $trigger-name.
trgr:trigger-set-description Sets the description of the trigger nameds $trigger-name to $description.
trgr:trigger-set-event Assigned the trigger named $trigger-name the new triggering event defined in $event.
trgr:trigger-set-module Assigned the trigger named $trigger-name the new execution module defined in $module.
trgr:trigger-set-name Changes the name of the trigger from $user-name to $new-user-name.
trgr:trigger-set-permissions Set the permissions on the trigger to the new set of permissions in $permissions.
trgr:trigger-set-recursive Sets the recursive setting of the identified trigger.
Function Detail
trgr:any-property-content( ) as element(trgr:any-property-content)
Summary:

Returns the representation of an all-properties part to a triggering event.

trgr:collection-scope(
$uri as xs:string
)  as  element(trgr:collection-scope)
Summary:

Returns the representation of a collection scope.

Parameters:
$uri : The collection uri.

trgr:create-trigger(
$trigger-name as xs:string,
$description as xs:string?,
$event as element(),
$module as element(trgr:module),
$enabled as xs:boolean,
$permissions as element(sec:permission)*,
[$recursive as xs:boolean]
)  as  xs:unsignedLong
Summary:

Creates a new trigger in the context database. Returns the trigger ID of the created trigger.

Parameters:
$trigger-name : A unique name. If $trigger-name is not unique, an error is returned.
$description : A description of the trigger.
$event : The definition of an event that invokes the trigger module. Use trgr:trigger-data-event or trgr:trigger-database-online-event to construct this element.
$module : The module to execute when the triggering event occurs. Use trgr:trigger-module to construct this element.
$enabled : Set to true if the trigger is enabled.
$permissions : A sequence of permissions for the trigger. These permissions will determine which roles are permitted to modify the trigger.
$recursive (optional): Set to true if the trigger should be allowed to trigger itself for recursive changes on the same document. Set to false to prevent the trigger from triggering itself. If this parameter is not present, then its value is true.

Required Privilege:

http://marklogic.com/xdmp/privileges/create-trigger
Usage Notes:

Triggers should be created in the database defined as the triggers database for the database in which the documents are stored. The xdmp:triggers-database function returns the ID of the triggers database (when run against the database in which the content is stored). The triggers are created in the http://marklogic.com/xdmp/triggers/ directory, with the ID of the trigger completing the URI.

Once a trigger is created, you can view it in the Admin Interface under the database in which the content is stored, in the Triggers Summary page (Databases > content_db_name > Triggers).


Example: 
xquery version "0.9-ml"
import module namespace trgr="http://marklogic.com/xdmp/triggers" 
   at "/MarkLogic/triggers.xqy"

trgr:create-trigger("myTrigger", "Simple trigger example", 
  trgr:trigger-data-event(
      trgr:directory-scope("/myDir/", "1"),
      trgr:document-content("create"),
      trgr:post-commit()),
  trgr:trigger-module(xdmp:database("test"), "/modules/", "log.xqy"),
  fn:true(), xdmp:default-permissions() )

  => The ID of the newly created trigger. This
     trigger fires when a document is created in
     the /myDir/ directory, and then it spawns the
     /modules/log.xqy XQuery document (in the modules
     database for App Server against which the document
     was created) is placed on the task server to
     evaluate.
trgr:directory-scope(
$uri as xs:string,
$depth as xs:string
)  as  element(trgr:directory-scope)
Summary:

Returns the representation of a directory scope.

Parameters:
$uri : The directory uri.
$depth : The depth of descendants included in the scope. ("1" or "infinity")

trgr:document-content(
$update-kind as xs:string
)  as  element(trgr:document-content)
Summary:

Returns the representation of a document part to a triggering event.

Parameters:
$update-kind : "create", "modify", or "delete"

trgr:document-scope(
$uri as xs:string
)  as  element(trgr:document-scope)
Summary:

Returns the representation of a document scope.

Parameters:
$uri : The document uri.

trgr:get-trigger(
$trigger-name as xs:string
)  as  element(trgr:trigger)
Summary:

Returns the xml representation of the trigger named $trigger-name.

Parameters:
$trigger-name : The trigger name.

trgr:get-trigger-by-id(
$trigger-id as xs:unsignedLong
)  as  element(trgr:trigger)
Summary:

Returns the xml representation of the trigger that has a trigger-id of $trigger-id.

Parameters:
$trigger-id : The trigger id.

trgr:post-commit( ) as element(trgr:when)
Summary:

Returns the representation of a post-commit trigger timing.

Usage Notes:

Use this function with trgr:trigger-data-event to specify a post-commit trigger.
trgr:pre-commit( ) as element(trgr:when)
Summary:

Returns the representation of a pre-commit trigger timing.

Usage Notes:

Use this function with trgr:trigger-data-event to specify a pre-commit trigger.
trgr:property-content(
$property-name as xs:QName
)  as  element(trgr:property-content)
Summary:

Returns the representation of a property part to a triggering event.

Parameters:
$property-name : The QName of the property.

trgr:remove-trigger(
$trigger-name as xs:string
)  as  empty-sequence()
Summary:

Remove the trigger named $trigger-name.

Parameters:
$trigger-name : The trigger name.

Usage Notes:

This function deletes the specified trigger. You must run this function to remove a trigger before you can re-create it. If the trigger does not exist, throws the TRGR-TRIGGERDNE exception.
Example: 
xquery version "0.9-ml"
import module namespace trgr="http://marklogic.com/xdmp/triggers" 
   at "/MarkLogic/triggers.xqy"

trgr:remove-trigger("myTrigger")

=> Empty. Removes the specified trigger from the database.
trgr:trigger-add-permissions(
$trigger-name as xs:string,
$permissions as element(sec:permission)*
)  as  empty-sequence()
Summary:

Add $permissions to the set of permissions on the trigger named $trigger.

Parameters:
$trigger-name : The trigger name.
$permissions : A sequence of permission nodes.

trgr:trigger-data-event(
$scope as element(),
$content as element(),
$when as element(trgr:when)
)  as  element(trgr:data-event)
Summary:

Returns the representation of a triggering event.

Parameters:
$scope : An event scope.
$content : An event part.
$when : The timing of the trigger execution (pre- or post-commit). Use trgr:post-commit or trgr:pre-commit to construct this element.

trgr:trigger-database-online-event(
$user-name as xs:string
)  as  element(trgr:database-online-event)
Summary:

Returns the representation of a database coming online event.

Parameters:
$user-name : The user used to execute the module.

trgr:trigger-disable(
$trigger-name as xs:string
)  as  empty-sequence()
Summary:

Disable the trigger named $trigger-name.

Parameters:
$trigger-name : The trigger name.

trgr:trigger-enable(
$trigger-name as xs:string
)  as  empty-sequence()
Summary:

Enable the trigger named $trigger-name.

Parameters:
$trigger-name : The trigger name.

trgr:trigger-get-permissions(
$trigger-name as xs:string
)  as  element(sec:permission)*
Summary:

Get the set of permissions of the trigger named $trigger-name.

Parameters:
$trigger-name : The trigger name.

trgr:trigger-module(
$database-id as xs:unsignedLong,
$root as xs:string,
$path as xs:string
)  as  element(trgr:module)
Summary:

Returns the representation of a trigger module invocation.

Parameters:
$database-id : A database-id.
$root : The root path within the database.
$path : The path to the module relative to $root within the database identified by $database-id.

trgr:trigger-remove-permissions(
$trigger-name as xs:string,
$permissions as element(sec:permission)*
)  as  empty-sequence()
Summary:

Remove $permissions from the set of permissions on the trigger named $trigger-name.

Parameters:
$trigger-name : The trigger name.
$permissions : A sequence of permission nodes.

trgr:trigger-set-description(
$trigger-name as xs:string,
$description as xs:string?
)  as  empty-sequence()
Summary:

Sets the description of the trigger nameds $trigger-name to $description.

Parameters:
$trigger-name : The trigger name.
$description : The new trigger description.

trgr:trigger-set-event(
$trigger-name as xs:string,
$event as element()
)  as  empty-sequence()
Summary:

Assigned the trigger named $trigger-name the new triggering event defined in $event.

Parameters:
$trigger-name : The trigger name.
$event : An event definition. Use trgr:trigger-data-event or trgr:trigger-database-online-event to construct this element.

trgr:trigger-set-module(
$trigger-name as xs:string,
$module as element(trgr:module)
)  as  empty-sequence()
Summary:

Assigned the trigger named $trigger-name the new execution module defined in $module.

Parameters:
$trigger-name : The trigger name.
$module : A module definition

trgr:trigger-set-name(
$trigger-name as xs:string,
$description as xs:string?
)  as  empty-sequence()
Summary:

Changes the name of the trigger from $user-name to $new-user-name.

Parameters:
$trigger-name : The current trigger name.
$description : The new trigger name.

trgr:trigger-set-permissions(
$trigger-name as xs:string,
$permissions as element(sec:permission)*
)  as  empty-sequence()
Summary:

Set the permissions on the trigger to the new set of permissions in $permissions.

Parameters:
$trigger-name : The trigger name.
$permissions : A sequence of permission nodes.

trgr:trigger-set-recursive(
$trigger-name as xs:string,
$recursive as xs:boolean
)  as  empty-sequence()
Summary:

Sets the recursive setting of the identified trigger. When the recursive setting is true, it allows the trigger to trigger itself for recursive changes to the same document.

Parameters:
$trigger-name : The current trigger name.
$recursive : The new recursive value for the specified trigger.

© Copyright 2002-2010 Mark Logic Corporation.  All rights reserved.