Merge fields Custom Filters

Custom filters are specialized functions that allow advanced manipulation of merge field values. They extend the basic merge field functionality by providing domain-specific operations for date/time manipulation, image processing, and content rendering.

Custom filters are organized into several functional areas:

📅 Date and Time Manipulation

The shift_datetime filter provides powerful date and time manipulation capabilities:

Syntax

{{ value|shift_datetime(years=None, months=None, days=None, hours=None, minutes=None, seconds=None, business_days=False) }}

⚙️ Parameters

• value - Reference date/time from which new date/time is calculated
• years - Number of years to shift (integer, positive/negative)
• months - Number of months to shift (integer, positive/negative)
• days - Number of days to shift (integer, positive/negative)
• hours - Number of hours to shift (integer, positive/negative)
• minutes - Number of minutes to shift (integer, positive/negative)
• seconds - Number of seconds to shift (integer, positive/negative)
• business_days - When True with days, excludes weekends (boolean)

📥 Input Value Formats

The value parameter accepts:

• ISO date/time string: "2023-12-25T14:30:00+02:00"
• ISO date string: "2023-12-25" (time defaults to 00:00:00)
• Date/time merge field: {{ record.created_at }}
• Date merge field: {{ record.created_at.date() }}
• New line to HTML
  : {{ record.string_field_with_new_line }}
• Converts JSON string into the python object: {{ record.string_field_with_json }}

💡 Examples

{{ current_date|shift_datetime(days=30) }}
{{ record.start_date|shift_datetime(years=-2, months=-6) }}
{{ current_date|shift_datetime(days=5, business_days=True) }}
{{ "2023-01-15T09:00:00"|shift_datetime(months=3, days=10, hours=2) }}
{{ record.string_field_with_new_line|nl2br }}
{{ record.string_field_with_json|fromjson }}

🌍 Availability

• Document Templates
• Send Message Actor
• Variable Actor
• API Call Actor

Output Format

📝 The shift_datetime filter always returns date in ISO format as local time (without timezone): "YYYY-MM-DD hh:mm:ss"

🖼️ Image Processing

Custom filters for handling images in document fields provide embedded image functionality with dimension control.

🔗 Basic Image Embedding

{{ record.field_<alias>[index].embedded }}

• <alias> - Document field's alias
• [index] - Mandatory array index (0-99, as fields can contain up to 100 attachments)
• embedded - Special property for image embedding

🎨 Supported Image Formats

• PNG
• GIF
• JPEG/JPG

📏 Dimension Control Filters

Control image dimensions using custom filters:

{{ record.field_image[0].embedded|img_width(150)|img_height(100) }}

• img_width(size) - Set image width in millimeters
• img_height(size) - Set image height in millimeters
• size - Dimension in millimeters (integer)

🎯 Examples

{{ record.field_photos[0].embedded }}
{{ record.field_logo[0].embedded|img_width(200) }}
{{ record.field_banner[1].embedded|img_width(300)|img_height(150) }}
{% for i in range(10) %} {{ record.field_gallery[i].embedded|img_width(100) }} {% endfor %}

📐 Ratio Preservation Rules

• No dimensions specified: Original ratio preserved
• One dimension specified: Ratio preserved, other dimension calculated
• Both dimensions specified: Ratio not preserved, exact dimensions applied

⚠️ Error Handling

• Non-image files: Return empty string (silently ignored)
• Unsupported formats: Return empty string (silently ignored)
• Missing index: Return empty string
• Invalid parameters: Standard Jinja filter error handling

📄 DOCX embedding

Custom filters for handling .docx files in document fields provide embedded document functionality with preserved formatting.

🔗 Basic DOCX Embedding

{{ record.field_<alias>[index].embedded }}

• <alias> - Document field's alias
• [index] - Mandatory array index (0-99, as fields can contain up to 100 attachments)
• embedded - Special property for document embedding

Supported Formats

• DOCX (Microsoft Word OpenXML format)

⚠️ Other file formats are ignored and return an empty string.

Examples

{{ record.field_contract[0].embedded }}
{{p record.field_appendix[1].embedded.inline }}
{% for i in range(5) %} {{ record.field_documents[i].embedded }} {% endfor %}

📝 Formatting Preservation

• Inserted .docx documents retain their original formatting (styles, headings, fonts).
• No manual overrides or filter-based formatting changes are available.
• Merging is powered by the docxtpl library.

Merge Syntax Variants

Two syntaxes are supported, with slightly different behaviors:

• Standard merge syntax (consistent with image embedding)

{{ record.field_<alias>[index].embedded }}

• Paragraph-replacement syntax (docxtpl standard)

{{p record.field_<alias>[index].embedded.inline }}

Replaces the entire paragraph with the merged document content.

📌 Behavioral difference

Template:

This is example line in document.
Second line, where document should be merged {{ record.field_doc[0].embedded }}.

• Result using

{{ record.field_<alias>[index].embedded }}

This is example line in document.
Second line, where document should be merged
[Content of merged document].

• Result using

{{p record.field_doc[0].embedded.inline }}

This is example line in document.
[Content of merged document]

⚠️ Error Handling

• Non-DOCX files: Return empty string (silently ignored)
• Unsupported formats: Return empty string (silently ignored)
• Missing index: Return empty string
• Invalid parameters: Standard Jinja filter error handling

📝 Merge Field Rendering

The render_merge_fields filter enables dynamic merge field processing within string content, allowing nested merge fields to be resolved and rendered at runtime.

🎯 Purpose

This filter processes merge fields that are stored as content within other fields, enabling dynamic template rendering where merge field references are embedded in text values.

📝 Syntax

{{ record.field_name|render_merge_fields }}

🌍 Availability

The filter is supported in all features that allow merge fields:

• API Call Actor
• Send Message Actor
• All AI Actors
• Local Variable Actor
• Document Templates

⚙️ How It Works

When a merge field with render_merge_fields filter is processed:

1. Retrieves the content of the field
2. Identifies any merge fields within that content
3. Replaces nested merge fields with their actual values
4. Returns the fully rendered string

💡 Complete Example

Database field content (record.field_prompt):

Generate a professional legal contract clause based on the following terms and conditions fields:
- Payment Terms {{record.field_payment_terms}}
- Acceptance Clause {{record.field_acceptance_clause}}
- Duration {{record.field_duration}}
- Effective Date {{record.field_effective_date}} Ensure the clause is structured formally, aligns with standard legal practices, and accounts for potential risk mitigation. Use clear, precise legal language.

Template usage:

{{record.field_prompt|render_merge_fields}}

Rendered output:

Generate a professional legal contract clause based on the following terms and conditions fields:
- Payment Terms Net 30 Days: (Payment is due within 30 days from the invoice date.)
- Acceptance Clause Acceptance pending
- Duration 01/05/2027
- Effective Date 15/04/2025 Ensure the clause is structured formally, aligns with standard legal practices, and accounts for potential risk mitigation. Use clear, precise legal language.

🔗 Supported Merge Field Types

The filter supports all standard merge field types:

• Basic fields: {{record.field_name}}
• Relational fields: {{record.related_records_1.0.field_name}}
• System fields: {{admin_first_name}}
• Constants: {{constants.API_URL}}

⚠️ Processing Rules

• Single-level processing: Non-recursive to prevent infinite loops
• Second-level limitation: Using |render_merge_fields inside nested content returns the raw string
• Field type restriction: Only works with string field types
• Non-string fields: Filter is ignored, returns original field value

🚫 Error Handling

• Invalid nested merge fields: Return empty string (standard handling)
• Non-supported filters: Standard merge field error returned
• Non-string field types: Filter ignored, original value returned

🎯 Use Cases

{{ record.email_template|render_merge_fields }}
{{ record.ai_prompt_template|render_merge_fields }}
{{ record.api_request_template|render_merge_fields }}
{{ record.contract_template|render_merge_fields }}

Recursion Prevention

🔄 The filter processes only one level of merge fields to prevent infinite loops. Nested render_merge_fields calls will return the raw string value.

Dynamic Templates

✨ This filter is particularly powerful for creating dynamic templates where the template structure itself is stored in database fields and can be modified by users.

🔧 Usage Contexts

Custom filters are available in:

• Document Templates (Templates panel)
• Sequence Actors: Send Message, Variable, API Call
• Doc Auto Actor (for image embedding)
• Standard document generation workflows

Index Requirement

⚠️ Image merge fields require the [index] parameter. Omitting it will return an empty string.

Template Integration

🎨 Image merge fields integrate seamlessly with the Templates panel for standard document generation workflows.