daisy-process-meta.xml reference

Overview

The daisy-process-meta.xml contains the Daisy process metadata. This file is entirely optional, but will often be required to make meaningful usage of a workflow process in Daisy. See process authoring overview for a general discussion on the role of the process metadata, this section only contains reference information.

One of the important things the Daisy process metadata describes is which variables can be updated as part of the interaction with each task. Any variables not declared in the Daisy process metadata cannot be accessed (read or updated) through the Daisy workflow API (though they can be used internally in the process definition).

All elements in the Daisy process metadata file are optional. The process metadata file should be valid according to its XML schema, so no additional elements or attributes are allowed (if it's not valid, deploying the process archive will fail).

The XML Schemas for the workflow can be found in the Daisy source tree in the directory services/workflow/xmlschema-bindings/src

Basic form

The most simple, valid process metadata file consist of only a document element, as follows:

<?xml version="1.0"?>
<workflowMeta xmlns="http://outerx.org/daisy/1.0#workflowmeta"
              xmlns:wf="http://outerx.org/daisy/1.0#workflow">
</workflowMeta>

The following sections describe the information that can be added inside this document element. The order of the elements inside the document element doesn't matter. And every one of them is optional.

As you can see, the “workflow metadata namespace” has been declared as default namespace, because most of the workflow metadata elements fall into that namespace. We've also added a declaration of the workflow namespace, since a few elements of that namespace are reused (see selectionList).

Process label and description

These elements allow to specify a label and description for the process definition. If no label is specified, the process definition name (specified in processdefinition.xml) is used as label.

<workflowMeta xmlns="http://outerx.org/daisy/1.0#workflowmeta">
 <label [i18n="true"]>...</label>
 <description [i18n="true"]>...</description>
</workflowMeta>

The i18n attribute indicates whether the content of the label or description element is a resource bundle key, rather than the actual text. See workflow process internationalization for more details on this.

Resource bundles

Zero or more resource bundles can be specified which are searched to lookup internationalized texts.

For each resource bundle, only the base name should be specified, without a directory path. The resource bundles are always retrieved from the i18n subdirectory in the process archive.

Having multiple resource bundles can be useful when sharing sets of messages between multiple process definitions.

For more details on resource bundles see workflow process internationalization.

<workflowMeta xmlns="http://outerx.org/daisy/1.0#workflowmeta">
  <resourceBundles>
    <resourceBundle>...</resourceBundle>
    [... more resource bundles ...]
  </resourceBundles>
</workflowMeta>

Reusable variables declarations

As detailed in the section on variables, for each task in a process it is possible to specify some variables that can be communicated to the user.

Often the same variable will be re-used by multiple tasks, therefore it is possible to declare reusable variables.

Variables can belong to the global scope or a task specific scope. For the global scope, it is mandatory to declare the variable here, in order to avoid conflicting variable definitions.

See variables for the variable-declaration syntax.

<workflowMeta xmlns="http://outerx.org/daisy/1.0#workflowmeta">
  <variables>
    [... some variable declarations ...]
  </variables>
</workflowMeta>

Nodes

For each node in the process definition, some metadata can be specified. Currently this is only the labels for the transitions of each node.

<workflowMeta xmlns="http://outerx.org/daisy/1.0#workflowmeta">
  <nodes>
    <node path="...">
      <transition name="...">
        <label [i18n="true"]>...</label>
      </transition>
      [... more transitions ...]
    </node>
    [... more nodes ...]
  </nodes>
</workflowMeta>

The path attribute of the node element contains the fully qualified node name, which is:

parent node name + "/" + node name

For the common case of a normal top-level node (such as the start node), this means just the node name.

Tasks

For each task in the process definition, some metadata can be specified:

a label and description for each task
the variables that can be updated through this task

For the syntax for declaring variables inside the <variables> element, see variables, this syntax is the same as for the reusable variable declarations.

<workflowMeta xmlns="http://outerx.org/daisy/1.0#workflowmeta">
  <tasks>
    <task name="...">
      <label [i18n="true"]>...</label>
      <description [i18n="true"]>...</description>
      <variables>        
        [... variable declarations ...]
      </variables>
    </task>
    [... more tasks ...]
  </tasks>

</workflowMeta>

Variables

Process variables allow to store state information in process instances. Together with the execution path(s), they are what make one process instance different from another.

In the Daisy Workflow API, variables are updated as part of task interactions. Only the variables declared in the Daisy process metadata are accessible, it is not possible to access other arbitrary variables.

The syntax for declaring a variable is shown below. Everything except for the name and type attributes is optional.

<variable name="..."
          type="string|daisy-link|long|date|datetime|actor|boolean|user"
          scope="task|global"  [optional, default task]
          required="true|false”  [optional, default false]
          readOnly="true|false" [optional, default false]
          hidden=”true|false” [optional, default false]
          base="[name of a reusable variable]">
  <label [i18n="true"]>...</label>
  <description [i18n="true"]>...</description>
  <selectionList>
    [ see details below ]
  </selectionList>
  <initialValueScript>
    [ see details below ]
  </initialValueScript>
  <styling>
    [ see details below ]
  </styling>
</variable>

type attribute

The following table lists the types of process variables supported by Daisy. This means these are the types of variables which can be updated through the Daisy API, and are supported in the Daisy Wiki frontend. Inside the process definitions, variables can be assigned to any type supported by jBPM.

Name	value Java class
string	java.lang.String
daisy-link	org.outerj.daisy.workflow.WfVersionKey
long	java.lang.Long
date	java.util.Date
datetime	java.util.Date
actor	org.outerj.daisy.workflow.WfActorKey
boolean	java.lang.Boolean
user	org.outerj.daisy.workflow.WfUserKey

Below some more information on the Daisy-specific ones

daisy-link

This type of variable points to a Daisy document variant (identified by the triple {documentId, branch, language}). It can optionally point to a specific version of the document variant (identified by a version number or the special values 'live' or 'last').

actor

This type of variable contains an “actor”, which is either a specific user or one or more workflow pools. This type of variable is useful to use in the assignment of tasks (see assignment handler).

user

This type of variable points to a specific user.

Reserved Daisy variables

Daisy defines some preserved context variables which have a special meaning. Their names all begin with "daisy_". The "daisy_" prefix should not be used for naming your own variables.

Variable name	scope	type
daisy_document	global	WfVersionKey
daisy_creator	global	WfUserKey
daisy_owner	global	WfUserKey
daisy_description	global	string
daisy_site_hint	global	string

daisy_document

While it is possible to define as many variables pointing to documents as you desire, the one called “daisy_document” is used to store the primary document with which the workflow is associated.

This variable has influence on the workflow access control.

In the Daisy Wiki, this variable is automatically initialized with the document that was active when starting the workflow.

daisy_description

This variable is used as a description of the workflow process, its value is shown in the various overview lists in the Daisy Wiki.

daisy_owner and daisy_creator

These variables gets automatically initialized by Daisy (with as value the current user) when a process instance is created. The daisy_creator is simply used to remember who created the workflow, and should never be changed. The daisy_owner variable indicates the owner of the process, which is a user who has some additional privileges (see workflow access control). The daisy_owner may be changed after process creation.

daisy_site_hint

If this variable is present on the start state task, the Daisy Wiki will automatically put the name of the current site in it. This is useful in the task notification mails, to add an URL containing the original site name. This variable is usually declared as hidden variable.

scope attribute

In jBPM, variables can be bound to the tokens (the root token or other ones -- note that 'token' is called 'execution path' in the Daisy API) and to tasks. It is possible to have variables with the same name but bound to different scopes.

In the Daisy Workflow API, two variable scopes are supported:

the “global” scope: associates variables with the root token
the “task” scope: associates variables with specific tasks

Variables in with global scope should always be declared as part of the reusable variable declarations and than reused in specific tasks, this to avoid conflicts in types.

base attribute

The base attribute is used to refer to a reusable variable declaration. When using the base attribute, usage of any other attributes is optional. So one can write:

<variable base="myVar"/>

It is however possible to customize the reused variable. The attributes and child elements can be overriden simply by specifying them. For example suppose the reusable variable is non-required, than it can be made required like this:

<variable base="myVar" required="true"/>

hidden attribute

Through the Daisy workflow API, it is only possible to update variables that are declared in the metadata. Sometimes you might which to have a variable programmatically available, without it being visible to the user. In that case the hidden attribute can be used.

It is recommended to make hidden variables non-required (which is the case by default), since the user is not able to enter a value for them.

selectionList element

A selection list allows the user to choose a value from a list instead of having to type it. The syntax for defining a selection list is as follows:

<selectionList>
  <listItem>
   [just one of the following, depending on the
    variable type]
    <wf:string>...</wf:string>
    <wf:date>...</wf:date>
    <wf:dateTime>...</wf:dateTime>
    <wf:long>...</wf:long>

    [an optional label]
    <label [i18n="true"]>...</label>
  </listItem>
  [... more list items ...]
</selectionList>

Note that the value-tags (wf:string, wf:date, etc) are in the “wf” (workflow) namespace, rather than in the workflow metadata namespace. This is because the definition of these elements is shared with other parts of the workflow XML Schema.

As an example, here is (a part of) the selection list of the priority field:

<selectionList>
  <listItem>
    <wf:long>4</wf:long>
    <label i18n="true">variable.priority.low</label>
  </listItem>
  <listItem>
    <wf:long>3</wf:long>
    <label i18n="true">variable.priority.normal</label>
  </listItem>
  <listItem>
    <wf:long>2</wf:long>
    <label i18n="true">variable.priority.high</label>
  </listItem>
</selectionList>

initialValueScript element

The initialValueScript element can contain a script that returns a default value for the variable. This is only relevant for variables associated with the start-state task, since the workflow is then not started yet (defaulting of variables for further tasks can be done inside the process definition).

The script should be written in Javascript and return a value of a type corresponding to the type of this variable. The script has access to the following variables:

contextDocKey: if the workflow is started in the context of a certain document, this variable points to a WfVersionKey object specifying that document (this is the same document that will be put in the daisy_document variable).
repository: the Repository object for the current user
wfRepository: the Repository object for the special workflow user (= a repository with Administrator rights)
repositoryManager: the RepositoryManager, allowing to retrieve any Repository

In case you simply want to initialize a variable with a fixed value, the script can contain just a return statement, for example:

<initialValueScript>
 return "default value";
</initialValueScript>

Initial value scripts however allow to do more interesting things. Here is an example for the “priority” variable that changes the priority according to the document type.

<initialValueScript>
  var priority = new java.lang.Long(3); // 3 is normal priority
  if (contextDocKey != null) {
    try {
      var doc = repository.getDocument(contextDocKey.getVariantKey(), false);
      var docTypeName = repository.getRepositorySchema().
             getDocumentTypeById(doc.getDocumentTypeId(), false).getName();
      if (docTypeName == "News") {
        priority = new java.lang.Long(1); // 1 is highest priority
      }
    } catch (e) {
      // something failed (e.g. no access to document), ignore
    }
  }
  return priority;
</initialValueScript>

Here is an example of initializing an actor-type variable. This example initializes it to contain all pools.

<initialValueScript>
  var pools = repository.getExtension("WorkflowManager").getPoolManager().getPools();
  var poolIds = new java.util.ArrayList(pools.size());
  for (var i = 0; i &lt; pools.size(); i++) {
    poolIds.add(new java.lang.Long(pools.get(i).getId()));
  }
  return new Packages.org.outerj.daisy.workflow.WfActorKey(poolIds);
</initialValueScript>

styling element

The styling element allows to specify styling hints for the frontend. The exact available styling hints and their meaning depends on the frontend, therefore the schema allows any attributes and child content on the styling element, so that it can be flexibly extended.

Currently supported by the Daisy Wiki frontend are:

attribute width: size of the input field (e.g. 10em)
attribute rows: to enable multi-line input (textarea in HTML), its value is the number of rows you want displayed.

Example to display a variable as a textarea:

<styling width=”10em” rows=”3”/>

Comments (0)