Natural language instructions are the foundation of accurate document processing in instruction builds. Instruction builds are written in plain language and can apply reasoning, which lets them interpret the messy variety of real-world documents (dates in many formats, mixed units, multiple languages) in ways that simple rule-based logic cannot.
Effective instructions are clear and specific about what you want, name the specific fields you want to act on, and include any interpretation, calculation, or formatting the data needs. This article covers how to write clear, testable instructions that deliver consistent results across diverse documents and edge cases.
How It Works
Where Instruction Builds Fit in the Pipeline
Instruction builds run first, directly on the data Docupath extracts from a document. Transformations then run on the output of the instruction builds, and rejection rules run last. The order is:
Instruction builds → Transformations → Rejections
Because instruction builds run first and can reason about the document, they are the right place for anything that requires interpretation, including date normalization, unit harmonization, translation, multi-step calculations, and formatting.
Instruction Builds vs Transformations
Instruction builds are natural language and can reason about a document. Transformations are more structured: they reference fields and operators directly and are suited to reference-file lookups and simple operations.
Use instruction builds for tasks that require interpretation or multi-step logic, such as:
Interpreting and normalizing dates that appear in many different formats
Harmonizing units of measure and recalculating dependent values such as unit prices
Translating extracted text
Multi-step or conditional logic expressed in plain language
Use transformations for structured operations, such as:
Looking up values in a reference file and replacing fields based on the result
Simple arithmetic, such as a single multiplication
Direct field replacements
Transformations cannot perform complex multi-step arithmetic, reasoning-based date extraction, or translation. Those belong in instruction builds.
Writing Effective Instructions
Be specific about what you want. You do not need rigid syntax or operators (for example, "="). Plain language is fine, as long as it is clear and specific enough to be testable.
Name the specific fields you want to act on. When an instruction should work with a particular captured field, name that field explicitly (for example, "ship-to location" rather than "where this will be shipped to").
Pronouns are fine when context is clear. Words like "it" or "this" are acceptable when the rest of the instruction makes the reference unambiguous.
Include the formatting and interpretation the data needs. Because instruction builds run first, this is where date formatting, normalization, calculation, and similar logic belong.
Add fallback behavior. Specify what should happen when a field is ambiguous, missing, or malformed.
Give each requirement its own instruction. A scope holds a group of separate instructions, so write one requirement per instruction instead of combining several into one long passage. Instructions in a group are applied in the order they are listed, and each can be enabled, disabled, and refined independently.
Test against real examples. Validate instructions against actual document samples.
Using Separate Instructions to Isolate Behavior
Because each instruction in a group has its own switch, you can change what the group does without rewriting anything:
To find which instruction causes an unexpected result, switch instructions off one at a time and reprocess a sample document. This is more direct than deleting part of a single combined passage and putting it back afterwards
To introduce a risky instruction safely, save it switched off, confirm the rest of the group still behaves, then switch it on
To retire an instruction, switch it off rather than deleting it. The wording is preserved and the change is easy to reverse
Only enabled instructions are applied. A disabled instruction contributes nothing to the text the AI receives, so it cannot influence extraction while it is off.
Keeping requirements in separate instructions is what makes this possible. A single passage covering four requirements can only be switched on or off as a whole.
Example Instruction Builds
The following are typical instruction builds. They require reasoning or multi-step calculation that transformations cannot perform:
Harmonize UOMs captured from line items into "EA". For example, "2 boxes of 10" would be 20 EA, and a "Dozen" would be 12 EA. Recalculate unit prices and update them appropriately.
If the Invoice Details Due Date is less than 30 days after the Invoice Details Invoice Date (calculated as the difference in calendar days between the two dates), replace Invoice Details Payment Terms with "URGENT".
Translate all extracted Arabic text values into English.
For contrast, a transformation references fields and operators directly and handles structured lookups, for example:
For each line item, look up the row in the Updated Price List reference file where item_article_id = {Article ID} and retrieve {Unit Price}.
If the retrieved {Unit Price} != item_unit_price, then replace item_unit_price with the retrieved {Unit Price}.
Common Instruction Patterns
Pattern 1: Fixed-Format Field Extraction "Find an 8-digit PO number starting with 29. Capture digits only; ignore the 'PO' prefix." Specifies: field, length, starting pattern, allowed characters, and what to exclude.
Pattern 2: Reasoning-Based Date Normalization "Extract the invoice date and normalize it to YYYY-MM-DD, regardless of the date format used in the document." Specifies: field, the interpretation required, and the target format. Date interpretation belongs in instruction builds because documents use many different date formats.
Pattern 3: Decimal Separator Handling "Use a dot for decimals. If a comma appears, treat it as a thousands separator." Specifies: the primary behavior and the alternative-format behavior.
Pattern 4: Conditional Row Splitting "If a line item quantity is present and greater than zero, split it into separate rows." Specifies: condition, field, threshold, and action.
Supported Configurations and Options
Instruction Scopes
Instructions can be scoped at multiple levels:
Scope Level | Usage | Override Behavior |
Global | Default instructions for all documents | Overridden by Country, Organization, Trading Party |
Country | Country-specific instructions (tax, date formats, language cues) | Overrides Global; overridden by Organization, Trading Party |
Organization | Partner-specific instructions (PO formats, cost centers, whitelists) | Overrides Country and Global; overridden by Trading Party |
Trading Party | Relationship-specific instructions (Party A and Party B, or a single party) | Highest precedence |
Instruction Component Options
Component | Valid Values | Notes |
Field Reference | The name of the field you want to act on | Name specific fields explicitly (e.g., "ship-to location") when targeting them |
Format Specifier | Digit count, prefix, allowed charset, delimiter, target format | Example: "8-digit," "alphanumeric," "starts with 29," "YYYY-MM-DD" |
Condition | Expressed in plain language | No specific operators required (e.g., "is less than 30 days after") |
Fallback Action | leave empty, use default, skip row, flag for review | Choose one per instruction |
Other Technical Specifications
Instruction Syntax Requirements
Length: 1,000-5,000 characters per instruction (recommended for clarity).
Natural language: Instructions can be written as plain-language sentences. Numbered steps are optional and useful for multi-step logic.
Field names: Name the specific fields you want an instruction to act on.
Conditions: Express conditions in natural language; specific operators are not required.
Comments: Prefix clarifications with "Note:" to distinguish them from the core requirement.
Instruction Validation Criteria
Criterion | Details |
Use clear references | Pronouns such as "it" or "this" are fine when context makes the reference clear. Name the specific field when you want to act on a particular field. |
No contradictory instructions | If two instructions conflict, either reword them so they cannot both apply, or keep them as separate instructions and switch one off. Consolidating into a single priority-ordered instruction is still valid where the two really are one ordered requirement. |
Include needed formatting | Formatting, normalization, and reasoning belong in instruction builds, because they run first (before transformations and rejections). |
Testable criteria | Every instruction should be verifiable against a document sample. Example: "Find an 8-digit number starting with 29" (measurable) rather than "Find the main PO" (subjective). |
Character Limits and Quotas
Per instruction: 5,000 characters maximum.
Per document type: Recommended maximum of 20 distinct instructions. Where a group is approaching this, review whether some instructions have been superseded and can be switched off, rather than merging unrelated requirements into one instruction to reduce the count.
Reserved keywords: Do not use field names as instruction prefixes (e.g., avoid starting with "Invoice Date" without context).
Relationship to Other Features
Feature | Integration | Notes |
Transformation Rules | Run after instruction builds, on the data instruction builds produce | Use transformations for reference-file lookups and simple operations; keep reasoning, multi-step calculations, and formatting in instruction builds |
Rejection Rules | Run last, after instruction builds and transformations | Instructions and transformations shape the data; rejection rules then decide what is rejected |
Field Mapping | Instructions refine extraction within mapped fields | Field mapping identifies field location; instructions clarify extraction logic |
Reference Files (CSV) | Referenced by transformations and rejection rules | Reference-file lookups are handled by transformations and rejection rules rather than instruction builds |
Notes
Common Pitfalls
Pitfall | Problem | Solution |
Vague Instructions | "Make data complete" or "clean up values" is not testable | Write a specific instruction, e.g., "Harmonize all line-item units of measure into EA and recalculate unit prices" |
Over-Broad Instructions | "Extract all numbers" without context captures spurious data | Scope narrowly, e.g., "Extract the 8-digit number immediately after the 'PO:' label" |
Conflicting Instructions | "Use a dot for decimals" contradicts "treat a comma as decimal" | Reword so one instruction covers both cases, e.g., "Use a dot for decimals; if a comma appears, treat it as a thousands separator". To confirm which of two instructions is causing the conflict, switch one off and reprocess a sample |
Whole Group Switched Off Unintentionally | The group's row switch was used, which turns every instruction in the group on or off | Expand the group and set the individual switches, and check the enabled-count indicator on the group's row |
Vague Field References | "Extract the amount" without saying which field | Name the field, e.g., "Extract the Amount from line item 1 only" |
Common Edge Cases
Case 1: Missing or Empty Fields Scenario: The PO number field is present but empty. Handling: "If the PO field is empty, leave it empty (do not use a default)."
Case 2: Multiple Matching Patterns Scenario: A document contains two different 8-digit numbers. Handling: "Extract the 8-digit number that immediately follows the 'PO:' label; if there are multiple 'PO:' labels, use the first occurrence."
Case 3: Format Variance Across Documents Scenario: Some documents use "29-001234," others use "29001234." Handling: "Extract 8 digits starting with 29; ignore hyphens or spaces."
Case 4: Language or Locale-Specific Cues Scenario: European invoices use a comma as the decimal separator; US invoices use a dot. Handling: Apply Country-scoped instructions, e.g., "For Germany, treat a comma as the decimal separator. For the US, treat a dot as the decimal separator."
Case 5: Conditional Extraction Based on Trading Party Scenario: Tax-exempt organizations should skip the sales tax field. Handling: Use a Trading Party-scoped instruction, e.g., "For Party A, when tax-exempt status is true, leave the sales tax field empty."