Variable Definition

Variable Definitions define a variable with a computed value that can be called by various code expressions. Variable Definitions are added to Data Models, Data Sections and Data Tables using their "Variables" property.

Overview

Variable Definitions provide a powerful way to create named, reusable values that are calculated dynamically using code expressions. Variables can be referenced throughout your Data Model, Data Section, Data Table, and other configuration objects to drive logic, formatting, automation, and conditional behavior.

Variables are not static. They are computed at runtime based on the logic you define. This makes them ideal for scenarios where you need to calculate totals, derive values, perform conditional checks, or format data for display and export.

What are Variables for?

Variables serve several key purposes in Grooper:

• Calculation: Compute values such as totals, differences, or derived fields based on other data elements.
• Reusability: Define logic once and reference it in multiple places, reducing duplication and improving maintainability.
• Conditional logic: Drive workflow, validation, or formatting based on dynamic conditions.
• Formatting: Control how numbers or dates are displayed using custom format strings.

Key properties

A Variable Definition consists of several key properties:

• Name: The unique identifier for the variable. This is how you reference the variable in expressions and throughout your configuration. Names must be code-friendly (letters, numbers, and underscores only, starting with a letter or underscore).
• Type: The data type of the variable (e.g., Boolean, DateTime, Decimal, Double, Guid, Int16, Int32, Int64, Object, Single, String, or TimeSpan). The type determines how the value is evaluated and formatted.
• Is Array: Indicates whether the variable represents a single value or a collection (array) of values.
• Expression: The logic used to calculate the variable's value. Expressions can reference other fields, variables, or built-in functions, and can include arithmetic, string manipulation, and conditional logic.
• Number Format: (Optional) Controls how numeric values are displayed. Use standard or custom .NET numeric format strings (e.g., c2 for currency, n0 for whole numbers).
• Date Format: (Optional) Controls how date and time values are displayed. Use standard or custom .NET date/time format strings (e.g., yyyy-MM-dd for ISO dates).
• Description: (Optional) A place to document the purpose and logic of the variable.

When Grooper processes a document, it evaluates each variable's expression in the context of the current data. The result is available for use in other expressions, validation rules, formatting, and automation.

How are Variables created?

Variable Definitions can be added to any Data Field Container using the "Variables" property. This includes:

• Data Models (the root container for a document's data schema)
• Data Sections (logical groupings of fields or subsections)
• Data Tables (for tabular, repeating data)

To create a new Variable Definition:

1. Select the Data Model, Data Section, or Data Table.
2. Open the "Variables" editor (Press the "..." button).
3. Press the Add button (add_circle) to create a new Variable.
4. Fill in the required properties:
   • Name: Enter a unique, code-friendly name.
   • Type: Select the appropriate data type.
   • Is Array: Set to "True" if the variable should be an enumeration of multiple values. Otherwise, leave as "False".
   • Expression: Enter the logic to compute the variable's value. You can reference Data Elements in scope, other variables, and/or use built-in functions.
     • If you open the "Expression" editor, Grooper's code completion will assist you. As you type, members in scope will appear in the code completion list.
5. (Optional) Set "Number Format" or "Date Format" to control how the value is displayed.
6. (Optional) Enter a "Description" to document the variable's purpose.
7. Click "OK" when finished.
8. Press the Save button (save) to save your changes.

Example

Suppose you have a Data Table named "Line Items" with columns "Quantity" and "Unit Price". You can define a variable named TotalAmount with the following properties:

• Name: TotalAmount
• Type: Decimal
• Expression:

(From row In Line_Items Select row.Quantity * row.Unit_Price).Sum

• Number Format: c2 (to display as currency)

This variable will automatically calculate the total amount for all line items and display it in currency format.

What can use Variables?

Variables are referenced (or "called") in code expression editors. The Variables must be in scope in order to be called. The following is a comprehensive list of every object and property in Grooper that can reference (or "call") a variable.

Data Field and Data Column properties that can call Variables:

• "Default Value"
• "Calculated Value"
• "Is Valid"
• "Validate Message" (Available when "Is Valid" expression is configured)
• "Is Required"

Data Section properties that can call Variables:

• "Caption"

Data Rule properties that can call Variables:

• "Trigger" (Access to Variables is determined by the Data Rule's "Scope" assignment)
• True and False Data Actions can also call Variables:
  • "Calculate Value > Vale Expression"
  • "Append > Trigger"

Export Definition properties that can call Variables:

• File Export properties:
  • "Relative Path"
• Data Export properties:
  • "Table Mappings > Column Mappings > ColumnName > Expression" (Access to Variables is determined by the Table Mapping's "Source Scope" assignment)
  • "Custom Statements > Statement" (Access to Variables is determined by the Custom Statement's "Source Scope" assignment)
• CMIS Export properties:
  • "Subfolder Path"
  • Read Mapping expressions
  • Write Mapping expressions

Lookup Specification properties that can call Variables:

• "Trigger" (when "Trigger Mode" is set to Custom)
• Database Lookup
  • "SQL Query" (Variables can be called with "@VariableName" in the WHERE clause)
• CMIS Lookup
  • "CMIS Query" (Variables can be called with "@VariableName" in the WHERE clause)

Fill Method properties that can call Variables:

• "Trigger"

Variable Definitions themselves can reference other Variables in scope (including those defined earlier in the same container).

Best practices

• Use descriptive, code-friendly names to avoid conflicts and make your configuration easy to understand.
• Test your expressions thoroughly to ensure they produce the expected results.
• Use the formatting properties to control how values appear in the UI or exported data.
• Document each variable's purpose using the "Description" property.
• Reference variables in other expressions to build complex logic in a maintainable way.