When a transformation rule fills the wrong value from a supporting file, or fails to fill a value that is clearly present, the cause is often how the lookup compares text rather than the rule itself. This guide walks through writing a matching instruction to correct it, and confirming that the instruction governed the rules you meant. For the full set of available options and the safety rules applied, see Matching Instructions for Transformation Rules.
Prerequisites
A transformation rule that performs a lookup against a linked supporting file, and a document where the match is wrong.
Access to the custom instructions for the scope you want to change.
The field name the rule reads or writes, and the name of the supporting file as it was uploaded. You will use one of these to point the instruction at the right rules.
Steps
1. Identify what is going wrong
Open the affected document and check the value the rule produced. Two patterns are common:
A shorter value matched inside a longer one. A printed code such as
26103110AC10315580was replaced by a shorter unrelated code such as0315that exists as its own row in the supporting file. This calls for a stricter instruction.A value that is clearly present was not matched. Punctuation, accents, or a single character of OCR error prevented an otherwise correct match. This calls for a more forgiving instruction.
2. Decide how narrowly to scope the change
Work out the smallest set of rules that needs to change. In order of preference:
A specific field, for example the field the rule fills or the field it reads.
A specific supporting file, named as you uploaded it.
All rules that consult a supporting file.
All transformation rules on the document.
Prefer the narrowest option that fixes the problem. A broad instruction governs every condition on the document, including rules you did not intend to change.
3. Write the reference
Begin the instruction with a phrase that states it is addressed to your transformation rules or to a supporting-file lookup. Without this, the instruction has no effect. Any of the following work:
"for transformations"
"when evaluating transformation rules"
"from the supporting file", "the master file", "the attached CSV"
the name of your supporting file
4. Add the narrowing, then the change
Append the field or file you identified in step 2, then describe the change in plain language. For a stricter match:
"When matching the article codes against the supporting file, match the full word only."
"For transformations, match the whole word for Article ID."
For a more forgiving match:
"When evaluating transformation rules, allow small typos when looking at Street 1."
You can request several changes in one instruction, and you can set different behavior for different conditions of the same rule. The reference only needs to be stated once and covers every condition you go on to name:
"For transformations: when looking at street 1, allow small typos. When looking at name 1, search the whole document."
5. Save the instruction to your custom instructions
Add the sentence to the custom instructions for the scope you chose, alongside your existing instructions. No rule numbers or special formatting are required, and existing instructions do not need changing.
6. Reprocess a document and check the enrichment view
Process or reprocess an affected document, then open the enrichment view in the console, next to the rules. Confirm that:
the instruction is listed, with the rules and conditions it governed
it is recorded as making matching stricter or more forgiving, as you intended
it is not showing an amber "had no effect on this document"
the field now holds the value you expected
Expected Outcome
The rule's lookup compares text the way you described, and the field holds the correct value. The enrichment view lists your instruction against the matching engine along with the rules and conditions it governed, and any change permitted by a forgiving match is marked as such.
Conditions you did not name keep their existing precision, and rules outside the scope you specified are unaffected. Once the instruction is saved, it is applied the same way to every document from then on.
Common Issues
Issue | Cause | Resolution |
The document reports "This looks like a matching instruction, and it did nothing" | The instruction described a change but did not state that it addresses transformation rules or a supporting-file lookup | Use the suggested wording shown on the document, or add one of the reference phrases from step 3 |
The instruction shows an amber "had no effect on this document" | It governed nothing it could change, usually because it named a different field or file than the rule actually uses | Check the rule's conditions and reword the instruction to name the field or file the rule really reads |
A forgiving instruction did not fill the field | Forgiving matches only fill blanks, so a field that already holds a value is left alone. The field may also have been left empty because two possible matches disagreed | Check the enrichment view for a disagreement note. If the field already held a wrong value, correct the rule that wrote it rather than relying on a forgiving match |
A forgiving instruction had no effect on a rejection rule | Forgiving matches never apply to rejection rules | Use a stricter instruction, or adjust the rejection rule's condition |
A forgiving instruction was not applied to a very short value | Forgiving matching requires at least three letters or digits on both sides | Match on a longer value, or change the rule's condition to read a more substantial field |
Nothing changed anywhere | The sentence was classified as a reading instruction, because it describes where on the page a value comes from | Rewrite it so it clearly addresses the rules rather than the document layout, using a reference phrase from step 3 |
Too many rules changed | The instruction was scoped broadly, for example "for transformations" with no field named | Reword it to name the specific field or supporting file |
Notes
Stricter instructions are always safe to apply, because they can only remove a wrong match. They also apply to rejection rules, which resolves cases such as a rule blocking
BLOCKEDalso blocking a supplier namedUNBLOCKED Ltd.Forgiving instructions are constrained deliberately: they fill blanks only, never overwrite, never apply to rejection rules, require at least three letters or digits on both sides, and write nothing when two candidate matches disagree.
Test on a single affected document before relying on an instruction across a supplier or an entire account. The amber "had no effect" indicator is the fastest way to confirm the instruction reached the rule you had in mind.
If a value is being overwritten by another rule rather than matched incorrectly, matching instructions are not the fix. See Transformation Rule Evaluation Order.
Writing no matching instruction leaves every rule behaving exactly as before, so there is no risk in leaving existing rules alone.