the “dollar notation”

Many of the examples of OpenWFEru process definition, Ruby or XML, feature some ‘dollar notation’.

A long time ago (2002), OpenWFE had no dollar notation, but already featured ways to extract values from fields or variables.

    <sequence>
        <participant field-ref="customer" />
        <participant variable-ref="customer" />
    </sequence>

With the dollar notation, this XML process definition can also be written as :

    <sequence>
        <participant ref="${f:customer}" />
        <participant ref="${customer}" />
    </sequence>

(The original documentation about the ‘dollar notation’ may still be found in the old OpenWFE Manual).

It doesn’t look much different in a Ruby process definition :

    sequence do
        participant :ref => "${f:customer}"
        participant :ref => "${customer}"
    end

or even :

    sequence do
        participant "${f:customer}"
        participant "${customer}"
    end

More examples :

    sequence do

        participant "${f:customer}"
        participant "${field:customer}"
            #
            # the participant name is in a workitem field (attribute) named 'customer'

        participant "${customer}"
        participant "${v:customer}"
        participant "${variable:customer}"
            #
            # the participant name is in a variable named 'customer'

        participant "${/customer}"
        participant "${v:/customer}"
        participant "${variable:/customer}"
            #
            # the participant name is in a variable named 'customer' bound at
            # the root of this process instance (or at the engine level)

        participant "${//customer}"
        participant "${v://customer}"
        participant "${variable://customer}"
            #
            # the participant name is in a variable named 'customer' bound at
            # the engine level
    end

Nesting dollar notations is permitted :

        participant "${customer_${f:index}}"

Aggregation as well :

        participant "${customer}__${customer_dept}"

The ‘dollar notation’ with arrays and hashes

The examples so far dealt with flat structures : the desired value was immediately at hand. What if it’s a bit further ?

    #
    # we have a workitem that looks like this :
    #
    workitem.customers = [ 
        { :name => "Alfred", :region => "Queensland" }, 
        { :name => "Berth", :city => "Palo Alto" }
    ]

This is possible :

    participant "${f:customers.0.name}" # for Alfred

    set :field => customer, :value => "${f:customers.1.name}"

The concepts in the next paragraph can also be used to extract values out of more complex structures.

The ‘dollar notation’ and Ruby code evaluation

OpenWFE Java had functions, but instead of reimplementing them for OpenWFEru, direct evaluation of Ruby code got added instead.

But by default, an engine will not evaluate ruby code found in the dollar notation. To enable it, you have to explicitely set the :ruby_eval_allowed parameter to true in the engine’s application context :

    engine.application_context[:ruby_eval_allowed] = true

(the expression reval is also affected by this parameter, as well as the condition attributes like “rif”, “rtest” and so on)

Beware of untrusted ruby code.

Once the parameter is set to true, it’s possible to write things like :

    <sequence>
        <set field="now" value="${ruby:Time.now.to_s}" />
        <participant ref="${r:'toto'.reverse}" />
        <set field="balance" value="${r:wi.credit - wi.debit}" />
    </sequence>

Future releases of OpenWFEru will provide a enhanced security model, the OpenWFEru team hopes that Ruby will feature standard sandboxing mechanism in the near future and will incorporate them ASAP.