Overview
Expressions in Kodexa allow you to dynamically set values for data elements using Groovy scripting. Instead of extracting values directly from documents, expressions calculate or derive values programmatically based on document properties, metadata, or other data elements.
When to Use Expressions
Use expressions when you need to:
Calculate values based on other data elements (e.g., totals, percentages)
Transform extracted data (e.g., formatting dates, concatenating strings)
Apply business logic to determine values
Access document metadata or properties
Create conditional values based on document content
Creating an Expression Data Element
Step 1: Configure the Data Element
Open your Data Definition in the workspace
Create or select a data element
In the Overview tab, configure:
Name - The display name for this data element
Description - Describe what this expression calculates
Source - Select "Expression" from the dropdown
Data Type - Choose the type of value returned (String, Number, Date, etc.)
Step 2: Write the Expression
After setting Source to "Expression", an Expression tab appears where you can write your Groovy code:
Click the Expression tab
Write your Groovy expression in the code editor
The expression should return a value matching your selected Data Type
Expression Editor Features
Syntax Highlighting - Groovy code is highlighted for readability
Full Screen Editing - Large editor area for complex expressions
Auto-Save - Changes are saved automatically
AI Generation - Use the "Generate Expression" button in Overview tab to create expressions from your description
Groovy Expression Basics
Simple Calculations
// Calculate total from subtotal and tax subtotal + tax// Calculate percentage (value / total) * 100// Concatenate strings firstName + " " + lastName
Accessing Data Elements
Reference other data elements in your expression:
// Access a sibling field
document.getFieldValue("fieldName")// Check if a field exists
document.hasField("fieldName") ? document.getFieldValue("fieldName") : "N/A"
Conditional Logic
// Return different values based on conditions
if (amount > 1000) {
"High Value"
} else if (amount > 100) {
"Medium Value"
} else {
"Low Value"
}
Date Manipulation
// Format a date
new Date().format("yyyy-MM-dd")// Calculate date differences
(endDate - startDate).days
Working with Metadata
// Access document filename document.metadata.filename// Access document creation date document.metadata.createdDateTime// Access document status document.metadata.documentStatus
AI-Generated Expressions
You can use AI to generate expressions automatically:
In the Overview tab, write a clear description of what you want to calculate
Click the Generate Expression button
The AI creates a Groovy expression based on your description
Review and modify the generated expression as needed
The expression appears in the Expression tab
Tip: Be specific in your description. For example: "Calculate the total by adding subtotal and tax fields" or "Return the due date which is 30 days after the invoice date".
Expression Data Types
Choose the appropriate data type for your expression's return value:
String - Text values, concatenations, formatted output
Number - Numeric calculations, counts, sums
Currency - Monetary calculations (formatted with currency symbol)
Date - Date calculations or transformations
Date Time - Date and time calculations
Boolean - True/false logic results
Percentage - Percentage calculations (formatted with %)
Common Expression Patterns
Calculate Total
// Sum multiple fields subtotal + tax + shipping
Format Currency
// Format number as currency
String.format("$%.2f", amount)
Generate Identifiers
// Create unique reference number
"INV-" + new Date().format("yyyyMMdd") + "-" + invoiceNumber
Conditional Assignment
// Assign priority based on amount amount > 10000 ? "High" : amount > 1000 ? "Medium" : "Low"
Extract from Filename
// Get customer ID from filename
document.metadata.filename.split("-")[0]
Validating Expressions
Ensure your expressions work correctly:
Test with Documents - Process documents to verify expression results
Handle Nulls - Check if fields exist before accessing them
Match Data Types - Ensure the returned value matches your selected type
Use Try-Catch - Handle potential errors gracefully
Expression vs Other Sources
Expression vs Formula
Expression - Full Groovy scripting with complex logic
Formula - Simplified formula syntax for calculations
Expression vs External
Expression - Calculated from internal document data
External - Retrieved from external APIs or databases
Best Practices
Keep It Simple - Break complex logic into multiple data elements
Add Comments - Document what your expression does
Handle Errors - Check for null values and provide defaults
Use Descriptive Names - Name data elements clearly for easy reference
Test Thoroughly - Verify expressions with various document types
Use AI Generation - Start with AI-generated code and refine as needed
Tips
Expression code is written in Groovy language
Reference other data elements by their field names
Use the Description field to help AI generate accurate expressions
Expressions are evaluated when documents are processed
The code editor provides syntax highlighting for easier editing
Changes are saved automatically as you type