This guide walks through setting up a transformation rule or rejection rule that uses a CSV supporting file to apply flags based on matched conditions. Instead of writing individual rules for each value, you upload a CSV file containing value-to-flag mappings, and the system automatically flags documents when it finds matching values in the document content or line items.
Prerequisites
The
Flaggingfeature enabled for your tenantA CSV file in comma-separated format with at least two columns: one for the values to match and one for the flag values to apply
The CSV file must already be uploaded to your tenant as a Supporting File
Steps
Step 1 - Prepare the CSV File
Create a CSV file with columns for the values to match and the flags to apply. For example, a file called SerialNumbers_KDY.csv:
SerialNumber | ItemName | BuyerFlag |
SN-KDY-1001 | Wireless Router | ReceivedKDY1 |
SN-KDY-1005 | Monitor Stand | ReceivedKDY5 |
SN-KDY-1008 | Docking Station | ReceivedKDY8 |
The flag column contains the flag values that will be applied to documents when a match is found. These values are taken directly from the CSV and do not need to be pre-created in Settings > Flagging.
Step 2 - Create a New Transformation or Rejection Rule
Click the dropdown arrow next to your user avatar in the top-right corner to open the main menu.
Click "Transformations" or "Rejection Rules" to open the respective management page.
Select the scope tab for your rule (e.g., Global, Organization, or Trading Party).
Click "+ Add New" to open the new rule form.
Enter a descriptive Title (e.g., "SerialNumbers_KDY").
Select the Document Type this rule applies to.
Step 3 - Link the Supporting File
Click "Link Supporting File". A popup opens listing the supporting files already uploaded to your tenant. Select the CSV file that contains your value-to-flag mappings.
Step 4 - Write the Rule
In the Rules text area, write a natural language instruction that tells the system how to match values from the CSV against the document and which flag column to apply. For example:
If any line item on the document has a serial number matching the SerialNumber column and an item name matching the ItemName column in the uploaded sheet SerialNumbers_KDY, add the matching document flag from the BuyerFlag column.
The rule text should reference the CSV column names exactly as they appear in the file header.
Step 5 - Generate and Save
Click "Refine with AI" to check and improve the rule.
Click "Generate with AI" to generate the rule from your instruction. Wait for the loading spinner to complete.
Review the generated rules. Conditions should reference the CSV columns as
{ColumnName}placeholders (e.g.,{SerialNumber},{ItemName}). The Flag action value should also appear as a{ColumnName}placeholder referencing the flag column (e.g.,{Flag}).Click "Save". You will be returned to the rule list with a confirmation banner.
Step 6 - Test with a Document
Upload a document that matches one or more conditions from the CSV. After processing completes, open the document in the Cockpit and verify that the expected flags appear in the Flags column and document preview.
Expected Outcome
When a document is processed, the system evaluates each row in the linked CSV against the document content. For every row where the conditions match, the corresponding flag from the flag column is applied to the document. Multiple rows can match on a single document, resulting in multiple flags. If no conditions match, no flags are applied. Flags appear in the Flags column on the document list and in the document detail view.
Common Issues
Issue | Cause | Resolution |
Values not matching | Column names in the rule text do not match the CSV header exactly | Verify the column names in the rule text match the CSV file header (case-sensitive) |
Rule does not fire for a document | The rule is scoped to a document type that does not match the uploaded document | Check the Document Type setting on the rule matches the document being processed |
CSV upload rejected | File exceeds 100,000 rows, 10 columns, or 50 MB | Reduce the file to within platform limits |
Notes
CSV-based flag rules are evaluated deterministically at processing time with no AI involved. The AI is only used during rule generation (the "Generate with AI" step) to compile your natural language instruction into structured rules.
When a document is reprocessed, all previously applied flags are cleared and recalculated, so CSV-based flags are re-applied based on the current state of the rule and CSV data.
To update the value-to-flag mappings, remove the old Supporting File and re-upload the new version. In-place editing of supporting files is not supported.
CSV-based flags coexist with flags from other sources (regular transformation rules, rejection rules, and instruction builds). All matching flags from all sources are applied to the same document without conflict.
Flag values in the CSV are applied directly from the file and do not need to be pre-created in Settings > Flagging.
A single rule group can contain both CSV-based flag rules and regular SET action rules. Both types are applied during processing without conflict.