<apidoc:module name="PipelinesModule" category="Pipelines" bucket="CPF Functions" 
  xmlns:apidoc="http://marklogic.com/xdmp/apidoc"
  xmlns="http://www.w3.org/1999/xhtml" lib="p"
>
<apidoc:summary access="public">
<p>The pipelines module is installed as part of the Content Processing
Framework. 
These functions are used to manage pipelines, which define content processing
steps.
</p>
<p>To use the pipelines module as part of your own XQuery module, include the
following line in your XQuery prolog:
</p>
<p><code>import module namespace p = "http://marklogic.com/cpf/pipelines"
         at "/MarkLogic/cpf/pipelines.xqy";</code></p>
<p>The library namespace prefix <code>p</code> is <em>not</em> predefined in
the server.</p>
<p>These functions should be executed in the context of the triggers database.</p>
</apidoc:summary>

<apidoc:function name="insert" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>Insert a fully constructed content processing pipeline, 
  returning its unique ID.
  If a pipeline with the same name already exists in the database, it is
  replaced.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="pipeline-node" type="node()">
    The pipeline definition. Any pipeline-id element will be ignored.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:unsignedLong </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:insert( xdmp:get("/pipelines/myapp.xml")/* )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="create" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>Create a new content processing pipeline.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="name" type="xs:string">
    The name of the pipeline. It must be unique.
    </apidoc:param>
    <apidoc:param name="description" type="xs:string">
    A description of the pipeline.
    </apidoc:param>
    <apidoc:param name="success-action" type="element(p:action)?">
    The default action for successful transitions. If none is provided the
    system default success action will be used. Create using p:action.
    </apidoc:param>
    <apidoc:param name="failure-action" type="element(p:action)?">
    The default action for failed transitions. If none is provided the
    system default failure action will be used. Create using p:action.
    </apidoc:param>
    <apidoc:param name="status-transitions" type="element(p:status-transition)*">
    Status transition definitions. There should be exactly one status
    transition for the statuses "created", "deleted", and
    "updated". Create using p:status-transition.
    </apidoc:param>
    <apidoc:param name="state-transitions" type="element(p:state-transition)*">
    State transition definitions. There should be at most one state transition
  for a given state. Create using p:state-transition.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> xs:unsignedLong </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  let $init-state := xs:anyURI("http://example.com/states/init")
  let $error-state := xs:anyURI("http://example.com/states/error")
  return
  p:create( "Empty", "No nothing much", (), (), 
            ( p:status-transition("created", "", 
                                  $init-state, 
				  $error-state, 
				  (), (), () ),
	      p:status-transition("deleted", "", 
	                          (), 
	                          $error-state, 
				  (), (), () ),
	      p:status-transition("updated", "", 
				  (), 
				  $error-state, 
				  (), (), () )
             ), ()
          )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="remove" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
Remove the named pipeline.
An error is raised if no such pipeline exists. 
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="pipeline-name" type="xs:string">
    The name of the pipeline to remove.
    </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 p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:remove( "Empty" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="get" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
Find a particular pipeline.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="pipeline-name" type="xs:string">
    The name of the pipeline to get. An error is raised if no such pipeline exists.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:pipeline) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:get( "Link Maintenance" )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="get-by-id" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
Find a particular pipeline.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="pipeline-id" type="xs:unsignedLong">
	    The ID of the pipeline to get. An error is raised if no 
	    such pipeline exists.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:pipeline) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";
  import module namespace dom = "http://marklogic.com/cpf/domains" 
		  at "/MarkLogic/cpf/domains.xqy";
          
  p:get-by-id( dom:get("Default Domain")/dom:pipeline[1] )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="collection" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Return the name of the collection in which pipelines are stored.
  </apidoc:summary>
  <apidoc:params>
  </apidoc:params>
  <apidoc:return>xs:string</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:collection()
      ==> returns "http://marklogic.com/cpf/pipelines"
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="pipelines" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Return all the pipelines.
  </apidoc:summary>
  <apidoc:params>
  </apidoc:params>
  <apidoc:return> element(p:pipeline)* </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  for $pipeline in p:pipelines()
  return $pipeline/p:pipeline-name
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="state-transition" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Construct a new state transition element.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="state" type="xs:anyURI">
    The name of the state.
    </apidoc:param>
    <apidoc:param name="description" type="xs:string">
    A description of the transition.
    </apidoc:param>
    <apidoc:param name="on-success" type="xs:anyURI?">
    The successor state, should the transition succeed. If no successor state
    is defined, the document will remain in its current state.
    </apidoc:param>
    <apidoc:param name="on-failure" type="xs:anyURI?">
    The successor state, should the transition fail. If no successor state
    is defined, the document will remain in its current state.
    </apidoc:param>
    <apidoc:param name="priority" type="xs:unsignedLong?">
    The priority for this transition.  Higher priority transitions will be
    examined before lower priority ones.  If no priority is passed, then
    the transition gets the highest priority.
    </apidoc:param>
    <apidoc:param name="default-action" type="element(p:action)?">
    The default action to execute on entry into this state, if none of the
    rules apply.
    </apidoc:param>
    <apidoc:param name="rules" type="element(p:execute)*">
    The execution rules to apply in this transition. The first rule whose
    condition is true will have its action executed.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:state-transition) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:state-transition( xs:anyURI("http://example.com/states/review"),
                      "Document review state", 
                      (), xs:anyURI("http://example.com/states/error"), (),
                      p:action("/app/send-to-reviewer.xqy",(), ()),
                      () )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="status-transition" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Construct a new status transition element.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="status" type="xs:string">
    The status: either "created", "updated", or
    "deleted".
    </apidoc:param>
    <apidoc:param name="description" type="xs:string">
    A description of the transition.
    </apidoc:param>
    <apidoc:param name="on-success" type="xs:anyURI?">
    The successor state, should the transition succeed. If no successor state
    is defined, the document will remain in its current state.
    </apidoc:param>
    <apidoc:param name="on-failure" type="xs:anyURI?">
    The successor state, should the transition fail. If no successor state
    is defined, the document will remain in its current state.
    </apidoc:param>
    <apidoc:param name="priority" type="xs:unsignedLong?">
    The priority for this transition.  Higher priority transitions will be
    examined before lower priority ones.  If no priority is passed, then
    the transition gets the highest priority.
    </apidoc:param>
    <apidoc:param name="default-action" type="element(p:action)?">
    The default action to execute on entry into this status, if none of the
    rules apply.
    </apidoc:param>
    <apidoc:param name="rules" type="element(p:execute)*">
    The execution rules to apply in this transition. The first rule whose
    condition is true will have its action executed.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:status-transition) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:status-transition("created", 
                      "Document creation: Put in initial state.",
                      xs:anyURI("http://example.com/states/initial"), (), (),
                      (), () )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="execute" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Construct a execute element.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="condition" type="element(p:condition)?">
    The condition to execute to test whether this rule applies. If no
    condition is specified, the action always executes.
    </apidoc:param>
    <apidoc:param name="action" type="element(p:action)?">
    The action to execute should this rule apply. If no action is specified,
    the default success action will execute instead.
    </apidoc:param>
    <apidoc:param name="description" type="xs:string?">
    A description of the rule.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:execute) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  let $options := 
     <options xmlns="/app/test-root.xqy">
        <root>workitem</root>
     </options> 
  return 
  p:execute( p:condition("/app/test-root.xqy", (), $options ), (),
             "Execute default action on workitems."
           )
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="condition" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Construct a condition element.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="module" type="xs:string">
    The path to the module to evaluate.
    </apidoc:param>
    <apidoc:param name="description" type="xs:string?">
    A description of the condition.
    </apidoc:param>
    <apidoc:param name="options" type="element()?">
    The options element to pass to the module as the external variable
    $cpf:options. The options element will be in the namespace
    of the module.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:condition) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  let $options := 
     <options xmlns="/app/test-root.xqy">
        <root>workitem</root>
     </options> 
  return p:condition("/app/test-root.xqy", (), $options )
         ===> returns 
            <p:condition xmlns:p="http:marklogic.com/cpf/pipelines">
               <p:module>/app/test-root.xqy</p:module>
               <options xmlns="/app/test-root.xqy">
                 <root>workitem</root>
               </options> 
            </p:condition>
  ]]></pre>
  </apidoc:example>
</apidoc:function>

<apidoc:function name="action" type="pipeline" lib="p" 
                 category="Pipelines" bucket="CPF Functions">
  <apidoc:summary>
  Construct an action element.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="module" type="xs:string">
    The path to the module to evaluate.
    </apidoc:param>
    <apidoc:param name="description" type="xs:string?">
    A description of the action.
    </apidoc:param>
    <apidoc:param name="options" type="element()?">
    The options element to pass to the module as the external variable
    $cpf:options. The options element will be in the namespace
    of the module.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return> element(p:action) </apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  xquery version "1.0-ml";
  import module namespace p = "http://marklogic.com/cpf/pipelines" 
		  at "/MarkLogic/cpf/pipelines.xqy";

  p:action("/app/process-workitem.xqy", (), () )
         ===> returns 
            <p:action xmlns:p="http:marklogic.com/cpf/pipelines">
               <p:module>/app/process-workitem.xqy</p:module>
            </p:action>
  ]]></pre>
  </apidoc:example>
</apidoc:function>
</apidoc:module>
