Workflow-Engine

WorkflowApi methods

The WorkflowApi contains the following methods:

• createWorkflow
  create and start a new workflow based upon a given workflow template.
  
• doTransition
  execute the specified transition and either create new tasks or check if this workflow is finished.
  
• findOpenTasks
  find all open tasks for a user, a workflow or the whole repository. 

A detailed documentation of these methods can be found in the WorkflowApi-class' JavaDoc.

HowTo list available workflow templates

Query the server for all objects of the type _workflow_template (via searchObjects) where active_workflow=true:

<BooleanQuery>
  <Clause occurs='must'><TermQuery fieldName='objecttype'> $id_of_workflow_template_objectType </TermQuery></Clause>
  <Clause occurs='must'><TermQuery fieldName='active_workflow'>true</TermQuery></Clause>
  <Clause occurs='must'><TermQuery fieldName='latesthead'>true</TermQuery></Clause>
</BooleanQuery>

Metadata structure and relations of WorkflowApi objects

Workflow-Template

the start task.

It has a relation of type "_workflow_task" with all tasks that are part of this workflow.

<meta>
  <active_workflow>true</active_workflow>  
</meta>

TaskDefinition

A TaskDefinition contains a list of required and optional fields:

The name of the TD-OSD is the screen label.

<?xml version="1.0" encoding="UTF-8"?>
<meta>
    <metaset type="task_definition">
        <name>cinnamon.test.EditTask</name>
        <manual>true</manual>
        <description>Review the document</description>
        <input>
            <fixed>    <!-- This parameter should be set via the transition leading here. -->
                <param>
                    <type>document</type>
                    <!-- id of a Cinnamon document -->
                    <label>document</label>
                    <name>document</name>
                    <value></value>
                </param>
            </fixed>
            <required>
                <param>
                    <type>user</type>
                    <!-- a Cinnamon user id -->
                    <label>reviewer</label>
                    <!-- screen label -->
                    <name>reviewer</name>
                    <!-- parameter name -->
                    <value></value>
                </param>
            </required>
            <optional>
                <param>
                    <type>string</type>
                    <label>message.to.editor</label>
                    <name>message</name>
                    <value></value>
                </param>
            </optional>
        </input>
    </metaset>
    <metaset type="transition">
  <!-- define transitions here -->
    </metaset>
</meta>

Thoughts on design: <value> could contain a query [type, query_string] which the client can execute to receive a map <label, value> from the server. For example: query for reviewers, query for new documents, ...

<deadline> The deadline element is a datetime string following the ISO 8601 format (YYYY-MM-DDThh:mm:ss) used for determining deadlines on tasks. When the deadline is reached, the deadline_transition is executed (which must be configured as one of the possible transitions of the task).

Transitions

Transitions are classes on the server which perform validation of input data and create subsequent tasks as needed.

The kind of transitions a task has is defined in the task's metadata in the metaset=task_definition element.

<?xml version="1.0" encoding="UTF-8"?>
<meta>
    <metaset type="task_definition">
      <!-- define task definition here as seen above -->
    </metaset>
    <metaset type="transition">
        <manual>true</manual>
        <default>edit_to_review</default>
        <transition>
            <show>true</show>
            <name>edit_to_review</name>
            <label>transition.edit_to_review</label>
            <class>workflow.transition.test.EditToReview</class>
            <tasks>
                <task name="review_task">cinnamon.test.ReviewTask</task>
            </tasks>
        </transition>
        <transition>
            <show>true</show>
            <confirm>true</confirm>
            <name>cancel.review</name>
            <label>transition.cancel.review</label>
            <class>workflow.transition.test.CancelReviewWorkflow</class>
        </transition>
    </metaset>
</meta>

WorkflowServer process

The WorkflowServer is a separate thread which is instantiated for each repository, if the cinnamon_config.xml contains the element <startWorkflowServer>true</startWorkflowServer>. It runs continuously every couple of seconds and checks if there are automatic transitions to execute.

This process is also responsible for checking on deadlines and executing the corresponding deadline_transitions if necessary.