XML-invoice field layout
Introduction
In another article, Digital invoice processing in combination with XML invoices, we describe the benefits of receiving and processing XML invoices. To read an XML invoice, you need an existing XML invoice field layout, known as mappings. In the XML invoice field layout section, you'll find all the layouts that exist in your environment. Each environment has a default set of mappings recognizable by the fact that they can't be edited. However, there's also an option to create a custom mapping, especially if you have an agreement with a supplier that they provide a particular value in a specifically communicated field. Later in this article, we'll attempt to explain how to create your own mapping and make it work for the supplier it should be applied to.
XML Mappings
Within this section, you'll find multiple mappings, with a distinction between the default mapping and supplier-specific mappings. The standard format for XML invoices is UBL (Universal Business Language), with the most common versions being UBL 2.0 and UBL 2.1. More extensive general information can be found on the Forum Standardization website. The explanations in this article are based on this standard.
Creating Custom Mappings
You can create a custom mapping by clicking the "Add" button at the top of this section. Once the new screen is open, you can upload an XML file received from the supplier. When you've saved the mapping and open it again, the XML invoice will be displayed on the right side of the screen. In the case of a UBL invoice, it's easiest to start by copying an existing mapping. For example, you can copy the "Standard UBL invoice field layout" by clicking on the three dots at the end of the row and choosing "Copy."
After copying, you can upload and save the received XML invoice, but not before setting a unique recognition string.
Recognition String
To process an XML invoice, you need a recognition string, which is a sequence of characters based on which Spend Cloud recognizes the file as an invoice. For UBL invoices, this means that any XML file containing one of the following sequences can always be processed from the mailbox:
- //cbc:UBLVersionID='2.0' - Appears in the XML as <cbc:UBLVersionID>2.0
- //cbc:UBLVersionID='2.1' - Appears in the XML as <cbc:UBLVersionID>2.1
- //cac:AccountingCustomerParty - Appears in the XML as <cac:AccountingCustomerParty>
When creating a specific mapping for a supplier, a unique recognition string must be set. It's useful to look at other specific mappings and use them as examples. For instance, the supplier's name is always present in the AccountingSupplierParty field. As seen in the overview, several mappings have set the following recognition string: //cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name='[Supplier Name]', where the last part is replaced with the supplier's name, as seen in the XML invoice.
To test if the recognition string works, manually send the XML invoice to your Spend Cloud mailbox. When the email is received and opened in Spend Cloud, the attachment can be downloaded as a PDF. This PDF is a visualization of the XML invoice, and at the top of this visualization, you can see which mapping will be used to process the invoice.
If the XML-invoice already has been added to your Spend Cloud environment, you can reapply the XML-mapping by clicking on the three dots on the right of the invoice in the Encode menu, after that click on 'reapply text recognition/XML mapping. The Spend cloud will attempt to reply a mapping based on the recognition string if applicable and will also recreate invoice lines if necessary. You can only do this with invoices that have not been coded yet. If you want to perform this on multiple invoices you can use the 'reapply recognition' button on top of the encode overview.
Line Identifier
Once you've successfully set a recognition string, you need to establish a line identifier. This is a field within the XML file that opens each invoice line. By default, this is set to //cac:InvoiceLine, and for UBL invoices, there's no need to change it. If the supplier provides an XML invoice that doesn't follow the UBL format, it's crucial that each invoice line in the file is opened and closed with the same tag.
Invoice Structure
An XML invoice typically consists of a general part, the header of the invoice, followed by the detailed specification of each invoice line. The header contains the information you can use for mapping throughout the whole invoice for the parts invoice data Creditor data and receiver data).
For example, to identify the correct creditor, Spend Cloud primarily searches for the bank account number. By default, it is provided in the field //cac:PaymentMeans/cac:PayeeFinancialAccount/cbc:ID. If the creditor isn't recognized, a possible cause could be a mismatch between the bank account number in the XML file and the one set for the creditor in Spend Cloud, or the creditor may not have included it in the file.
If your supplier provides specific information, such as the general ledger account number, cost center, or cost unit, you can map these. Suppose the supplier includes a cost center number in the field <cbc:AccountingCost>. In that case, you can map it as follows:
This approach allows you to coordinate with suppliers about the data you'd like to see in the XML file, enabling you to have Spend Cloud read this data accurately. This makes the invoice processing process for these suppliers easily automated.
Tips & Tricks
Sometimes, a supplier may not provide specific information in the XML that Spend Cloud can read. Here are some examples:
- The supplier always provides both the cost center number and the name, such as '1000 - Cost Center A.'
- The supplier provides the cost center and cost unit numbers in a single field, for example, '1000-4800.'
- The supplier includes a description for each invoice line, but for processing the invoice, you always want the combination 'Supplier Name - Description' in the line.
With certain functions, you can still extract the correct values. Here are a few functions to help you read the right values:
1. <cbc:AccountingCost>1000 - Cost Center A</cbc:AccountingCost> - You want to extract Cost Center 1000.
Function: substring(cbc:AccountingCost,0,4) - This function extracts a part of the string starting from position 0, reading the next 4 characters.
2. <cbc:AccountingCost>1000-4800</cbc:AccountingCost> - You want to extract Cost Center 1000 and Cost Unit 4800.
Function for Cost Center: substring-before(cbc:AccountingCost,'-') - This function extracts a part of the string before the hyphen.
Function for Cost Unit: substring-after(cbc:AccountingCost,'-') - This function extracts a part of the string after the hyphen.
3. <cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name>Visma|ProActive</cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name> & <cac:InvoiceLine/cac:Item/cbc:Description>Invoice Quarter 1</cac:InvoiceLine/cac:Item/cbc:Description> - You want the description to be "Visma|Proactive - Invoice Quarter 1."
Function: concat(//cac:AccountingSupplierParty/cac:Party/cac:PartyName/cbc:Name,' - ',cac:InvoiceLine/cac:Item/cbc:Description) - The concatenate function combines different values, separating them with a hyphen. In this function, a hyphen is used by placing it in quotes.
Related Articles
Default conditions for UBL in the Spend Cloud
This technical information can be used by your accounting package's developer/application manager. This is how the Spend Cloud reads UBL invoices and processes the values. Curious how you can create your own unique XML field layout (mapping)? Read ...How can I receive XML invoices in the Spend Cloud?
The (design) objective of XML is simplicity, uniformity and usability. In order for these invoices to be read by all computers worldwide, certain rules have been laid down on how an XML invoice must be constructed. This set of standard rules ...Everything you need to know about XML-Invoices
Why process XML invoices? Our goal is to have users spend as little time as possible in the Spend Cloud. The software should do as much as possible automatically, so that our users can focus on other important tasks. Digital invoice processing helps ...Encoding an invoice
In the Coding menu, you'll find all the invoices that can be processed (coded). By clicking on a row or the pencil icon from the overview, you can access the page where you can code the invoice details. Encoding Invoices When you start encoding an ...Configuration settings for Invoice Processing
In the menu section Configuration Settings / Invoice Processing, you will find settings that apply to the Invoice Processing module. Also, read this article for more information on configuration settings. Make sure you understand what each setting ...