Code Expressions (Concept)

From Grooper Wiki
(Redirected from Code Expressions)

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025 2023

Code Expressions (not to be confused with regular expressions) are snippets of VB.NET code that expand Grooper's core functionality.

Code expressions provide a powerful way to add dynamic logic, calculations, and conditional behavior to your Data Fields, Batch Processes, image processing steps, and export paths. This article explains the types of expressions available, how they are used, and best practices for configuring them.

What are expressions?

An expression in Grooper is a code snippet or formula that is evaluated at runtime to compute a value, determine workflow logic, or validate data. Expressions can reference fields, variables, and built-in functions available in the current context, allowing you to tailor Grooper’s behavior to your business needs.

Expressions are used in many places, including:

  • Calculating field values in a Data Model
  • Validating extracted data
  • Controlling the flow of a Batch Process
  • Generating export paths for documents
  • Managing image processing steps in an IP Profile
  • Data Rule triggers

Types of expressions

Grooper supports several types of expressions, each designed for a specific purpose:

Data Model expressions

A full article on Data Model expressions can be found here.

These expressions are among the most common in Groper. They are used to calculate and validate field values in a Data Model.
Data Model expressions are configured using the following Data Field and Data Column properties:
  • "Default Value" - Generates a default value for the field.
  • "Calculated Value" - Calculates an expected value for the field based on other field values. This can be used to validate or automatically populate the field.
  • "Is Valid" - A Boolean expression that determines if the field's value is valid. If the expression evaluates to false, the field will be set to an error state to alert a user during Review.
  • "Is Required" - A Boolean expression that determines if the field is required (meaning it cannot be empty). If the expression evaluates to true and the field is empty, it will be set to an error state to alert a user during Review.

Batch Process expressions

These expressions customize the flow of steps in a Batch Process.
Batch Process expressions are configured using the following Batch Process Step properties:
  • "Should Submit Expression" - A Boolean expression that determines if a task is submitted for each item in scope (Batch, Batch Folder or Batch Page). The expression is evaluated for each item. If the expression evaluates to false, no task is submitted for the item and the item is skipped. If all items are skipped, the step is effectively bypassed.
  • "Next Step Expression" - Determines the next step to execute after this one. This is used to create branching workflows in a Batch Process and route the Batch to Review steps for exception handling. This must evaluate to a specific Batch Process Step or Nothing to complete the Batch.

IP Profile expressions

These expressions customize the flow of steps in an IP Profile.
IP Profile expressions are configured using the following IP Step and [[IP Group] properties:
  • "Should Execute Expression" - A Boolean expression that determines whether the IP Step or IP Group should execute. This allows the IP Profile to adapt dynamically to properties of the image or the results of previous IP Steps. If the expression evaluates to true, the IP Group or IP Step executes. The IP Group or IP Step is skipped if false.
  • "Next Step Expression" - A Boolean expression that determines the next IP Step or IP Group after the current one completes. This is used to create conditional branching in an IP Profile or terminate the IP Profile early. This must evaluate to a specific IP Group or IP Step or Nothing to terminate the IP Profile.
  • The need for complicated, expression-driven IP Profiles has reduced dramatically with the introduction of Azure OCR. The Azure engine simply does not require the levels of image cleanup traditional OCR engines require.

Path expressions

These expressions are used to dynamically generate output paths for exported documents. They allow you to combine field values, metadata, and custom logic to build folder and file names.
Path expressions are configurable for the following:
  • The Merge activity's "Attachment Name" property - Calculates the attachment filename.
  • Various Export Formats' "Computed Filename" property - Generates the filename for the exported file.
  • The File Export, FTP Export, and STFP Export definitions' "Relative Path" property - Defines the path of exported files, dynamically generating subfolder paths and filenames based on document data retrieved by the expression.
  • The CMIS Export definition's "Subfolder Path" property - Defines the folder path inside the "Target Folder" where files are exported, dynamically generating subfolder paths based on document data retrieved by the expression.
    • BE AWARE: This expression ONLY generates folder paths NOT filenames.
  • The Attachment Type command "Rename Attachment" and its "Expression" property - Calculates the attachment's new name using an expression.

Mapping expressions

Mapping expressions are used by various mechanisms to export Grooper document data to external systems like database tables and content management systems. Mapping expressions are also used by CMIS Import and Import Behaviors to import data from external content management systems to Grooper documents.

Trigger expressions

Trigger expressions are utilized by various Grooper objects to dynamically control execution.
  • In most cases, when the trigger expression evaluates to true the object is executed. For example, AI Extract has a "Trigger" property. If configured and the expression returns true, AI Extract will automatically run during extraction. If it returns false, it won't. This can be used to conditionally execute AI Extract only for certain Document Types or when specific data is present.
  • In the case of a Data Rule's "Trigger" property, the trigger expression determines what Data Actions are applied. If the expression returns true, the "True Action" configuration is applied. If the expression returns false, the "False Action" is applied.
Trigger expressions are configured in almost all cases using a "Trigger" property. The following have configurable "Trigger" properties in Grooper:

Variable Definitions

A full article on Variable Definitions can be found here.

Variable Definitions use expressions to compute values that can then be leveraged from other expressions.

Syntax and examples

Grooper expressions use Visual Basic .NET syntax. You can use string interpolation, composite formatting, LINQ queries, built-in functions, and lambda functions.

String interpolation

$"Invoice_{Invoice_No}_{Invoice_Date:yyyy-MM-dd}"

String concatenation

"Invoice" & "_" & Invoice_No & "_" & Invoice_Date.ToSTring("yyyy-MM-dd")

Composite formatting

String.Format("Invoice_{0}_{1}", Invoice_No, Invoice_Date.ToString("yyyy-MM-dd"))

LINQ queries

(From Row In Line_Items Select Row.Line_Total).Sum

Built-in functions

CleanFileName(Customer_Name)
Guid.NewGuid
DateTime.Now

Best practices

  • Test expressions thoroughly to avoid runtime errors.
  • Sanitize path segments in path expressions to avoid invalid characters.
  • Use clear, maintainable logic for conditional and validation expressions.
  • Document complex expressions using comments or supporting documentation.
  • Use explicit formatting for dates and numbers to ensure consistent output.

Expression Editor shortcuts

When in any expression editor:

  • Enter Ctrl + Shift + Space on the keyboard to bring up the IntelliSense menu.
  • Type Me. to list all accessible instance fields, properties, and methods in the IntelliSense menu.
Retrieved from "https://wiki.grooper.com/index.php?title=Code_Expressions_(Concept)&oldid=31299"