MarkLogic 10 Product Documentationtrgr:create-trigger
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 item()*, [$recursive as xs:boolean?], [$task-priority as xs:string] ) 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. When run in an XQuery context, the permissions are a sequence of XML elements (sec:permission). When importing this module into a Server-Side JavaScript context, the permissions are an array of Objects. |
| recursive | 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. |
| task-priority | The task priority for post-commit triggers. Either "normal" or "higher". If this parameter is not present, the value is "normal". |
Required Privileges
http://marklogic.com/xdmp/privileges/create-trigger
Usage Notes
Triggers must be created in the triggers database associated with the
content database to which the triggers apply. To determine the
triggers database programatically, use xdmp:triggers-database
in the evaluation context of the content database, or
xdmp:database
with the database name listed as the
triggers database value in the Admin Interface under
Databases > content_db_name.
Triggers are created in the
http://marklogic.com/xdmp/triggers/ directory, with
the trigger ID completing the URI. This is the ID returned by
trgr:create-trigger
.
If a trigger named $trigger-name already exists, the exception
TRGR-TNEXISTS is raised. You must use
trgr:remove-trigger
to delete an existing trigger before recreating it.
Once a trigger is created, you can view it in the Admin Interface
under the content database, in the Triggers Summary page
(Databases > content_db_name > Triggers). If your
trigger does not appear in Triggers Summary,
trgr:create-trigger
was probably evaluated in the wrong database context.
Example
(: Run in the context of the triggers database of the content database :)
xquery version "1.0-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 whenever a document is created in the
/myDir/ directory. The action module, /modules/log.xqy,
is stored in the modules database of the App Server
against which the content document is created. When
the trigger fires, a task to evaluate /modules/log.xqy
is spawned on the task server queue.