...

The participant expression not only accepts the 'ref' attribute, you can also use the 'field-ref' or the 'variable-ref' attributes, like their names imply, they seek their values in the fields of the incoming workitem or in the variables available in the current scope.

    <sequence>
        <participant field-ref="__target__" />
        <participant variable-ref="vtarget" />
    </sequence>

The first participant in the example references a participant whose name is stored in the field named '__target__' of the workitem as it reaches the participant expression. The second participant will seek its reference in the content of the variable named 'vtarget'. See the 'set' expression and the iterators to learn how to get variables to work for you.

    <participant ref="${field:toto}_${index}" />

This last example combines a field reference and a variable reference without using 'field-ref' neither 'variable-ref'. This dollar notation is available to all expressions, not only to the participant expression.

Nested dollar notations are possible :

    <set variable="i" value="3" />
    <set field="sum" value="${i} + ${i} = ${c:sum('${i}', '${i}')}" />

will yield the value "3 + 3 = 6" in the field named "sum".

Setting the attribute 'forget' of the participant expression will make the engine resume the flow immediately, the workitem will be sent to the participant but the engine will not care about any reply. This may be very useful for sending simple messages (still workitems though) to participants (like notifications or reminders).

    <participant ref="role-alpha" forget="true" />

As OpenWFE processes have tokens in the form of workitems, sometimes the payload of these items are worth a higher degree of control. A workflow definition may include as many filter definition as desired. A filter definition should be detailed after the body of the main flow and the bodies of the subprocesses.

    <filter-definition name="closed-1" type="closed" add="false" remove="false">
        <field regex="writable" permissions="rw" />
        <field regex="readonly" permissions="r" />
        <field regex="hidden" permissions="" />
    </filter-definition>

This filter named 'closed-1' is closed (everything that isn't explicitely allowed is not permitted), adding and removing fields are not allowed either and it sets permissions on three fields. These are designed with a regex (regular expression) so that

        <field regex="input_.*" permissions="rw" />

Means that all fields beginning with "input_" are readable and writable, so 'field' does mean setting the permissions on just one field only if the regex is a 'flat' one (no *, ., +, whatever).

To have any effect, a filter must be bound to a participant. This is done with the 'filter' attribute of the participant expression.

    <sequence>
        <participant ref="first-reviewer" filter="review-filter" />
        <participant ref="second-reviewer" filter="review-filter" />
        <participant ref="third-reviewer" />
        <participant ref="publisher" filter="publish-filter" />
    </sequence>

In this example flow, the 2 first reviewers receive filtered workitems, but not the 3rd one. The publisher also receives a filtered workitem, but another filter will 'control' it.

When dispatching a workitem to a participant with a filter set, the OpenWFE engine takes care of keeping a copy of the workitem. It then dispatches a mangled copy of the workitem where the hidden fields have been removed. When the workitem comes back from the participant, the engine 'enforces' the filter : cancelling any unallowed modification.

When dispatching, a copy of the filter is also sent in the payload of the workitem so that the worklist (then client) or apre handling the workitem is able to enforce / use the filter too. For example, the generic OpenWFE webclient takes care to show in read-only mode (no input field) read-only fields.

The 'participant' expression also allows you to route workitems to participants determined at runtime.

    <participant 
        default-ref="alice" 
        field-ref="__target__"
    />

This example will route workitems to the participant whose name can be found in the workitem field named '__target__'. If this field is not present, the workitem will be dispatched to the participant 'alice'.

OpenWFE 1.5.2 introduces a new 'else-ref' attribute for the participant expression. Whenever dispatching to the regular participant fails, the participant listed int the 'else-ref' attribute are probed successively until delivery to one of them is successful.

Of course, you can also take advantage of the 'dollar notation' with the 'else-ref' attribute.

    <participant 
        ref="${watermark-agent}"
        else-ref="${failover-watermark-agent}, admin"
    />

Participant names are separated by commas. You could have a function returning such a list or a field containing such a list.

    <participant 
        ref="${watermark-agent}"
        else-ref="${call:determineFailoverAgents()}"
    />
    <participant 
        ref="${db-insertion-agent}"
        else-ref="${field:alternate-agents}"
    />

If nothing is specified, the newly launched subflow will use a copy of the workitem used by the parent flow. You can use the 'fields' attribute to the 'subprocess' expression to specify which fields from the 'parent workitem' should be copied / passed to the 'sub workitem'.

    <subprocess ref="review" fields=""/>

will launch the subprocess 'review' with a workitem that has no fields at all.

    <subprocess ref="check_issue" fields="field_echo, field_fox"/>

will launch the subprocess 'check_issue' with a workitem containing two fields : 'field_echo' and 'field_fox', copied from the parent workitem.

    <subprocess ref="resolve_issue" fields="issue_${i}_.*"/>

given that the variable 'i' is set to 4, then all fields starting with 'issue_4_' will be copied to the sub workitem.

    <subprocess ref="do_the_job" fields="alpha as f_bravo, bravo as f_alpha"/>

in this example, the sub workitem will have two fields 'f_bravo' and 'f_alpha', swapped from 'alpha' and 'bravo' fields of the parent workitem.

    <subprocess ref="sub_zero" fields="f1=(${field:customer_name})"/>

looks complicated, but this 'f1' field will receive as value the name of the customer surrounded by parenthesis. This '=' notation has a drawback : it only generates fields with string values. The 'as' notation copies field whatever type they have.

You can bind variables as parameters of a subprocess call :

    <sequence>

        <participant ref="role-charly" />

        <subprocess ref="review">
            <set variable="reviewer1" value="role-alpha" />
            <set variable="reviewer2" value="role-bravo" />
        </subprocess>

    </sequence>

    <!-- activity definitions -->

    <process-definition name="review">
        <concurrence>
            <participant ref="${reviewer1}" />
            <participant ref="${reviewer2}" />
        </concurrence>
    </process-definition>

The variables will be bound only for the instance of the subprocess triggered by the subprocess call.

Attributes of the 'subprocess' tag are also passed as variables of the subprocess :

    <sequence>

        <participant ref="role-charly" />

        <subprocess 
            ref="review" 
            rev1="role-alpha" 
            rev2="role-bravo"
        />

    </sequence>

    <!-- activity definitions -->

    <process-definition name="review">
        <concurrence>
            <participant ref="${rev1}" />
            <participant ref="${rev2}" />
        </concurrence>
    </process-definition>

There is an elegant way of calling a subprocess :

    <sequence>

        <participant ref="role-charly" />

        <review />

    </sequence>

    <!-- activity definitions -->

    <process-definition name="review">
        <concurrence>
            <participant ref="role-alpha" />
            <participant ref="role-bravo" />
        </concurrence>
    </process-definition>

Of course, this is possible :

    <sequence>

        <participant ref="role-charly" />

        <review
            rev1="role-alpha" 
            rev2="role-bravo"
        />

    </sequence>

    <!-- activity definitions -->

    <process-definition name="review">
        <concurrence>
            <participant ref="${rev1}" />
            <participant ref="${rev2}" />
        </concurrence>
    </process-definition>

(beware, you should not use attributes like 'ref' or 'forget', they are reserved for the underlying subprocess ref expression).

Warning : flows using this notation will fail XSD validation.