Overview

Advanced Settings provide fine-grained control over how data elements behave in your Data Definition. These settings allow you to define fallback values, customize serialization, control editability, and enable multiple values for a single field.

Accessing Advanced Settings

To configure advanced settings for a data element:

Open your Data Definition
Select the data element you want to configure
Navigate to the Advanced tab
Enable and configure the settings you need

Available Advanced Settings

1. Enable Fallback Expression

Define a default value or calculation when the data element is not present in the document.

When to use:

Provide default values for optional fields
Calculate fallback values from other elements
Use metadata when document data is missing
Ensure required fields always have a value

How it works:

Enable the "Enable Fallback Expression" checkbox
A Groovy code editor appears
Write an expression that returns the fallback value
Expression executes only if the field is empty or missing

Available variables:

attribute - The current data element
document - The document being processed
metadata - Document metadata (filename, upload date, etc.)
family - The document family

Example expressions:

Set a static default:

"Default Value"

Use metadata with fallback:

metadata['author'] ?: 'Unknown Author'

Reference document family:

family.name ?: 'General'

Use current date as fallback:

new Date()

Calculate from other fields:

attribute.parent?.children?.find { it.name == 'defaultValue' }?.value

2. Enable Serialization Expression

Define custom formatting rules for how data is serialized when exported to JSON, XML, CSV, or other formats.

When to use:

Format values for specific export requirements
Transform data before external integration
Normalize values for consistency
Apply business logic during export

How it works:

Enable the "Enable Serialization Expression" checkbox
A Groovy code editor appears
Write an expression that transforms the value
The expression receives the raw value as #value
Return the transformed value

Example expressions:

Convert to uppercase:

#value.toUpperCase()

Format numeric values:

String.format('%.2f', #value)

Append suffix:

#value + "_normalized"

Format date:

#value.format('yyyy-MM-dd')

Trim whitespace:

#value.trim()

Replace characters:

#value.replaceAll('[^0-9]', '')

3. Multivalue

Enable storage of multiple values for a single field.

When to use:

Fields requiring lists or collections
Multiple email addresses or phone numbers
Tags or keywords
Categories or classifications

How it works:

Enable the "Multivalue" checkbox
The field stores an array of values instead of a single value
AI can extract multiple instances
Forms allow adding/removing values

Note: Not available for group elements.

Example use cases:

Email addresses: ["[email protected]", "[email protected]"]
Tags: ["urgent", "billing", "review"]
Categories: ["electronics", "computers", "laptops"]

4. User Editable

Control whether users can modify this field's value through forms.

When to use:

Fields requiring manual user input
Values that may need correction
Additional information not in the document
User annotations or notes

When NOT to use:

Calculated fields (formulas)
System-generated values
Audit or tracking fields
Fields that should remain as extracted

How it works:

Enable the "User Editable" checkbox
Field becomes editable in data forms
Users can click to modify the value
Changes are tracked in revision history

5. Not User Labelled

Hide this field from user-customizable labels.

When to use:

System fields not relevant to end users
Internal tracking or metadata fields
Technical fields used only by integrations
Fields that would clutter the user interface

How it works:

Enable the "Not User Labelled" checkbox
Field is hidden from label selection interfaces
Value is still stored and available programmatically
Reduces UI complexity for end users

Best Practices

For Fallback Expressions

Keep it simple - Complex expressions can impact performance
Handle null cases - Use ?: operator for safe defaults
Test thoroughly - Verify fallbacks work with various document types
Document the logic - Add comments in complex expressions

For Serialization Expressions

Validate output - Ensure transformed values meet format requirements
Maintain data type - Return appropriate type for the field
Consider performance - Complex transformations may slow exports
Test edge cases - Verify behavior with null, empty, or unusual values

For Multivalue Fields

Use sparingly - Each multivalue field increases storage overhead
Set clear expectations - Document when multiple values are appropriate
Consider alternatives - Sometimes repeating groups are more appropriate

For User Editable Fields

Be selective - Only enable for fields that truly need editing
Add validation - Ensure edited values meet requirements
Track changes - Use revision history to audit modifications
Set permissions - Control who can edit sensitive fields

Common Patterns

Default to Current Date

// Fallback Expression
new Date()

Use Filename as Document ID

// Fallback Expression
metadata['filename']?.replaceAll('\\.[^.]+$', '')

Normalize Phone Numbers

// Serialization Expression
#value.replaceAll('[^0-9]', '')

Format Currency

// Serialization Expression
String.format('$%.2f', #value)

Trim and Normalize Text

// Serialization Expression
#value.trim().replaceAll('\\s+', ' ')

Convert to Title Case

// Serialization Expression
#value.split(' ').collect { it.capitalize() }.join(' ')

Performance Considerations

Expression Complexity

Simple expressions execute quickly
Avoid loops and recursive operations
Minimize external lookups or API calls
Test with large document sets

Multivalue Impact

Increases storage requirements
More complex indexing and searching
Slower form rendering with many values
Consider limits on maximum values

Serialization Load

Executed during every export operation
Complex transformations slow bulk exports
Consider caching transformed values
Profile performance with production data volumes

Benefits of Advanced Settings

Data Integrity - Enforce consistency through fallbacks and normalization
Automated Cleanup - Serialization expressions clean data automatically
Integration Ready - Format data to meet external system requirements
User Control - Balance automation with manual oversight
Audit Compliance - Maintain data standards for regulatory needs
Flexibility - Adapt to varying document formats and requirements

Groovy Expression Reference

Common Operators

?: - Elvis operator (safe default): value ?: 'default'
?. - Safe navigation: object?.property
+ - Concatenation: 'hello' + ' world'
== - Equality: value == 'test'

String Methods

toUpperCase() - Convert to uppercase
toLowerCase() - Convert to lowercase
trim() - Remove leading/trailing whitespace
replaceAll(pattern, replacement) - Replace text
split(delimiter) - Split into array

Collection Methods

find { condition } - Find first matching element
findAll { condition } - Find all matching elements
collect { transformation } - Transform each element
join(delimiter) - Join array into string

Tips

Advanced settings are optional - use only when needed
Both fallback and serialization use Groovy expressions
Test expressions with sample data before deploying
Use the safe navigation operator (?.) to prevent null errors
Multivalue is useful for tags but consider repeating groups for structured data
User Editable is helpful for fields requiring human judgment
Not User Labelled keeps technical fields out of user interfaces
Document your expressions with comments for future maintainability
Profile performance with realistic data volumes

Introducing Data Definitions

Defining your Data

Working with External Data

Review Templates

Using Expressions