Basware Purchase-to-Pay XML integrations guide

This guide describes Basware XML file format integration capabilities used with Basware Purchase-to-Pay (P2P). It contains process-level instructions, end-to-end data flows, as well as recommended practices for implementation and debugging.

The XML integration files are typically generated by customers and sent to Basware using SFTP. This guide describes using the standard XML file format and does not focus on Basware capabilities for doing file format conversions and other custom integrations, such as outgoing webservice calls.

The XML integrations are available for transferring invoices to accounting, importing master data, user data and external purchase orders for invoice matching, as well as for importing and exporting data to and from P2P Purchase. Separate environments are available for test and production systems

Integrating to Basware P2P using XML integrations

Data is exchanged as XML files through Basware SFTP service which is accessible by the customer with authorized credentials from whitelisted IP addresses. Using this standard XML option, the customer provides inbound XML files from their ERP to Basware Cloud P2P system, and Basware provides outbound XML files from its Cloud P2P system to customer ERP.

Basware Standard XML integration Architecture

The file transfer is integrated through a customer specific secure Basware SFTP service which is provisioned as part of service delivery. The customer pushes data to the inbound folder and pulls from the outbound folder with or without the use of a middleware. Basware in turn processes the incoming files as per a schedule that is maintained in the Basware P2P Admin module. Basware’s Scheduling principles, that are documented in the SLA, need to be followed. Invoices transferred to accounting from P2P are available in the outbound folder as soon as they have been processed and are not scheduled. The customer should align their internal file transfer schedule to the agreed Basware schedule.

Technical details

Basware SFTP service is SSH encrypted and authenticated with username and password or a certificate. Customer IP addresses are whitelisted to allow access only from authorized addresses.

When the SFTP integration method is used, files are transferred to and from a single customer specific SFTP site. Inbound and outbound files are synchronized with the Basware P2P Cloud service.

Integration details are documented in the below table:

Fair use practices

Fair usage policy is documented in the Basware services SLA.

Depending on customer business scenarios and the Basware solutions in use, different Basware interfaces will be used. The following integration scenarios are available when integrating to Basware P2P:

• Importing Master data
• Integrating to Basware AP Automation for accounts payable processing
• Integrating to Basware AP Automation for accounts payable processing with Order Matching for external orders
• Integrating Basware Purchase to an external purchasing solution
• Importing users to Basware solutions

For each integration scenario, Basware provides sample XML and schema files.

XML usage scenarios

This section lists the standard interfaces supported by the Basware P2P API and the basic integration logic. The interfaces to be implemented are selected based on customer requirements. Additional data can be imported using the generic header or coding dimension interfaces.

Basware solutions require a set of master data that replicate the Customer’s business model in Basware. This data is required to enhance the processing of business documents and makes it possible to bring all, or suitable parts of the validation logic to Basware.

As best practice, master data should be maintained in one central place. This data nearly always sits in an organization’s main ERP system. Multi ERP scenarios are also supported.

Integrations where delta load is supported are able to receive only the changed records, which is also the best practice. Integrations where delta load is not supported require sending the full set of records each time the data is updated. In these interfaces old data will be fully replaced with the new records.

Usage scenario 2: Import external purchase orders for Order Matching

In order matching a purchase order, purchase order line, or a goods receipt is linked to an invoice or invoice line. Basware XML integration supports importing external Purchase orders from customer systems to match invoices to existing orders. These orders need to be fully processed and approved in external systems.

These external matching orders are used only for automatic matching to received invoices. Creating, approving and sending orders can be also done in Basware P2P using "Purchase" module, which has another set of APIs to integrate the purchasing process with external purchasing systems (see section "Usage scenario 4: Import and export procurement data").

Basware supports importing the following purchase order types:

• Standard (quantity-based) purchase order is the most used order type. Standard purchase order identifies the ordered goods or service. It also contains information of the ordered quantity and unit price. Purchase orders can be imported for 2-way matching without receipts and for 3-way matching with goods receipts. This order type enables matching invoices with both inventory purchase orders and cost-based purchase orders
• Return purchase order is a variation of the standard purchase order. It is used for returning goods or services when the return has no relation to an earlier standard purchase order. The difference to the standard purchase orders is in the negative unit price. Purchase orders can be imported for 2-way matching without receipts and for 3-way matching with goods receipts.
• Blanket (value-based) purchase order does not specify ordered quantity. Blanket purchase order identifies the ordered goods or service only with monetary value. Purchase orders can be imported for 2-way matching without receipts and for 3-way matching with service entries.
  • Blanket purchase order without receipts that enables 2-way matching is also known as framework order.
  • Blanket purchase order with receipts that enables 3-way matching is also known as service purchase order.
• Service purchase order is used for procuring services.

Usage scenario 3: Prebook and transfer invoices to Accounting

Once an invoice has been approved in P2P, it is routed to AP/finance users for transfer to accounting. In this phase, the invoice and its coding data are transferred to an ERP system for payment. Triggering invoice transfer to ERP can done either manually or automatically from P2P.

Invoice prebooking is an optional feature that can be enabled if required.

Invoice transfer consists of the following steps:

1. Get invoice data from prebook XML file from P2P (optional)
2. Send prebook succeeded / failed XML file from ERP (optional)
3. Get reverse prebook XML file from P2P (optional)
4. Get invoice data from transfer XML file from P2P
5. Send transfer succeeded / failed XML file from ERP (optional)
6. Send payment information XML file from ERP (optional)

Usage scenario 4: Import and export procurement data

External procurement data can be imported as requisitions or pre-approved orders and goods receipts into the Basware Purchase module. Basware Purchase handles the procurement process. It allows users to approve the purchase requisition, sends created order(s) out to supplier(s), handles any changes done in ordering phase and allows documenting that goods have been received. Orders created in Basware Purchase are also automatically available for invoice matching along with the documented goods receipts.

Orders created or edited in Basware Purchase can also be exported to an external system with the Order Data Export XML. Exported orders also include goods receipts when they are registered in Basware Purchase.

Below picture illustrates available order and requisition document flows. The operations between P2P and purchasing system can be performed using Basware XML interfaces.

Usage scenario 5: Import users

New or updated users can be imported into Basware P2P using the username (LoginAccount) as a key field. The interface supports assigning users to P2P user groups to control user rights. If you need to define invoice approval rights for users on coding row level, you can also import these using 'advancedPermissions' interface.

General guidelines for building integrations

Each record needs to be only once per company in the input file

Each record needs to be only once per company in the input file , i.e. Cost Center code '2800' should have a single (not multiple) entries when it is used on the same company. This applies to items where the value needs to be unique, such as accounts, vendors, cost centers and orders. It does not apply to AdvancedPermissions, where multiple permission rules can be specified for the same user. It is also ok to use the same record code on several companies, as long as it is used only once per company.

Schema validate XML files sent to Basware P2P before testing with P2P

Please validate the files you send to Basware against the .xsd schema files before sending them to be loaded to P2P for the first time. The schema validation will catch most of the errors and delivery time will be reduced.

New fields will be added to XML files over time

Please note that Basware will add new fields from time to time to both outgoing and incoming integrations. Please build the receiving end for exported XML documents so that it can cope with additional fields being added without crashing or failing schema validation.

Test all expected scenarios

Test your integrations using all expected scenarios, for example in case of invoice transfer, check standard invoice, negative sums, reverse VAT, foreign currency invoices, multiple coding lines, coding lines having special handling in ERP system, etc. This will help to ensure smooth production use later on. See API testing guidelines for scenarios which might be applicable.

Validate XML files with P2P before implementation start when using 3rd party integrator

When working with 3rd party integrators, Basware recommends manually creating example XML files using actual customer data and verifying they load correctly to P2P in order to get details of the specification right from the start. This will likely speed up delivery time and prevent costs from additional iterations. The example files can be created manually by populating customer data to Basware XML example files and removing those fields which will not be used.

Delta load supported vs. not supported differs per interface

Some of the XML interfaces support delta load. For these interfaces P2P keeps existing records while updating those records which have been sent in the XML integration file. Best practice is to send only changed records in interfaces supporting delta load, such as in Suppliers and Orders interfaces. Interfaces which need to be scheduled to update the data frequently should send only changed records. Note that in delta load interfaces record deactivation requires sending the deacticated record with <Active>false</Active> flag in order to deactivate the record in P2P.

Interfaces where delta load is not supported operate on a delete/insert paradigm. These interfaces cannot receive only changed resords as they require sending the full set of active records each time data is updated. For such interfaces, existing data is first cleared and then new data is loaded from the XML integration file.

Handling multiple ERP systems

It is generally a good practice to send one file per data type per ERP system,  such as accounts of all "ERP 1" companies. The organization structure created in P2P affects how the data is loaded. Your P2P consultant will advise how to distribute the data to files in your specific case.

Configurability

The file names and names of input fields are configurable in Basware P2P. This site describes the standard configuration.

Extending integrations to manage customer specific requirements

In addition to standard XML integrations, it is possible to build customer integrations to support customer specific requirements. It is also possible to add additional logic to loading the data files. Building custom integrations requires additional effort throughout the integration lifecycle, from build to operations and support. Custom integration may be subject to additional fees. Feasibility is subject to Basware evaluation.

Basware can also use customer specific file formats with additional integration work.

Terminology

Entity type: Named structured types with a key. They define the named properties and relationships of a record. Examples: accounts, costCenters, matchingOrderLines.

Record: Instances of entity types (e.g. account, opportunity).

Accounting system: Computer program used for keeping accounts. Commonly included in an ERP system as a module.

ERP: Enterprise resource planning (ERP) is defined as the ability to deliver an integrated suite of business applications. ERP tools share a common process and data model, covering broad and deep operational end-to-end processes, such as those found in finance, HR, distribution, manufacturing, service and the supply chain.

Basware P2P: Basware Purchase-to-Pay, in this manual refers to Basware Purchase-to-Pay solution.

Basware AP Automation: Accounts Payable Automation solution. Part of Basware P2P.

Basware Purchase: Basware Purchase solution. Part of Basware P2P.