A mapping defines how Atlas converts values between a format and Docupath's canonical document format, the Docupath Internal Format (DIF). Every format has two mapping legs: the inbound leg (format to canonical format) and the outbound leg (canonical format to format). Each leg contains mapping rows. A row defines the value to write to a target field and any transformation to apply. Activating a leg compiles its approved rows into the converter that transforms documents.
How It Works
Mapping rows
A leg's mapping list shows one row per mapping. A constant shows its value under Source path, such as = "VAT", and a row with no source path of its own shows its transformation in words, such as Join Buyer/Street ", " Buyer/City. Actions holds Approve (not on approved rows), Edit, Reject (not on rejected rows) and Visual, which opens the row in the visual editor.
Status | Tooltip | How a row gets it |
Proposed | Awaiting review | Atlas generated it, you added it in a format's visual editor, or the Describe a mapping change bar created it |
Approved | Included in the converter | You approved it |
Modified | Edited after proposal | You edited its paths, type or settings, or you added it inside a project |
Rejected | Excluded from the converter | You rejected it. It can be approved again |
Match score
Match is the model's estimate of how closely the two fields' names and structure agree. Its tooltip says it is not a check that the mapping is correct and gives the scale, from 100% for identical names and structure down to 50 to 60% for a plausible but uncertain match. Atlas never approves, rejects or drops a row because of its score. A row added in a format's visual editor, or created or rewritten by the bar, has no score and shows a dash. A row added inside a project shows 100%.
Repeating elements and single occurrences
A repeating element is marked [] in a path, as in Invoice/cac:InvoiceLine[]/cbc:ID, and carries a [ ] chip in the visual editor. Atlas compiles the rows under it into a loop, so one row maps that field on every line. A position in brackets picks one occurrence, such as Party[1]/Name. To pick one by value, use a CUSTOM transformation, an XPath expression (XPath is the address of a field inside an XML document) such as Party[Role='Seller']/Name.
Versions and activation
Each leg is versioned. Generating a leg saves a new draft, and the active version keeps running until you activate the draft. Work in a draft: on an active version the visual editor is read only and the bar does not show. There, Edit (fork to draft) opens the leg's draft or copies the active version into a new one. Discard draft deletes a draft and returns the leg to its active version, when it has one.
Activate version works in two steps:
If any row is still Proposed, Atlas first approves every row that is not already Approved, including Rejected and Modified rows.
Atlas compiles the rows that are Approved at that point into the converter and makes the draft the active version. When no row was Proposed, step 1 does not happen, so Modified and Rejected rows stay out of the converter until you approve them.
A compile error stops the activation. The version stays a draft, but the approvals from step 1 remain.
A format's legs are shared by every Via canonical project and every document type in the Docupath platform that uses the format, so activating a leg, or compiling such a project, changes the mapping for all of them. A Direct project compiles its own mapping for that source and target pair and does not change the formats' legs.
Activating a leg also activates the format's latest draft version, listed under VERSIONS on the format page. A project's Compile XSLT button, on the XSLT stage, includes Modified rows as well as Approved ones.
Describe a mapping change
Describe a mapping change is available on a draft's mapping list and visual editor. It is unavailable on project pages.
Enter a sentence describing the change to preview Proposed changes, with one card per change. A card tagged CHANGE, ADD or REMOVE is ready and shows the current transformation (NOW) and the new one (AFTER). A card that can't be made is tagged REJECTED, shows what was TRIED and explains the reason. The preview does not save changes. Applying the preview saves all selected changes to the draft, or none if the operation fails. A filter or search on the mapping list limits the changes to the matching rows, indicated by the {n} filtered rows chip.
Describe a mapping change supports direct copies, constants, joins of 2 to 8 fields, splits, lookups of up to 200 entries, and date, datetime and number formats. It does not support CUSTOM transformations. A change can't be made when, for example, a path is not in the schema, another row already writes to that target (each target field allows one mapping row), the row was rejected, a date transformation does not specify the source date format, or the result would not compile.
Supported Configurations and Options
Transformation types
Set the type with Edit in the list (the Type dropdown) or in the visual editor's inspector (Transformation:). Changing the type resets its settings, and format starts from a default date format.
Type | What it does and what it needs |
DIRECT | Copies the value unchanged. No settings |
FORMAT | Converts the value. Pick date or datetime with a from and a to pattern, or number with Decimals (0 to 4) and thousands |
CONCAT | Joins source fields: a path per input (+ field adds one) and a join with separator |
SPLIT | Takes one part of a source field: split on (the delimiter) and take part #, counted from 0. Its description counts from 1, so part #0 reads |
LOOKUP | Translates values with from → to pairs (+ pair adds one) and an optional default |
CUSTOM | Runs an XPath expression, such as |
CONST (constant in the dropdown) | Writes a fixed value, such as |
Bulk actions
Action | Where | Rows it changes |
Reject all proposed | Format mapping list | Every row not already Rejected, including Approved and Modified rows. It works only while a row is Proposed, and the confirmation counts only the proposed ones |
Approve all proposed | List panel in the visual editor | Proposed rows only |
Approve all | A project's Field mappings page | Every row not already Approved, including Rejected rows |
Reject all | A project's Field mappings page | Every row not already Rejected, including Approved rows |
Other Technical Specifications
FORMAT date patterns, both ways: YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY, YYYY/MM/DD, DD.MM.YYYY and YYYYMMDD. Datetime has its own list. A new number format has 2 decimals and a thousands separator.
Compile checks: every path exists in its schema, every required target field is mapped, a direct copy or a lookup fits the target field's type (a FORMAT transformation converts the value explicitly), and every XPath expression is valid. Each failure stops the activation.
The bar takes one sentence of 3 to 2,000 characters per preview, with no follow-up conversation, and allows 500 previews per tenant per calendar month, applied or not. Past that, a preview fails with You have used all 500 AI mapping edits included this month. The allowance resets on the 1st.
Notes
Before you activate, decide every Proposed row and approve edited rows again, or activation approves rows you rejected or leaves your edits out.
A row added inside a project starts as Modified, so the project's Compile XSLT includes it, but activating the leg on the format compiles it only once it is approved.