Skip to main content

Applying Flags with CSV Keyword Matching

Using a CSV supporting file with value-to-flag mappings in transformation or rejection rules to automatically flag documents based on matched conditions

This guide walks through setting up a transformation 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 Flagging feature enabled for your tenant

  • Create access to the tab you create the rule on. Admins and managers have the Trading party specific and Organization specific tabs of Transformations and Rejection Rules; the Country specific and Global tabs are available to admins only, and a custom role can be granted read access to them but never create, update or delete access

  • A CSV file, with its columns separated by commas or semicolons, that has 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 Main menu → Flagging.

A cell can hold several flags separated by semicolons or commas. A comma between two digits is part of a value (for example, "Over 5,000" stays one flag).

Step 2 - Create a New Transformation or Rejection Rule

  1. Click the dropdown arrow next to your user avatar in the top-right corner to open the main menu.

  2. Click "Transformations" or "Rejections" to open the respective management page.

  3. Select the scope tab for your rule: Trading party specific or Organization specific. The Country specific and Global tabs are admin only. Managers do not see them, and no custom role can be given create, update or delete access.

  4. Click "Add New" to open the new rule form.

  5. Enter a descriptive Title (e.g., "SerialNumbers_KDY").

  6. Select the Document type this rule applies to.

Step 3 - Link the Supporting File

Click "Link supporting file", above the rule text on the right. A page opens listing the supporting files already uploaded to your tenant. Select the CSV file that contains your value-to-flag mappings, and click "Link File".

Step 4 - Choose Where the Rule Applies

Select the Organization the rule applies to. On the Trading party specific tab, also select Party A, and Party B as well if the rule is for the relationship between two trading parties.

Step 5 - Write the Rule

In the rule text box (Rule written in natural language for a transformation, Reject written in natural language for a rejection rule), 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 6 - Generate and Save

  1. Click "Refine with AI" to check and improve the rule.

  2. Click "Generate with AI" to generate the rule from your instruction. Wait for the loading spinner to complete.

  3. 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}).

  4. Click "Save". You will be returned to the rule list with a confirmation banner.

Step 7 - 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 250,000 rows 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, edit the rows of the Supporting File in Docupath, or replace it with an updated CSV. Either way the change becomes a new version of the file, and documents processed from then on use the new mappings.

  • CSV-based flags coexist with flags from other sources (regular transformations, 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 Main menu → Flagging.

  • A CSV flag value that matches a flag of the document's organization, ignoring capitals, is shown as that flag, with its color, position, and spelling.

  • Other CSV flag values have no color. They appear with black text on a light gray background, after the document's other flags.

  • A cell that names several flags, separated by semicolons or commas, applies each of them. A comma between two digits is part of a value and does not separate flags.

  • A single rule group can contain both CSV-based flag rules and regular SET action rules. Both types are applied during processing without conflict.

Related Articles
Did this answer your question?