Generate, review, and activate a format's inbound or outbound mappings for an integration.
A format has two mapping legs to Docupath's canonical document format, the Docupath Internal Format (DIF). In a Via canonical project, the inbound leg (format to canonical format) reads documents in this format and the outbound leg (canonical format to format) writes them. Docupath platform output also uses the outbound leg.
Prerequisites
Atlas enabled for your tenant, so that Atlas appears in the Docupath platform's Settings and user menu.
A tenant format with a field list, imported from XML samples or an XSD.
For a global format, a copy made with Fork to tenant. Its legs arrive with the rows already Approved, so you can go straight to reviewing the rows in the list.
Steps
Generate a leg
In Atlas, click Formats in the menu on the left.
Click your format in the list.
Find Mappings to and from canonical, with the inbound leg's panel on the left and the outbound leg's on the right.
Click Generate inbound or Generate outbound in an empty panel, or Generate both directions above the panels.
If one leg exists, Generate both directions asks first, because it also redoes that leg as a new draft. The active version stays active until you activate the draft.
Wait while the Building mappings panel lists each row as Atlas proposes it. A toast then reports the count, such as Generated 40 inbound mappings, and a leg that has never been activated shows a Draft chip and View mappings ({n}).
Review the rows in the list
Click View mappings ({n}) on the leg. The mapping list opens with the version chip DRAFT.
Work through the rows with the Filter buttons and Search source or target path…, checking each row's paths and Type. Match is the model's estimate of how well the field names fit, not a check that the row is right.
Click Approve on each row that is correct.
Click Edit on a row that needs fixing, and change its paths, Type, transformation settings or Notes.
Click Save. The row becomes Modified.
Click Reject on each row that should stay out of the converter.
To add or delete a row, use the visual editor or Describe a mapping change.
Work in the visual editor
Click Visual at the top of the list, or Open visual on the leg panel. Approved rows are solid green lines, proposed rows dashed amber, modified rows dotted blue and rejected rows red.
If the status strip reads Read-only, click Edit (fork to draft).
To add a row, click + Add mapping or an unmapped field, then click the field it maps to in the other tree. The new row is a DIRECT copy with the status Proposed and no match score.
To change a row, click its line. The inspector shows Transformation:, its settings and Notes, with Approve, Reject and Delete.
To remap a row, drag either end of its line to another field.
To delete a row, select its line and press the Delete key, or click Delete in the inspector.
Describe a change in a sentence
Optional: filter or search the mapping list to limit the change to those rows. The chip {n} filtered rows shows the scope.
On the draft's mapping list or visual editor, type the change in Describe a mapping change, for example "Concatenate street and postal code into Buyer.Address".
Click Preview change.
Read Proposed changes. Each card is a CHANGE, ADD or REMOVE marked ready, or a REJECTED card marked can't be made with the reason.
Clear the check box of any change you do not want.
Click Apply {x} of {n} changes, or Discard to drop the preview.
Review the added and modified mapping rows. New rows are Proposed and changed rows are Modified.
Activate the version
Click the Proposed filter and approve or reject every row it shows.
Click the Modified filter and approve every row you want in the converter.
Activation compiles Approved rows only, and a row still Proposed makes Atlas approve every unapproved row first, including rejected ones.
Click Activate version. In the visual editor the button activates every leg that has a draft, and reads Activate both directions when both do. The legs are activated one after the other, so if the second fails to compile, the first stays active.
Click Activate in the confirmation.
Wait for Mapping version activated. (or Both mapping directions activated.). If compilation fails, the toast starts with Activate failed: and lists up to three problems, and the version stays a draft.
Review from a project
In a project, open the Mappings stage. The Field mappings page lists the rows source to target. In a Via canonical project each row joins the two legs, and approving or rejecting it updates both.
Compile on the XSLT stage.
Expected Outcome
The mapping list's version chip reads ACTIVE. On the format page, the leg panel shows Active with a version number. Every Via canonical project that uses the format now runs this version, and for an outbound leg so does Docupath platform output.
Common Issues
Issue | Cause | Resolution |
The toast says some mappings need manual review | Atlas dropped proposals it could not use, such as a canonical path that does not exist. The warnings are not listed | In the visual editor, find fields without a line and add those rows by hand |
No Describe a mapping change bar | The leg's version is not a draft | In the visual editor, click Edit (fork to draft) |
Activate failed: with Source path … is not present in source schema …, Target path … or XPath expression … is not syntactically valid | An approved row points at a missing field, or a path or CUSTOM transformation is not valid XPath | Fix the row and approve it again, or reject it, then activate. The failed attempt already approved every row, so an edited row stays Modified and is left out without a message |
Activate failed: with Required target field … has no mapping | The target schema requires a field that no approved row fills | Add a row for it, approve it and activate again |
Activate failed: with Target … expects … but source … is … | A direct copy or lookup writes a value of the wrong type | Set the row's Type to format with the conversion, approve it again and activate |
Activate failed: with No approved mappings could be converted | No row was Approved, for example because every row was edited and none approved again | Approve the rows, then activate |
Rows you rejected are Approved after activation | A row was still Proposed at activation, so Atlas approved every row that was not approved | Click Edit (fork to draft), reject those rows, decide every Proposed row, and activate again |
Notes
One AI analysis covers both directions, but Atlas saves only the legs you ask for. Generating one leg leaves the other untouched.
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 changes all of them.