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.
When to Use
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
Admin role in Docupath
A CSV file in comma-separated format, 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 it is comma-separated with a maximum of 100,000 rows and 10 columns. 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 (e.g., Global, or Country / Organisation / Trading Party).
Click "+ Add New" in the top-right to open the new transformation rule form.
Add a title. Enter a descriptive name for the transformation.
Select a document type from the Document Type dropdown.
Write the transformation rule in the Rules text area, 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.
Link the supporting file. Click the "Link Supporting File" link. A popup opens listing the supporting files already uploaded to your tenant. Select the file the rule should reference (e.g., Customer Price List).
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, replace the Supporting File with an updated CSV. The platform does not promote the new version until it has processed successfully: the previous version stays active and keeps serving lookups, view, and download throughout processing, and the replacement becomes the active version only once it validates. If the replacement fails to process, the Supporting File keeps its previous stable version active (see Common Issues), so it never becomes inaccessible.
Common Issues
Issue | Cause | Resolution |
File upload fails or data not recognised | Wrong delimiter (e.g., semicolon instead of comma) | Re-save the file as comma-separated CSV |
Upload rejected due to size | File exceeds 100,000 rows or 50 MB | Split into smaller files or remove unnecessary rows |
Rule does not match expected values | Too many columns (maximum is 10) | Reduce columns to only those needed for the lookup |
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 organisation, 100 per tenant.
Reference data is updated by replacing the Supporting File. The platform uses a "don't promote until success" model: the previous version stays active until the replacement has processed successfully, so a failed replacement never leaves the file inaccessible.
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.