This guide explains how to define expressions in the Kodexa platform to set values for data elements using Spring Expression Language (SPEL). The "Expression" tab, as shown in the screenshot, provides users with a way to dynamically define and manipulate data element values.
What Are Expressions?
Expressions in Kodexa allow you to define dynamic values for your data elements based on the properties of documents, metadata, or parent objects. These expressions are written using Spring Expression Language (SPEL), which provides a powerful syntax for evaluating and manipulating data at runtime.
Key Features of SPEL in Kodexa
Variables
Several variables are available in the context of a Kodexa expression:
dataObject: The current data object for which the expression is evaluated.attribute: The attribute being processed within the data object.document: The document associated with the data object.metadata: A map of metadata associated with the document.family: The document family to which the document belongs.
Example:
#dataObject.parent
This retrieves the parent object of the current data object.
Accessing Metadata
You can access document metadata using the metadata variable. For example:
#metadata['author']
This retrieves the author metadata value from the document.
Mathematical Operations
Perform calculations dynamically:
#attribute.value + 10
This adds 10 to the current attribute's value.
String Manipulation
Manipulate string values:
#document.title.toUpperCase()
This converts the document title to uppercase.
Conditional Logic
Add conditional logic directly into the expression:
#dataObject.value > 100 ? 'High' : 'Low'
This assigns High if the value is greater than 100, otherwise assigns Low.
Steps to Define an Expression in Kodexa
Navigate to the Expression Tab
Open the "New Data Element" configuration.
Click the "Expression" tab, as shown in the screenshot.
Write Your Expression
Enter your SPEL expression in the input box provided under the "Expression" field.
Ensure the expression is valid SPEL syntax.
Use Available Context Variables
Reference the
dataObject,metadata, or other variables as required.Example: To calculate a field based on a metadata field:
#metadata['creationDate'].year + 5
Validate the Expression
Kodexa evaluates the expression in real time. If there are any errors, they will be logged in the backend, and you can adjust accordingly.
Behind the Scenes: How Kodexa Resolves Expressions
Expressions are parsed and evaluated using the following logic:
Context Setup A context is created for the data object, and variables such as
dataObject,document, andmetadataare added.Parsing Kodexa uses the
SpelExpressionParserto parse the user-defined expression.Evaluation The parsed expression is evaluated against the provided context. For example:
EvaluationContext context = new StandardEvaluationContext(dataObject); Expression exp = parser.parseExpression(expression); Object result = exp.getValue(context);
Error Handling If an error occurs during evaluation, a
DataExceptionis logged, and the attribute's value may remain unset.
Best Practices
Always validate expressions before saving.
Use conditional logic to handle null or missing values.
Keep expressions simple for better readability and maintainability.
Reference metadata and context variables appropriately to leverage dynamic data.
Example Expressions
Example 1: Accessing Metadata
#metadata['author']
Fetches the author metadata from the document.
Example 2: Conditional Formatting
#attribute.value != null ? #attribute.value.toUpperCase() : 'Default'
Converts the value to uppercase if it exists, otherwise assigns Default.
Example 3: Nested Property Access
#dataObject.parent.getChild('summary').valueFetches the value of a child data object named summary.
Example 4: Date Manipulation
T(java.time.LocalDate).now().toString()
Sets the attribute's value to the current date.
By understanding and utilizing SPEL in Kodexa, you can create powerful, dynamic data mappings and transformations. For further assistance, contact the Kodexa support team or refer to the official SPEL documentation.