Expressions are executed when guards are evaluated, when they are nested in actions, and for other configurable computations. Like actions, expressions are typically executed in the context of a task, but may occasionally be executed in the context of a process.

The main method of an expression is evaluate(WorkflowObject,Map<String,Object>), which receives as arguments the workflow object in which the expression is evaluated and a number of local properties. These properties must not be confused with the variables present in the workflow object or its view. Instead, the properties are purely local to the expression, without any form of persistence. They are typically set in the predefined expressions Let, Exists, or ForAll.

If an expression modifies the given map, it should make sure to return it to its previous state before returning from the evaluate method. Preferably, this is done in a try/finally construction.

Please see the Javadoc for more details regarding the data types that are permitted as return values of the expression and for the parameter map.

If you are creating an expression that will only return Boolean values, you can implement the interface BooleanExpression. Thereby you indicate the reduced set of return values and make your expression usable in a greater number of contexts, in particular in guards and as a subexpression of predefined Boolean connectives.

Mixing Unified API and WfAPI Expressions

You can include Unified API expressions and WfAPI expressions in one process definition. This allows a stepwise migration of existing plugins to the new APIs. You may even use, for example, old-style expressions as subexpressions of Unified API expressions. In this case, the expressions are automatically wrapped so that they appear as objects of the API that is used by the containing object. The wrappers will take care of converting argument values and return values when calling methods of the wrapped expression.

When using Unified API expression inside WfAPI actions, care has to be taken with respect to the correct treatment of null values. Because the WfAPI uses typed nulls and the Unified API expressions may return an ordinary Java null, a special subtype of WfValue has been introduced to the WfAPI: NullValue.

This value should not be used when working purely inside the WfAPI. Only when a Unified API expression returns a null and when that value must be propagated to a WfAPI action or expression, the above mentioned wrapper objects convert the value to a NullValue. Of course a plugin that was written for CoreMedia CMS 2005 or earlier may not expect a value of that type, possibly failing during a type cast. Therefore, existing plugin implementations may have to be hardened against the new value type NullValue, before you can use them with Unified API subexpressions.

Note that it is often desired to port the entire set of plugins to the new API anyway, so that this paragraph applies to a few specific cases, only. It is possible to use the built-in actions and expressions without restrictions. They will neither produce untyped nulls nor misbehave when they come across a NullValue.