Import XML samples or an XSD with Import format to create a draft tenant format for your integration. Sample files can be XML invoices or purchase orders (for example, exported by your ERP). You can then map the format to Docupath's canonical document format, the Docupath Internal Format (DIF), and use it in projects.
If the format is a standard Docupath already maintains, such as Peppol BIS Billing 3.0, look in the Global list on the Formats page first. Fork to tenant gives you a copy with Docupath's XSD, Schematron and any mapping legs it provides.
Prerequisites
Atlas enabled for your tenant. When enabled, an Atlas entry appears in Settings and in the user menu.
Either XML samples of the format (up to 10 files of 5 MB each, all with the same root element, the outermost element of the file) or the format's XSD, as one file of up to 5 MB.
Optionally, the format's Schematron, up to 5 MB, to import together with the XSD.
Steps
In the Docupath platform, open Settings and click Atlas. Atlas opens in a new browser tab. The first time, a Welcome to Atlas dialog offers a tour. Click Skip or Start tour.
Click Formats in the menu on the left. The first time, a short tour of the page starts.
Check that Tenant is selected, then click Import format.
Add the files, in one of two ways:
From samples: under XML or JSON samples, click Choose file and select one or more XML files.
From an XSD (the format's structural definition): under XSD schema, click Choose XSD and select the file. Once Atlas has read it, the section is tagged Detected and shows the root element.
Optional, with an XSD: under Schematron rules, click Choose Schematron and select the format's Schematron, the file of business rules every transformed document is checked against (.sch or .xml).
Check Format name. Atlas fills it in from the XSD's file name, or from the first sample's file name without its extension and any -number or _number at the end (invoice-1042.xml gives "invoice"), and tags it Auto. Type over it to use your own name.
Check Document type. If Atlas recognizes the root element, it selects the type and shows it in a chip, for example Auto-detected · Invoice. Otherwise choose Invoice or Purchase Order from Select document type….
Click Import Format, next to Cancel. The button reads Importing… while Atlas reads the files.
Click the new format in the Tenant list. New formats are added at the end of the list, on its last page when you have more than 20 formats.
Expected Outcome
The toast Imported "…". Draft version created. confirms the import. The Tenant list shows the new format with the status DRAFT and no current version, because version 1 is not active yet.
The format's page shows:
The Draft pending banner, v1. Activate it to use it., with Activate.
The Document Type: you chose. Root Element: shows a dash until version 1 is active.
Mappings to and from canonical, with empty Inbound and Outbound panels and the buttons Generate inbound, Generate outbound and Generate both directions.
Next, generate the format's mapping legs from this page, or pick the format on a project's Setup stage. Version 1 does not have to be active first. Activating one of its legs activates it too.
Common Issues
Issue | Cause | Resolution |
Import Format stays grayed out | No file is chosen, Format name or Document type is empty, or the dialog shows an error | Add samples or an XSD, fill in both fields, and replace any file an error names |
That file does not look like a valid XSD schema | The file chosen under XSD schema is not an XSD | Choose the format's .xsd file |
Choose Schematron cannot be clicked | No XSD is chosen. Removing the XSD also removes the Schematron | Choose the XSD first, or import without the Schematron and add it later with Schema files on the format page |
Format import failed: Samples have different root elements: … | The samples are not all the same format | Import only samples with the same root element, and import a different layout as a format of its own |
Format import failed: Input XML contains a forbidden DOCTYPE declaration, or the same for an ENTITY declaration | Atlas refuses XML files that contain DOCTYPE or ENTITY declarations | Remove the declaration from the file and import again |
Format import failed: A format named "…" already exists | Your tenant already has a format with that name, possibly a disabled one | Choose another name |
The format has no fields: + Add field is grayed out and generating mappings fails with Generate mappings failed: Format "…" has no extracted schema yet. Upload at least one XML sample before generating mappings. | Atlas could not build a field list from the XSD, for example because it relies on other XSD files, and kept only the root element | Import the format from XML samples instead |
Notes
When you choose an XSD, Atlas builds the format from the XSD alone. Samples chosen alongside it are not sent.
Atlas reads samples without AI. It combines the fields of every sample, so a field that appears in only one sample is still part of the format.
Atlas reads an uploaded XSD on its own, so fields defined in other XSD files that it refers to are not picked up. A format built from an XSD has no sample values.
The document type is a guess from the root element, for example Invoice for a root element named
InvoiceorCrossIndustryInvoice. The format maps to the canonical format of the type you choose, so check it before you import.XML or JSON samples also takes JSON. A JSON format is imported from exactly one JSON file, selected on its own, and a project can use it only with the Via canonical mapping mode.