Data Action

Data Actions are a core concept in Grooper’s data processing framework, enabling powerful, reusable, and configurable operations for manipulating, transforming, and validating extracted document data. They are the building blocks for data normalization, business rule enforcement, and data model conversion throughout Grooper’s workflow.

What Are Data Actions?

A Data Action is a discrete operation that acts on document data. Data Actions can:

Assign or transform field values
Parse and distribute values to other fields
Copy or move data between elements
Perform lookups and validations
Execute custom logic as part of a data processing pipeline

Data Actions are designed to be modular and reusable. With Data Rules, they can be combined into hierarchies allowing complex, multi-step data transformation and validation logic to be built from simple, focused operations.

Why Use Data Actions?

Data Actions provide a clear separation between data extraction (locating data in documents) and data normalization or transformation (making data fit business requirements). This separation offers several benefits:

Simplified Extraction: Keep extractors focused on finding data, not transforming it.
Reusability: Common transformations (such as splitting a full name or normalizing phone numbers) can be reused across multiple rules and workflows.
Maintainability: Changes to business logic or data mapping can be made in one place, without modifying extraction logic.
Advanced Scenarios: Enable complex data mapping, conditional logic, and multi-stage processing.

Where Are Data Actions Used?

Data Actions are used in several key areas of Grooper:

1. Data Rules

A Data Rule defines logic to be applied to document data, such as normalization, validation, or business rule enforcement. Each Data Rule can have one or more Data Actions assigned to its "True Action" or "False Action" properties. When a Data Rule is executed (for example, by the Apply Rules activity), its Data Actions are applied to the relevant data instances.

Example: A Data Rule might check if a "Full Name" field is populated. If so, a Data Action can split it into "First Name" and "Last Name" fields.

2. Activities: Convert Data and Route

Some Grooper activities use Data Actions to perform data mapping and transformation as part of broader workflow steps:

Convert Data: The Convert Data activity transforms a document from one Content Type (data model) to another. The "Actions" property is a collection of Data Actions that define how data is copied, mapped, or transformed from the source to the target type. This is essential for data normalization, especially when consolidating data from multiple document types into a single export format.

Route: The Route activity can move or clone documents into different batch processes based on classification or business rules. When routing between different Content Types, Data Actions can be defined to map, copy, or transform data fields as part of the routing process, ensuring that data fits the requirements of the target workflow.

How Data Actions Are Applied

Data Rules

When a Data Rule is executed, its Data Actions are applied to the document’s data instance. The process is as follows:

The Data Rule evaluates its trigger condition.
If the condition is met, the "True Action" (a Data Action or hierarchy of Data Actions) is executed.
If the condition is not met and a "False Action" is defined, it is executed instead.
Each Data Action manipulates the data as configured—assigning values, performing calculations, or raising issues.

This approach is ideal for normalization, validation, and enforcing business logic after extraction.

Data Rules can be executed in several Grooper activities:

Apply Rules: The Apply Rules activity is designed specifically to apply one or more Data Rules to each document in a batch or folder. If any Data Rule raises issues, the document can be flagged.
Extract: The Extract activity may optionally execute a Data Rule in two ways:
- The "Rules" property on the Extract activity allows you to specify a list of Data Rules to be applied after extraction.
- A Data Model, Data Section and/or Data Table will execute a Data Rule when its "Validate Rule" property is configured.
Convert Data: The Convert Data activity can apply Data Rules as preprocessing (before conversion) or postprocessing (after conversion) steps. This is useful for cleaning or validating data before or after it is mapped to a new content type.
Route: The Route activity can use Data Actions (including the "Execute Rule" action to apply Data Rules) to transform or map data when routing documents.
Review: Data Rules may be manually executed by a user in a Review step in the Data Viewer.

Convert Data and Route Activities

In activities like Convert Data and Route, Data Actions are used to map and transform data between different Content Types:

In Convert Data, the "Actions" collection specifies the sequence of Data Actions to execute. These actions define how each field or group of fields is copied, transformed, or calculated in the target data model.
In Route, Data Actions can be part of the routing definition, ensuring that when a document is moved or cloned into a new process (potentially with a different Content Type), its data is mapped and transformed appropriately.

This enables advanced scenarios such as:

Data normalization from multiple source types to a single output type
Conditional data mapping based on business rules
Multi-stage processing where data is transformed at each step

Types of Data Actions

Grooper provides a variety of built-in Data Actions. Each Data Action can be configured with properties such as "Display Name" and "Remarks" for documentation and clarity.

Below is a summary of each available Data Action.

Calculate Value

Calculate Value calculates and assigns a value to a Data Field or custom variable using a code expression. Use this action to perform calculations, normalization, or value assignments after extraction. The value can be set on a specific field or stored as a custom variable on the Batch Folder. The calculation is defined by the "Value Expression" property, which supports referencing other fields or context.

Example usage: Assign the result of Subtotal + Tax to the "Total" field.

Clear Item

Clear Item removes or resets the value of a specified Data Element. Use this action to clear the value of a field, remove all rows from a table, or empty a multi-instance section. For containers, all child elements are cleared; for fields, the value is set to an empty string.

Example usage: Clear the "Comments" field or remove all rows from a table.

Concat

Concat merges or combines items in a collection based on a trigger condition and parameter. This action is typically used to concatenate or aggregate data from multiple items in a collection, such as combining rows in a table or merging section instances, according to a specified rule.

Example usage: Combine adjacent table rows when a certain field matches a condition.

Copy

Copy copies data from a source element to a target element. You can copy values, containers, or collections, with options to prevent overwriting, ignore empty values, or specify a source index. This action is useful for duplicating or transferring data between fields, sections, or tables.

Example usage: Copy the value from "Address Line 1" to "Mailing Address" if the latter is empty.

Append

Append adds one or more elements to a collection, such as a table, multi-instance section, or multi-cardinality field. For each instance of the source element, an entry is added to the target collection. Optional actions can be defined to populate or copy child elements.

Example usage: Append all rows from one table to another, or add values from a multi-cardinality field to a list.

Data Lookup

Data Lookup performs a lookup operation against an external data source (such as a database) to validate or populate field values. The "Lookup" property defines the lookup specification, including criteria, target fields, and error handling. Use this action to automate field validation or population based on external data.

Example usage: Validate that a "Customer ID" exists in a database and populate related fields.

Extract From

Extract From sets a field value by running an extractor on another field. Configure the "Source Field", "Target Field", and "Extractor" properties to define the extraction logic. Use options like "Prevent Overwrite" and "Ignore Miss" to control execution and handling of missing results.

Example usage: Extract the last name from a "Full Name" field and assign it to a "Last Name" field.

Parse Value

Parse Value parses a field value into substrings using a regular expression and assigns them to sibling fields. The "Source Field" is parsed using the "Pattern" property, which should contain named groups matching the target fields.

Example usage: Split "DOE, JOHN Q" in "Full Name" into "Last Name", "First Name", and "MI" fields using a regex pattern.

Raise Issue

Raise Issue adds an issue to the issue log. The "Log Message" property defines the message, with optional "Category" and "Metadata" for classification and additional context. Use this action to flag data issues or validation errors during processing.

Example usage: Log an error if a required field is missing or a value is out of range.

Remove

Remove conditionally removes records from a collection such as a Data Section or Data Table. The "Collection" property specifies the target, and the "Trigger" property defines a Boolean expression to determine which records are removed.

Example usage: Remove all rows from a "Line Items" table where the "Amount" field is zero.

Require Value

Require Value enforces that specified data elements (fields, columns, sections, or tables) are populated with a value. The "Required Elements" property lists the elements to check. If any are missing, an error is logged and the element is marked as invalid.

Example usage: Require that "First Name" and "Last Name" fields are not blank.

Action List

Action List executes a sequence of Data Actions in a defined order. Use this to group several actions together as a single step in a Data Rule. Each action in the list is executed in sequence, allowing for complex, multi-step data processing.

Example usage: Normalize a value, validate it, and then copy it to another field, all in one step.

Execute Rule

Execute Rule invokes a Data Rule. Use this to modularize and reuse rule logic. The "Rule" property specifies which Data Rule to execute, which must apply to the same or a descendant scope.

Example usage: Invoke a Data Rule for validation or normalization.

Best Practices

Use Data Actions to keep extraction logic simple and focused.
Group related Data Actions into Data Rules for maintainability.
Use the "Actions" collection in Convert Data to centralize data mapping and transformation.
Document your Data Actions with clear display names and remarks.
Test Data Actions in isolation before integrating them into larger workflows.

Summary Table: Data Actions in Context

Context	How Data Actions Are Used	Typical Use Cases
Data Rules (e.g., via Apply Rules)	Applied as "True Action" or "False Action" for normalization, validation, or business logic	Splitting fields, enforcing required values, raising issues
Convert Data activity	"Actions" collection defines mapping/transformation from source to target Content Type	Data normalization, output formatting, multi-stage processing
Route activity	Data Actions map/transform data when routing between Content Types	Workflow branching, exception handling, parallel processing