Supporting Files (CSV) can be linked to Transformation Rules for dynamic lookups against reference data. Rules dynamically transform extracted values against the uploaded CSV data, without requiring manual rule edits when reference data changes.
Link a supporting file to a transformation for:
Value mapping: Convert extracted values using a reference table (e.g., country code to country name).
Reference-based enrichment: Set a field based on a matching entry in a reference table (e.g., look up a unit price from a price list).
Frequently changing reference data: When lookup values change often and maintaining them inline within rules is impractical.
Prerequisites
Create, Update or Delete access, as the change needs, on the tab of Transformations you are working on. Admins have all four tabs; managers have Trading party specific and Organization specific; a custom role has whatever it was granted. Country specific and Global are editable by admins only
Access to Supporting Files
A CSV file with its columns separated by commas or semicolons, conforming to platform limits, already uploaded to your tenant as a Supporting File (linking lets you select from files that already exist in your tenant; it does not upload a new file)
Steps
Prepare your CSV file. Ensure its columns are separated by commas or semicolons and that it has a maximum of 250,000 rows. The file must not exceed 50 MB. Confirm it has been uploaded to your tenant as a Supporting File.
Open the main menu. Click the dropdown arrow (▾) next to your user avatar in the top-right corner of the screen.
Click "Transformations" to open the Transformations management page.
Select the scope tab for your rule (Trading party specific, Organization specific, Country specific or Global). Only admins can add rules on the Country specific and Global tabs.
Click "Add New" in the top-right. The Add new transformation rule form opens.
Add a title. Enter a descriptive name for the transformation in Title.
Select a document type from the Document type dropdown.
Write the transformation rule in Rule written in natural language, referencing the supporting file by name. For example:
If item_code matches a product in the Customer Price List reference file, set unit_price to the corresponding list price.
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 file the rule should reference (e.g., Customer Price List).
Click "Link File". The form opens again, with the file's name shown above the rule text.
Choose where the rule applies. Fill in the fields the form shows for your tab, such as Organization or Country.
Click "Refine with AI" (✏️ icon) to check and improve the rule. Wait for any feedback, errors, or suggestions before proceeding.
Click "Generate with AI" (⚡ icon) to generate the rule from your instruction. Wait for the loading spinner to complete.
Click "Save" at the top of the screen. You will be returned to the Transformations list, and a confirmation banner will indicate the transformation was saved.
Test with sample documents to verify the rule behaves as expected.
To update reference data later, edit the Supporting File's rows or replace it from Main menu → Supporting files. Either way the change becomes a new version of the file, and the rule uses it for documents processed from then on, without being edited. A replacement comes into use only once it has processed successfully, so the file keeps working if a replacement fails (see Common Issues).
Expected Outcome
The transformation appears in the Transformations list with a confirmation banner, and the linked file's Transformation count in Main menu → Supporting files includes the new rule. Documents processed from then on are transformed using the rows of the file's version in use.
Common Issues
Issue | Cause | Resolution |
Data not recognized, with every value in a single column | The columns are separated by a character other than a comma or a semicolon | Save the file again as CSV with commas or semicolons between the columns |
Upload rejected due to size | The file is larger than 50 MB or has more than 250,000 rows | Split into smaller files or remove unnecessary rows |
Rule does not match expected values | The column names in the rule text do not match the CSV header exactly | Use the column names exactly as they appear in the file's header row |
Replacement file fails to process (e.g., missing or renamed columns, corrupted header, empty or unreadable file, unsupported format) | The replacement could not be validated against the original | The Supporting File automatically keeps its last successful version active and stays in Processed status, shown with a yellow info indicator and a tooltip (e.g., "Column mismatch detected - The replaced document's columns differ from the original, so we have restored the latest stable version of this document"). Please correct the file and try again. The failed attempt is recorded as Failed in the version history. |
Notes
Maximum 10 Supporting Files per organization, 100 per tenant.
Reference data is updated by editing the Supporting File's rows or by replacing it. A replacement comes into use only once it has processed successfully, so a failed replacement never leaves the file without a working version.
The version history retains every attempt. A failed replacement is listed as Failed, making it clear that the data currently served belongs to the last successful version.
Known Limitations and Edge Cases
A failed replacement leaves the Supporting File in Processed status (with a yellow info indicator and tooltip) because a stable previous version exists to fall back to.
A first-time upload that fails has no previous stable version to fall back to, so it shows a red Failed status instead.