Follow these guidelines to write effective Instruction Builds that deliver consistent AI extraction results.
When to Use
Refer to this guide before writing or reviewing Instruction Builds.
Prerequisites
Admin role in Docupath
Familiarity with how Instruction Builds work (natural language instructions guiding AI extraction)
Key Practices
Give each requirement its own instruction. A scope holds a group of separate instructions, so write one requirement per instruction rather than combining several into one block of text. Each one can then be enabled, disabled, refined, and reviewed on its own.
Use numbered steps within an instruction when a single requirement genuinely has an ordered sequence. Instructions are processed in the order they are listed in the group, so use separate instructions for separate concerns and numbered steps for stages of one concern.
Reference exact field names from your templates or schema. Ambiguous references cause extraction mismatches.
Be specific. Avoid vague instructions like "make data complete." Instead, state exactly what the AI should extract and from where.
Include fallback logic. For example: "If the invoice date is missing, return null." This prevents silent failures.
Scope as narrowly as possible. Apply instructions at the Trading Party or Org level rather than Global to avoid unintended side effects across other document flows.
Keep extraction logic in Instruction Builds, formatting logic in Transformations. Mixing concerns makes both harder to maintain.
Refine one instruction at a time. Use the magic wand icon on a single card to sharpen just that instruction, so a reviewed instruction is not rewritten while you are working on a different one.
Test with real sample documents before deploying to production workflows.
Disable rather than delete when retiring an instruction. Switching it off takes it out of processing while preserving the wording, which makes the change easy to reverse and keeps the reasoning available for review.
Introduce a risky instruction switched off. Save it disabled, confirm the rest of the group still behaves, then switch it on.
Document the intent of each instruction so future reviewers understand why an instruction exists, not just what it does.
Keep whitelists up-to-date. Reference data such as cost centres, VAT IDs, and supplier lists must reflect current business reality.
Split rather than consolidate when instructions might conflict. Where two requirements in the same scope could interact, keeping them as separate instructions lets you switch one off to isolate the problem instead of editing a single combined block.
Common Issues
Issue | Cause | Resolution |
Vague or inconsistent extraction | Instructions lack explicit steps | Rewrite as numbered, specific steps |
Over-broad instructions affecting unrelated documents | Instruction scoped too widely (e.g., Global instead of Trading Party) | Narrow the scope to the appropriate level |
Conflicting instructions producing unpredictable results | Multiple instructions targeting the same field without precedence | Switch instructions off one at a time to find the interacting pair, then split or reword them |
Output shaping embedded in Instruction Builds | Formatting logic mixed with extraction logic | Move formatting and reshaping to Transformations |
An instruction has no effect on documents | The instruction's switch is off | Expand the group on the Instruction Builds list and switch that instruction on |
A group looks active but one instruction is not applying | The group's row switch shows on when only some of its instructions are enabled | Check the enabled-count indicator on the group's row and the individual switches |
Instructions that were deliberately left off are all on again | The group's row switch was turned off and back on, which enables every instruction in the group | Re-check the individual switches after using the group switch |
Saving is blocked with a warning about flagged instructions | Save-time refinement flagged an instruction as an exception | Reword the flagged instruction, then save again |
Notes
Instructions within a group are applied in the order they are listed, and only enabled instructions are applied at all
A disabled instruction stays saved in the group and contributes nothing to processing until it is switched back on
Because the group's row switch reflects whether any instruction is enabled, it is not a reliable indicator that a whole group is active. Read the enabled count instead
Switch changes on the Instruction Builds list save automatically a couple of seconds after you stop toggling, rather than on an explicit Save click. Confirm the list shows the state you intended before moving on
Disabling every instruction in a group leaves nothing applied at that scope, so processing falls through to the next scope in the precedence order. That is a different outcome from the group applying no changes