Spring Expressions

Flex Actions and  plugins, Run Rules for Wizards and Actions and Event Handlers make use of runtime Expressions to dynamically modify behavior, for example you can use an expression to parse workflow variables to an action or evaluate a result for a run rule.

Dalet Flex supports the use of Spring Expression Language (SpEL). The same objects available in the JBPM context are also available in the Spring context, and thus can be used for Spring expressions as well. In newer versions of Dalet Flex, you should use SpEL. JEF plugins require the use of SpEL, while traditional plugins have traditionally used Expression language (EL) (however, most do support SpEL as well). Generally, SpEL will work for traditional and JEF plugins. However, regular expressions will not work for JEF plugins, so wherever possible use SpEL.

The main point of difference between SpEL and EL is the syntax, SpEL must start with#{and end with}. When Spring expressions are enabled, you must use#instead of$.

NOTE:

• Event handlers can only be configured using SpEL
• Objects in the expression language are based on the internal Dalet Flex object model, and not the B2B API model
• See the official Spring Expression guide for more information. This guide focuses on the advanced features of the Spring expression language.
• For workflow variables, you must use the syntax#{variables['<variable name>']}instead of${variables.<variable name>}
• If applicable, you can combine SpEL with EL in different fields 

Expressions for Actions and Run Rules

You use expressions when configuring actions and run rules for wizards and actions.

The properties/fields available for use in expressions depend on the Java object backing the expression being evaluated. You can check the objects available by querying the internal Dalet Flex object model. For example, for a run rule for a job, valid objects are those available in the context of the job object.

Examples of Expressions for run rules and actions

The following is a partial list of examples of generic expressions that can be used in action configurations and run rules for actions and wizards.

Examples of Run Rules for Wizards and Actions

Run rules typically evaluate to a parameter related to the context. For example, a run rule can be applied to a wizard so that the wizard is only displayed for a particular asset type or based on the value of a particular field. The wizard is only dispalyed if the expression evaluates to true. Similarly, you can apply a run rule to an action so that the action only runs if the expression evaluates to true.

The following is a list of real life examples of expressions  used in run rules in wizards/actions. You must adapt your expressions for your environment.

Spring Expressions for Event Handlers

You can ONLY use SpEL for configuring expressions for event handlers. You use Spring expressions to filter for events with specific values, or to ensure event handlers only run when certain fields are present. 

You can also use expressions in configuration fields present in particular types of event handlers, for example for a Job Executor event handler.

Event objects have different structures, depending on the event type. E.g. A metadata modified event has a different structure to a password reset event structure. This means that writing an event handler expression is more complicated due to the plethora of different events and event data. Use a GET call to the REST API using an eventID to retrieve the event details and retrieve the event.json and view all available objects for that event.

Below is a non-exhaustive set of event fields and sub-fields accessible via Spring expressions. You should also be able to access most other fields present in the full JSON representation of the event. To do this, build out the expression as in the below examples, starting with the top leveleventand adding each layer on the path to the field in question. Each layer on the path corresponds to each layer of data in the JSON event.

For example, consider the following JSON:

{
  "event": {
    "object": {
      "id": 123
    },
    "anotherField": "someValue"
  }
}

If you wanted to match against the value of theidfield, you would start atevent, addobject, and end inid, giving you the pathevent.object.id. You could then use this path in a Spring expression like so:#{event.object.id == 123}, or#{event.object!=null&&event.object.id == 123}to be null-safe (more information at the bottom of the page).

If you wanted to match against the value ofanotherField, you could follow the same process to build the path to the field you would like to target; in this case, the path would beevent.anotherField, which could then be used in a Spring expression like#{event.anotherField!=null&&event.anotherField.startsWith("some"}. This expression would return match against all events with ananotherFieldvalue beginning with “some”.

Selected event fields and examples for different event objects

Asset fields

Object fields

Object type fields

User fields

Metadata fields

Create expressions that reference values in metadata fields in the metadata instance associated to the object that the event is generated for.

Event data

Event data – the section of the event containing data specifically tied to the event type – can be accessed using a method calledgetDataValue, like so:event.getDataValue("someEventDataField").get().

It is often the case that users would like to filter events based on the content of nested event data fields. This occurs, for example, when checking the value of a taxonomy field change. Consider the following event data JSON snippet:

{ 
  "eventData": [
      {
          "name": "asset-status",
          "value": "{\"mode\":\"updated\",\"before\":\"Rejected\",\"after\":\"Approved\"}",
          "type": "JSON"
      }
  ]
}

Here, the event datavaluefield contains escaped, nested JSON. Let’s assume that the requirement is to only run the event handler whenafterequalsApprovedin thevaluefield’s nested JSON. Unfortunately, we cannot access these fields using a path like we do other fields in the event (likeevent.object.id,event.asset.displayName, etc). Instead, we can use regex to target String values contained in thevaluefield. For the above example, that would look like this:#{event.getDataValue("media-status").get().value.matches("(.*)after(.*):(.*)Approved(.*)")}. The(.*)statements allow us to sidestep the issue of the escaped quotation marks, but they do so at the potential cost of reducing the precision of the regex. If using such an expression, be sure to test the event handler to make sure it behaves as expected in all scenarios.

Examples of Filters for Event Handlers

Technical notes

• To prevent null pointer exceptions (NPE) in the logs, you can add a null check to the expressions to ensure that that the field is not null before continuing. The null check in the event examples above is added using event.object != null && to the expression.
• SpEL provides many convenience methods for collections (lists, sets, maps, etc). You can use these convenience methods when targeting event fields that are collections, such as external IDs, placed media regions, and so on. There are some usage examples on this page, but you can also refer to the official Spring documentationfor more advanced functionality in this area.