│ Grooper Help - Version 25.0
25.0.0017 2,127
  • Overview
  • Help Status

Data Model Expression Builder

Grooper.Core

Foundation for all dynamic code expressions that access Data Elements in a Data Model.

Remarks

Overview

The Data Model Expression Builder is the compilation engine that powers all code expressions which reference Data Elements within a Data Model. It provides the infrastructure for compiling, caching, and executing custom logic that interacts with document data, supporting a wide range of Grooper features such as field calculations, validations, data rules, and export mappings.

Below are a few examples of how these expressions are used:

  • Field Calculations:
    Compute values for Data Fields using formulas that reference other fields, parent data, or sibling data.
  • Field Validation:
    Enforce complex data requirements by validating field values against related data elements in the same document, parent, or sibling documents.
  • Computed System Variables:
    Create Variable Definitions on Data Models, Data Sections or Data Tables to expose dynamically computed values to other expressions.
  • Data Mapping and Export:
    Transform and map extracted data at Export time using one of Grooper's Export Definitions..

Data Model Integration

The Document Code Factory leverages the Data Model Compiler to expose the full set of Data Elements defined in one or more Data Models. When an expression is evaluated, the factory ensures that all relevant data elements—fields, sections, tables, and variables—are available as strongly-typed properties in the expression environment. This enables users to write intuitive, code-friendly expressions such as:

Invoice_Number > 0 And Vendor.Vendor_Name <> ""

Data Model Compiler automatically includes not only the primary Data Model, but also any Data Models exposed through 'Child Of' and 'Sibling Of' relationships between Content Types.

  • Child Of:. When a Content Type is configured with a value for 'Child Of', all data elements from the parent type are made available in expressions within the child.
  • Sibling Of:. The 'Sibling Of' property allows a Content Type to access data from sibling types within the same parent.

When these relationships are configured, the factory (via the Data Model Compiler) generates additional properties in the dynamic type, making parent and sibling data accessible by name.

Expression Examples

The following examples demonstrate common expression patterns used with the Document Code Factory.
Each example shows how to reference Data Elements and return different types of values.
Expressions can be used for field calculations, validations, variable definitions, data rules, and export mappings.

Boolean Expression
Checks if the invoice number is present and the total is greater than zero.
Invoice_Number <> "" And Total > 0

String Expression
Combines first and last name fields into a single display name.
First_Name & " " & Last_Name

Decimal Expression
Calculates the difference between two numeric fields.
Total_Amount - Amount_Paid

DateTime Expression
Returns the current date if the 'Payment Date' is empty; otherwise, returns the payment date.
If(Payment_Date = Nothing, Now, Payment_Date)

Sum Example (Decimal Column in a Data Table)
Sums the 'Line_Total' field for all rows in the 'Line_Items' Data Table.
Line_Items.Sum(Function(row) row.Line_Total)

Parent Data Reference Example
References a field from a parent Content Type using the 'Child Of' relationship.
Personnel_File.Employee_ID = Employee_ID

Sibling Data Reference Example
References a field from a sibling Content Type named 'Benefits Enrollment' using the 'Sibling Of' relationship.
Benefits_Enrollment.Enrollment_Date < Termination_Date

Best Practices

  • Leverage Data Relationships:
    Use the 'Child Of' and 'Sibling Of' properties on Content Type to expose all necessary Data Elements for your expressions. This enables powerful cross-document logic, such as referencing parent or sibling data for validation, calculations, or export.

  • Reference Data Elements by Code Name:
    Always use the code-friendly name (spaces replaced with underscores) of a Data Element in your expressions. This ensures clarity, reduces errors, and aligns with IntelliSense suggestions in the expression editor.

  • Keep Expressions Readable and Maintainable:
    Write concise, well-structured expressions. For complex logic, break it into multiple Variable Definitions or use comments (where supported) to clarify intent. Avoid deeply nested or overly long expressions.

  • Avoid Circular References:
    Do not create expressions that reference each other in a loop (directly or indirectly), as this can cause stack overflows and are difficult to diagnose. Use the dependency graph in the expression editor to review and prevent recursion.

  • Test Expressions Thoroughly:
    Use Grooper’s expression editor to test and preview results before deploying changes. Validate expressions against a representative set of documents to ensure correct behavior in all scenarios.

  • Utilize IntelliSense:
    Take advantage of syntax highlighting and code completion in the expression editor. These features help you discover available properties, methods, and verify syntax.

  • Centralize Reusable Logic:
    For logic used in multiple places, consider defining Variable Definitions or calling static methods in Object Libraries to promote reuse and simplify maintenance.

  • Review Data Model Changes:
    When modifying Data Models or Content Types, review all dependent expressions to ensure they remain valid and up-to-date with the new schema.

Related Features

Notification