A format in Atlas describes a document's fields and their structure. It can include an XSD that defines its structure and a Schematron file that checks its business rules. Its two mapping legs connect it to Docupath's canonical document format, the Docupath Internal Format (DIF).
The Formats page, opened from the menu on the left, holds two libraries. Tenant lists the formats your tenant has imported or forked. Global lists formats Docupath maintains and shares with every tenant, such as Peppol BIS Billing 3.0.
How It Works
Format contents
Part | What it is |
Name | Shown in the Formats list, in project pickers and in the Docupath platform's list of Atlas formats |
Document type | Invoice or Purchase Order. The format maps to the canonical format of this type |
Schema | The full list of the format's fields and how they nest, read from XML samples or from an XSD. It starts at the root element, the outermost element of the file, shown as Root Element: on the format page once a version is active |
XSD and Schematron | Optional. Atlas checks documents in this format against them |
Samples | The XML files the format was imported from, if any. The visual editor shows their values next to the fields |
Mapping legs | The inbound leg (format to canonical format) and the outbound leg (canonical format to format) |
Versions and statuses
A new format starts with version 1 as a draft. Later changes, such as an XSD or Schematron attached with Schema files or a field added with + Add field, are saved to a draft version. Atlas creates the draft from the active version when needed. While a draft exists, the format's page shows a Draft pending banner with Activate.
Version status | What it means |
DRAFT | Being prepared. Activate approves and activates it in one click |
APPROVED | Approved but not active, for example after an activation that failed. Activate makes it active |
ACTIVE | The version in use. Activating another version deprecates it |
DEPRECATED | No longer in use: replaced by another version, or deprecated with Deprecate or Disable. Rollback makes it active again at once, replacing any active version |
LOCKED | A deprecated version frozen with Lock. It can no longer be rolled back |
A draft version is also activated automatically when you activate one of the format's mapping legs, or when a project that uses the format compiles, runs a preview or approves all its mappings.
The format itself is ACTIVE or DISABLED. In the list, the Status column reads DRAFT while no version is active, and Current Version shows the active version's number, such as v2.
Tenant formats and global formats
| Tenant formats | Global formats |
Maintained by | Your tenant | Docupath |
Visible to | Your tenant only | Every tenant |
Edit, version, disable, remove | Yes | No, they are read only |
Use in a project | Yes | Fork first |
Choose for document output in the Docupath platform | Yes, under Tenant specific | Yes, under Global Formats |
With Global selected, the page says Docupath-managed formats. Read only. A global format's page is marked GLOBAL and READ ONLY, and shows its versions and the rows Docupath provides under Mappings to and from canonical · read only.
Forking a global format
Fork to tenant copies a global format into your tenant as a new tenant format with the same name. The copy gets version 1 as a draft, copied from the global format's active version with its XSD and Schematron. It also gets whichever inbound and outbound legs the global format has, as draft versions whose rows are already Approved. Each row carries the note Inherited from global format "…" (inbound) or (outbound).
You can edit the forked format. It does not receive subsequent updates to the global format.
From a row in the Global list, you confirm with Fork and the list stays on Global, so switch to Tenant to find the copy. From a global format's page, Fork to tenant forks at once and opens the copy under Tenant.
When a document type's output under Settings → Destination format & APIs is a global format, chosen under Global Formats, Docupath uses the global format directly, so its published changes apply from the next document.
Supported Configurations and Options
Option | Where | What it does |
Search name, document type, root element | Formats list | Filters the formats on the page already loaded, not every page |
All statuses, Active, Disabled, Hide disabled | Formats list | Filter by format status. Hide disabled is checked by default |
+ Add field | Format page | Adds a field to the draft. Grayed out until the format has a field list |
Rename field | Format page | Renames a field and publishes a new version at once, taking its mappings and validation rules along. Documents that still use the old name no longer match. Not offered once an XSD is attached |
Diff | VERSIONS table | Compares a version with the one before it, for example 3 fields added, 1 field removed |
Disable, Remove, Remove permanently | Formats list and format page | Disable deprecates the active version and hides the format while Hide disabled is checked. Remove in the list, or Remove permanently on the page, deletes a disabled format and all its versions |
Other Technical Specifications
Item | Detail |
XSD and Schematron files | Up to 5 MB each, in Import format and in Schema files |
Names | Up to 255 characters. Renaming a format with Edit accepts unaccented letters (A to Z), numbers, spaces and |
Global version statuses | ACTIVE, DEPRECATED, LOCKED |
Notes
Fork to tenant gives the copy the global format's name, so a second fork fails while your tenant has a format with that name, for example the first copy. Rename that format with Edit first.
The Formats page has no control that makes a disabled format active again.
Removing a format cannot be undone. Atlas refuses it while a project still uses the format, with the message Cannot remove "…". Detach the projects that reference it first.