Skip to main content

Transformations

Programmatic rules to transform information captured from documents

The Transformations page on the Organization specific tab, showing the Rules list sorted by Title with two rule groups expanded to reveal their individual rules and switches: an enabled group, and a fully disabled group shown in grey text

Transformations are programmatic rules that reshape, normalise, and standardise extracted data after AI processing but before export to downstream systems. They sit in the middle of Docupath's three-part business rules and instructions layer - after Instruction Builds (which guide extraction) and before Rejection Rules (which enforce compliance guardrails). Transformations handle field-level adjustments such as setting default values, converting units, applying percentage adjustments, and performing CSV-based lookups, ensuring that data leaving Docupath matches the exact format expected by receiving systems.


How It Works

The Transformations page showing the Rules list with scope tabs for Trading party specific, Organization specific, Country specific, and Global rules

Processing Position

Transformation Rules execute after AI extraction is complete and after Instruction Builds have guided the extraction process. They run before Rejection Rules evaluate the document, and before the data is exported. This sequencing means transformations operate on fully extracted data and can clean or reshape values before compliance checks are applied.

Creating a Transformation Rule

To create a transformation rule:

  1. Click the dropdown arrow (▾) next to your user avatar in the top-right corner of the screen to open the main navigation menu

  2. Click "Transformations" in the main menu

  3. Select the appropriate scope tab (Trading Party Specific, Organization Specific, Country Specific, or Global)

  4. Click "+ Add New" to open the creation form

  5. Enter a Title and select a Document Type

  6. Select the relevant scope options (sub-organization, trading parties, or countries — depending on the tab)

  7. Write your transformation logic in plain English in the Rules text area. For example: "If an item_uom is in g or grams, and the item_quantity is greater than 1000, set item_uom to kg and divide item_quantity by 1000"

  8. Optionally, click "Link Supporting File" to attach a supporting file already uploaded to your tenant instance

  9. Click "Refine with AI" (pencil ✏️ icon) to get AI feedback on your instruction

  10. Click "Generate with AI" (lightning ⚡ icon) to have the AI programmatically generate the transformation rule from your plain-English description

  11. Click "Save" to save the transformation

Editing a Transformation Rule

  1. On the Transformations page, select the scope tab that contains the rule (Trading party specific, Organization specific, Country specific, or Global).

  2. Click the edit (pencil) icon on the rule's row in the Actions column. The Edit transformation rule screen opens.

  3. Update any of the rule's details, including its Title, Document type, Organization, Party A, Party B, or the transformation logic in the natural-language text area. You can also use Link supporting file, Refine with AI, or Generate with AI, just as when creating a rule.

  4. Click Save to apply your changes, or Cancel to discard them.

Deleting a Transformation Rule

  1. On the Transformations page, select the scope tab that contains the rule.

  2. Click the delete (trash) icon on the rule's row in the Actions column.

  3. A confirmation dialog asks if you are sure you want to delete the rule.

  4. Click Delete to remove it, or Cancel to keep it.

Once deleted, the rule no longer applies to documents processed under that scope.

Enabling and Disabling Transformation Rules

A transformation rule group can be disabled without being deleted, either as a whole or one sub-rule at a time. Only enabled rules are evaluated when a document is processed; a disabled rule stays configured but is skipped entirely.

On the Transformations list:

  • Each rule group's row has a switch. It is on when at least one rule in the group is enabled. Turning it off disables every rule in the group; turning it on enables them all

  • A group whose rules are only partly enabled shows an information icon next to its title. Hovering it reveals how many are on, for example "2 of 3 rules currently enabled"

  • A fully disabled group is shown in grey text, making inactive rules easy to spot while scanning the list

  • Expand a group with the chevron (⌄) to see its individual rules, each with its own switch

The Title column is the first column in the list and can be sorted, so groups can be found by name before toggling them.

Each rule also carries its own switch on the create and edit screens, so a rule can be saved in a disabled state and switched on later once it has been reviewed.

Switch changes take effect in the interface immediately and are saved after you stop toggling. If a save fails, the group reverts to its last saved state and an error message appears.

Rules created before this capability existed are enabled by default, so existing behavior is unchanged until a rule is explicitly switched off.

Generated Rule Structure

When the AI generates a transformation rule, the output is composed of three components:

  1. Conditions: Field-value comparisons that determine when the rule applies, using supported operators

  2. Actions: Field manipulation operations that execute when conditions are met

  3. Logic connector: Either AND (all conditions must be true) or OR (any one condition must be true). A single rule cannot mix AND and OR.

Users do not typically need to edit the generated rules manually, but they can be modified directly if needed.

Condition Operators (in Generated Rules)

Operator

Meaning

Example

=

Equal to (string or number)

country = "US"

<

Less than (numbers, dates)

due_date < invoice_date

<=

Less than or equal to

total <= 0

!=

Not equal to

currency != "USD"

IS_NULL

Field missing or empty (after trim)

po_number IS_NULL

IS_NOT_NULL

Field exists and is not empty

supplier_name IS_NOT_NULL

CONTAINS

Field contains the value, or any value from a linked supporting file (case-insensitive substring)

article_name CONTAINS "widget"

NOT_CONTAINS

Field does not contain the value, or any value from a linked supporting file - the inverse of CONTAINS (case-insensitive)

article_name NOT_CONTAINS "widget"

Action Operators (in Generated Rules)

Operator

What It Does

Example

SET

Sets a field to a specific value

SET currency = "USD"

INCREASE

Adds an absolute amount or percentage

INCREASE total BY 10%

DECREASE

Subtracts an absolute amount or percentage

DECREASE discount BY 2%

MULTIPLY

Multiplies by a factor

MULTIPLY qty BY 1000

DIVIDE

Divides by a factor

DIVIDE unit_price BY 100

Scope Precedence

Transformation rules can be configured at multiple scopes. When multiple rules could apply, the most specific scope takes precedence:

  1. Trading Party specific (Party A + Party B) - highest priority

  2. Trading Party specific (only Party A or only Party B)

  3. Organisation specific

  4. Country specific

  5. Global - lowest priority

Supporting Files

Transformation rules can reference supporting files (e.g., master data, vendor information, price lists etc.) for value mapping scenarios - for example, mapping country codes to country names. Supporting files are uploaded to the tenant instance separately and can be linked to a rule during creation by clicking the "Link Supporting File" link. Use the CONTAINS and NOT_CONTAINS ("Does not contain") operators to act on whether a field matches an entry in a linked file - for example, filling a field when a lookup value is found (CONTAINS) and clearing it only when none is found (NOT_CONTAINS). Because NOT_CONTAINS is a true substring check, it affects only genuine non-matches, so values that did match keep their result.

Rule Execution Order

Actions within a generated rule execute top-to-bottom. When sequence matters (e.g., convert units first, then add tax), actions should be ordered accordingly within the same rule, or split across separate rules with explicit sequencing.

Rule Titles

Each generated rule shows a short, automatically generated title in its header, next to its position number - for example, Rule 1 : Set Currency to "USD". The title is derived from the rule's own content, so you can identify a rule at a glance instead of reading it by position alone. It is separate from the Title you enter for the rule group as a whole.

A transformation rule's title is built from its first action:

  • A SET to a value reads as Set <Field> to "<value>"; a SET with an empty value reads as Clear <Field>.

  • A SET that pulls from a supporting-file column reads as Set <Field> from column "<Column>".

  • INCREASE, DECREASE, MULTIPLY, and DIVIDE read as Increase, Decrease, Multiply, or Divide <Field> by <value> - or by column "<Column>" when the operand comes from a supporting file.

  • A flag action reads as Raise flag "<name>", or Raise flags "<name>", "<name>" when more than one flag is raised.

Field paths are shown with arrow notation (for example, Buyer -> Name). When a rule has more than one action, the title describes the first action and appends +N more to stand for the rest. A normal rule always has a describable first action, so a title is shown; the header falls back to just the position number (with no title) only in the rare case of an incomplete rule with no usable action.


Supported Configurations and Options

Configuration

Detail

Scope levels

Trading Party specific, Organisation specific, Global

Logic connectors

AND (all conditions true), OR (any condition true) - cannot mix

Condition operators

=, <, <=, !=, IS_NULL, IS_NOT_NULL, CONTAINS, NOT_CONTAINS

Action operators

SET, INCREASE, DECREASE, MULTIPLY, DIVIDE

Percentage support

INCREASE and DECREASE support percentage values (e.g., BY 10%)

CSV lookup

Up to 150,000 rows, up to 10 columns per file

Document type scoping

Rules are assigned to a specific document type

Enable/disable

Per rule, or per rule group (cascades to every rule in the group)


Other Technical Specifications

Parameter

Limit

Maximum rule groups per organisation

100

Maximum rules per rule group

500

Maximum rule groups per tenant

1,000

Maximum CSV file size

50 MB

Maximum CSV rows

150,000 (or line items)

Maximum CSV columns

10

String comparison

Case-sensitive by default (unless org default overrides)

Null handling

IS_NULL matches null, empty string, and whitespace-only values


Notes

  • AND and OR logic cannot be mixed within a single rule - choose one connector per rule

  • Arithmetic actions (INCREASE, DECREASE, MULTIPLY, DIVIDE) are skipped if the target field is not numeric; use SET to establish a numeric default first

  • Rounding and formatting are not natively supported as actions - apply rounding in subsequent rules or handle precision in the destination system

  • Percentage calculations use the current field value at the time of execution - ordering matters when chaining percentage adjustments

  • Only supported operators are accepted; unsupported operators will produce an error

  • CSV files must use comma-separated values format; other delimiters are not supported

  • Transformations do not correct extraction errors - use Instruction Builds for extraction accuracy

  • Existing rules keep working as before. To use the NOT_CONTAINS ("Does not contain") operator on a rule you built earlier, regenerate the rule so it picks up the operator, then reprocess the affected documents

  • Each rule's header title is generated automatically from the rule's first action and is for identification only. It is not separately editable and reflects the rule's current content

  • Disabling is not the same as deleting. A disabled rule keeps its conditions and actions and can be switched back on at any time

Did this answer your question?