The Peppol Business Interoperability Specification, “BIS” from here on after, has been developed by the OpenPeppol AISBL Post Award Coordinating Community and is published as part of the Peppol specifications.

Statement of copyright

This Peppol Business Interoperability Specification (BIS) document is based on the CEN CWA prepared by the BII workshop specified in the introduction below. The original CEN CWA document contains the following copyright notice which still applies:

© 2012 CEN All rights of exploitation in any form and by any means reserved worldwide for CEN national Members.

The CEN CWA documents and profiles prepared by the BII workshop are not specific to a business area. Subject to agreement with CEN, customizations have been made by Peppol to establish the Peppol BIS, detailing and adding further guidance on the use of BII profiles.

OpenPeppol AISBL holds the copyright in the customizations made to the original document. The customizations appear from the corresponding conformance statement which is attached to this document. For the purpose of national implementations, customizations covered by the conformance statement may be further refined and detailed by Peppol Authorities and/or other entities authorized by OpenPeppol AISBL, provided that interoperability with Peppol BIS is ensured. This Peppol BIS document may not be modified, re-distributed, sold or repackaged in any other way without the prior consent of CEN and/or OpenPeppol AISBL.

Link to main site of documentation

Main documentation site

1. Introduction to openPeppol and BIS

This BIS is a result of work within OpenPeppol and is published as part of the Peppol specifications.

This Peppol BIS provides a set of specifications for implementing a Peppol business process. The document is concerned with clarifying requirements for ensuring interoperability of pan-European Public eProcurement and provides guidelines for supporting these requirements and how to implement them. This Peppol BIS is based on the CEN BII2 Profile 36, Message Level Response.

The purpose of this document is to describe a common format for the message level response message in the European market, and to facilitate an efficient implementation and increased use of electronic collaboration regarding the message level response process based on this format.

BII relationship
Figure 1. Relationship between BII profiles and Peppol BIS

1.1. Audience

The audience for this document is organizations wishing to be Peppol enabled for exchanging electronic business documents, and/or their ICT-suppliers.

These organizations may be:

  • Service providers

  • Contracting Authorities

  • Economic Operators

  • Software Developers

More specifically it is addressed towards the following roles:

  • ICT Architects

  • ICT Developers

  • Business Experts

For further information, please see Peppol BIS common text and introduction.

2. Principles and prerequisites

This chapter describes the principles and assumptions that underlie the use of the Peppol Message Level Response message. It is based on the CEN BII2 Profile 36, Message Level Response.

A Messaging Level Response message can be used in the choreography of the exchange of a business document to improve reliability by allowing a receiver of a business document to inform the sender about the results of receivers validations and, in case of negative results, to inform the sender about the nature of the errors as well as their details

They may allow the sender of the document to take appropriate action.

2.1. Message Level Response message in general

Through the start to end flow of a message exchange; from the creation of an electronic message, down the transport line that goes through one or more transport networks to the designated receiver and all way through the eventual processing of the message content, there may be need to give responses to the relevant parties up-line about the status or results of the actions that the message goes through. These responses are of different nature but for the purpose of this document they can be divided into the following main groups.

Transport acknowledgements

These are messages that are exchanged within the transport network(s) to inform about the process of carrying a message down the transport line. These responses may inform someone up-line that the delivery to a given point was successful or not and may contain details about issues that are relevant such as why a delivery was not successful. The key nature of these responses is that they do not in any way act on result of validation or processing of the content of the payload that is being transported. These response messages are commonly called “acks”.

Message Level Responses

When a message has reached a given point in the transport line its content may be validated according to agreed specifications that may be both syntactical and semantic. The outcome of these validations may be reported to a relevant party up-line, informing him whether the validation was successful or not as well as giving some details. An example could be that an order message that is received is rejected because it is missing a closing tag (syntax error) or because its amounts don’t add up according to what is specified in the relevant syntax specification. A key nature of these messages is that they report on the message content on the basis of the technical specifications that apply.

Business Level Responses

A message that has been received and accepted for processing may call for an action on the receiver’s behalf. That receiver’s action may need to be reported back up-line to a relevant party. An example is that a technically correct order may be received but the receiver decides to reject the order for any business reason such as out-of-stock situation, expired contract etc. The key nature of these responses is that they report a business decision that is made on the message instance received.

This specification is only concerned with the Message Level Responses.

response
Figure 2. Flow of different response messages

2.2. Scope

The Message Level Response message is intended to inform the issuer of the following situations

  1. The received message contained errors according to the relevant conformance rules.

    • The message will not be processed any further.

  2. The received message passed the validation of conformance rules without any fatal errors.

    • The message will be processed further.

  3. The received message is not validated for conformance but the receiver acknowledges that it has been received and identified as a business message.

    • The message will be processed further.

2.2.1. The following errors are within the scope for a negative/rejecting Message Level Response:

  • XML schema validation error

  • Standard Compliance violations (e.g. empty elements not being allowed by UBL 2.1)

  • Validation error of type fatal error

  • Validation error of type warning. Warnings alone must NOT cause rejection of the business document (but they may be reported in addition to fatal errors)

  • Wrong version of business document (Will be handled like validation error of type fatal error)

2.2.2. The following errors are outside the scope of the message level response:

  • Unknown sender (in scope of transport acknowledgement)

  • Unknown receiver (in scope of transport acknowledgement)

  • Wrong version of envelope (in scope of transport acknowledgement)

  • XML schema validation error – envelope (in scope of transport acknowledgement)

  • XML not well formed (in scope of transport acknowledgement)

  • Non supported encoding (in scope of transport acknowledgement)

  • Wrong value (after database look-up) in reference fields (in scope of Business Level Response).

    • Examples:

      • Wrong order number in invoice

      • Wrong project or customer reference in invoice

      • Wrong contract ID reference in catalogue

2.3. Parties and roles

The table below gives the definitions of the parties and roles of the message level response process. The sender and receiver of the Message Level Response message should be extracted from the envelope, i.e. the Peppol participants.

Business partners

Description

Sender

The party sending an electronic message level response message back to the sending party of the business document.

Receiver

The party, an electronic message level response was addressed to, and who is supposed to process the message level response.
This is the same party as the sender of the business document.
roles 36

3. Process and typical use cases

3.1. Business process Diagram

3.1.1. Legend for BPMN diagrams

The diagrams are expressed in the BPMN notation. The diagram below serves as an explanation for the diagrams used in the process descriptions.

bpmn legend
Figure 3. BPMN legend

3.2. Process in general

The process starts when a BusinessDocumentSender is preparing an electronic business document and then sends it. The BusinessDocumentReceiver receives the business document and potentially validates syntax and business rules.

  1. If the BusinessDocumentSender has requested an MLR back, the BusinessDocumentReceiver either:

    1. Validates the business document and based on the result returns either an accept (no fatal errors) or a reject (fatal errors found)

    2. Doesn’t validate the business document and just sends a MLR with a response code indicating the message is acknowledged.

This specification does not prescribe how a request for MLR is made or communicated.

  1. If the BusinessDocumentSender hasn’t requested an MLR back, the BusinessDocumentReceiver either:

    1. Validates the business document and if fatal errors are found, returns a reject.

    2. Doesn’t respond with a MLR in case no fatal errors are found.

If a MLR is returned the MLRReceiver must be notified and take appropriate action. If the response is positive the MLRReceiver may update the status of the business document or simply ignore the MLR.

bpmn mlr 1

3.3. Typical use cases

3.3.1. Parties/Roles:

In the use case descriptions below the following terms are used:

BusinessDocumentSender

Sender party in the role of sending a business document
BusinessDocumentReceiver

Receiving party in the role of receiving a business document
MLRSender

Sender party in the role of sending a MLR document
MLRReceiver

Receiver party in the role of receiving a MLR document
In the use cases the BusinessDocumentSender is the same physical party as the MLRReceiver and the BusinessDocumentReceiver is the same physical party as the MLRSender.

3.3.2. Use Case 1 – Positive response

This use case is a message level response containing no errors, ie a positive response.

Use Case number 1

Use Case Name

Positive response

Use Case Description

This use case is a message level response based on a business document with no errors, ie a positive response.

Parties involved

BusinessDocumentSender, MLRReceiver
BusinessDocumentReceiver, MLR Sender

Assumptions

  1. The BusinessDocumentReceiver has received an electronic business document from the BusinessDocumentSender.

  2. The BusinessDocumentReceiver has validated the business document from the BusinessDocumentSender.

  3. The result of the validation is OK, no fatal errors.

The flow

  1. The BusinessDocumentSender has prepared and sent an electronic business document to the BusinessDocumentReceiver.

  2. The BusinessDocumentReceiver has received the business document.

  3. The BusinessDocumentReceiver has validated the business document.

  4. The MLRSender has sent a message level response message back to the BusinessDocumentSender.

  5. The MLRReceiver has received and processed the message level response message.

Result

  1. The message level response message helped the BusinessDocumentSender to confirm that the business document was received and validated with no errors by the BusinessDocumentReceiver.

XML example file

See Appendix A for a sample file illustrating Use Case 1.

3.3.3. Use Case 2 – Negative response – violation of business rules

This use case is a message level response containing errors due to violation of business rules.

Use Case number 2

Use Case Name

Negative response – violation of business rules

Use Case Description

This use case is a message level response based on a business document containing errors due to violation of business rules.

Parties involved

BusinessDocumentSender, MLRReceiver
BusinessDocumentReceiver, MLR Sender

Assumptions

  1. The BusinessDocumentReceiver has received an electronic business document from the BusinessDocumentSender.

  2. The BusinessDocumentReceiver has validated the business document from the BusinessDocumentSender.

  3. The result of the validation is not OK due to violation of business rules.

The flow

  1. The BusinessDocumentSender has prepared and sent an electronic business document to the BusinessDocumentReceiver.

  2. The BusinessDocumentReceiver has received the business document.

  3. The BusinessDocumentReceiver has validated and rejected the business document.

  4. The MLRSender has sent a message level response message back to the BusinessDocumentSender.

  5. The MLRReceiver has received and processed the message level response message and performed appropriate action due to the rejection.

Result

  1. The message level response message helped the BusinessDocumentSender to confirm that the business document was received and rejected by the BusinessDocumentReceiver. The BusinessDocumentSender must take appropriate action to correct and resend the business document.

XML example file

See Appendix A for a sample file illustrating Use Case 2.

3.3.4. Use Case 3 – Negative response – violation of syntax and business rules

This use case is a message level response containing errors and warnings due to violation of syntax and business rules.

Use Case number 3

Use Case Name

Negative response – violation of business rules, business rules warnings and violation of syntax

Use Case Description

This use case is a message level response based on a business document containing errors and warnings due to violation of business rules and syntax.

Parties involved

BusinessDocumentSender, MLRReceiver
BusinessDocumentReceiver, MLR Sender

Assumptions

  1. The BusinessDocumentReceiver has received an electronic business document from the BusinessDocumentSender.

  2. The BusinessDocumentReceiver has validated the business document from the BusinessDocumentSender.

  3. The result of the validation is not OK due to violation of business rules and syntax.

The flow

  1. The BusinessDocumentSender has prepared and sent an electronic business document to the BusinessDocumentReceiver.

  2. The BusinessDocumentReceiver has received the business document.

  3. The BusinessDocumentReceiver has validated and rejected the business document.

  4. The MLRSender has sent a message level response message back to the MLRReceiver.

  5. The MLRReceiver has received and processed the message level response message and performed appropriate action due to the rejection.

Result

  1. The message level response message helped the BusinessDocumentSender to confirm that the business document was received and rejected by the BusinessDocumentReceiver. The BusinessDocumentSender must take appropriate action to correct and resend the business document.

XML example file

See Appendix A for a sample file illustrating Use Case 3.

4. Semantic datatypes

Semantic data types are used to bridge the gap between the semantic concepts expressed by the information elements and the technical implementation. The semantic data types define the allowed value domain for the content, and any additional information components (attributes) needed in order to ensure its precise interpretation.

4.1. Primitive types

Semantic data type content may be of the following primitive types. These primitive types were taken from ISO 15000-5:2014, Annex A.

Primitive type Definition

Binary

A set of finite-length sequences of binary digits.

Date

Time point representing a calendar day on a time scale consisting of an origin and a succession of calendar ISO 8601:2004.

Decimal

A subset of the real numbers, which can be represented by decimal numerals.

String

A finite sequence of characters.

4.2. Semantic data types

The different semantic data types are described in the tables below, where various features such as attributes, format, and decimals as well as the basic type are defined for each semantic data type. They are based on ISO 15000-5:2014.

When used in an instance document, each data element will contain data. In the below tables this is identified as the “content”. Whenever a business term is used this term shall always have content and therefore the content is always mandatory.

4.2.1. Amount

An amount states a numerical monetary value. The currency of the amount is defined as a separate business term.

Amount is floating up to two fraction digits.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.25

4.2.2. Price Amount

A price amount states a numerical monetary amount value for data elements that contain item prices that may be multiplied by item quantities. The currency of the amount is defined as a separate business term.

Unit price amount does not set restrictions on number of decimals, as contrast to the Amount type
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.1234

4.2.3. Percentage

Percentages are given as fractions of a hundred (per cent) e.g. the value 34,78 % in percentage terms is given as 34,78.

No restriction on number of decimals for percentages.
Component Use Primitive Type Example

Content

Mandatory

Decimal

34.7812

4.2.4. Quantity

Quantities are used to state a number of units such as for items. The code for the Unit of Measure is defined as a separate business term.

No restriction on number of decimals for quantities.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.1234

4.2.5. Code

Codes are used to specify allowed values in elements as well as for lists of options. Code is different from Identifier in that allowed values have standardized meanings that can be known by the recipient.

Codes shall be entered exactly as shown in the selected code list
Component Use Primitive Type Example

Content

Mandatory

String

Abc123

4.2.6. Identifier

Identifiers (IDs) are keys that are issued by the sender or recipient of a document or by a third party.

The use of the attributes is specified for each information element.
Component Use Primitive Type Example

Content

Mandatory

String

abc:123-DEF

Scheme identifier

Conditional

String

0088

Scheme version identifier

Conditional

String

1.0

4.2.7. Date

Dates shall be in accordance to the “Calendar date complete representation” as specified by ISO 8601:2004, format YYYY-MM-DD.

Dates shall not include timezone information.
Table 1. EN 16931_ Date. Type
Component Use Primitive Type Example

Content

Mandatory

Date

2017-12-01

4.2.8. Time

Time shall be in accordance to the “Extended time format” as specified by ISO 8601:2004,
- format without time zone [hh]:[mm]:[ss]
- format with UTC timezone [hh]:[mm]:[ss]Z
- format for other zones [hh]:[mm]:[ss]±[hh:mm] with zone is given as difference from UTC.

Time may include timezone information.
Decimal fraction on seconds SHALL not be used.
Table 2. EN 16931_ Date. Type
Component Use Primitive Type Example

Content

Mandatory

Date

09:30:12

4.2.9. Document Reference

Document Reference Types are identifiers that were assigned to a document or document line.

Table 3. Document Reference. Type
Component Use Primitive Type Example

Content

Mandatory

String

abc:123-DEF

4.2.10. Text

Text is the actual wording of anything written or printed. Line breaks in the text may be present, and any line breaks should be preserved and respected by the receiver’s system

Component Use Primitive Type Example

Content

Mandatory

String

5% allowance when paid within 30 days

4.2.11. Binary objects

Binary objects can be used to describe files which are transmitted together with the business document. Attachments shall be transmitted together with the business document. The binary object has two supplementary components: a Mime Code, which specifies the Mime type of the attachment and a Filename that is provided by (or on behalf of) the sender of the business document.

Component Use Primitive Type Example

Content

Mandatory

Binary

QmFzZTY0IGNvbnRlbnQgZXhhbXBsZQ==

Mime Code

Mandatory

String

image/jpeg

Filename

Mandatory

String

drawing5.jpg

4.2.12. Boolean

Boolean indicators are used to specify the two allowed values, true or false. All elements of datatype Boolean, must have either true or false as their value.

Component Use Primitive Type Example

Content

Mandatory

Boolean

true

5. Code lists

5.1. Code lists for coded elements

Any element with the semantic data type = code, can mandate the use of a specific code list (or a fixed value). The applicable code lists can be found in the Code list section. In this section, you can find the valid codes, their names and description, and also links to where the same code list is used elsewhere in the transaction, or in other Peppol BIS v3. documents.

5.2. Code list for identifiers

5.2.1. Party identifiers and party legal registration identifier scheme

All party identifiers (cac:PartyIdentification/cbc:ID) and party legal registration identifier (cac:PartyLegalEntity/cbc:CompanyID) has an optional scheme identifier attribute (@schemeID). If used, the value shall be chosen from the code list ICD codes

Examples of usage in cac:PartyIdentification
<cac:PartyIdentification>
        <cbc:ID schemeID="0088">5790000435968</cbc:ID> (1)
</cac:PartyIdentification>
1 schemeID attribute is optional, but when used, the codes must be from ICD codes

5.2.2. Electronic address identifier scheme identifier

All electronic address identifiers (cbc:EndpointID/@schemeID) use the Electronic Address Scheme code list (EAS), maintained by CEF (CEF Code lists).

Valid values are found here: EAS codes.

Examples of usage in cbc:EndpointID
<cbc:EndpointID schemeID="0184">DK87654321</cbc:EndpointID> (1)
1 schemeID attribute is mandatory

6. Description of selected parts of the message level response message

6.1. Party identification

6.1.1. Sender Party

The element cac:SenderParty/cbc:EndpointID MUST contain the party identification of the receiver of the original envelope.

Example:
<cac:SenderParty>
    <cbc:EndpointID schemeID="0192">987654325</cbc:EndpointID>
</cac:SenderParty>

6.1.2. Receiver Party

The element cac:ReceiverParty/cbc:EndpointID MUST contain the party identification of the sender of the original envelope.

Example:
<cac:ReceiverParty>
    <cbc:EndpointID schemeID="0088">7315458756328</cbc:EndpointID>
</cac:ReceiverParty>

6.2. Document response

The document response is used to indicate the result of business document validation. See chapter Code lists for all code list values.

Exactly one cac:DocumentResponse element MUST be present. The element cac:DocumentResponse/cac:Response/cbc:ResponseCode MUST contain the overall result code.

In case the document is rejected, the cbc:Description element MUST be set.

Example for acceptance:
<cac:Response>
    <cbc:ResponseCode>AP</cbc:ResponseCode>
</cac:Response>
Example for acknowledging:
<cac:Response>
    <cbc:ResponseCode>AB</cbc:ResponseCode>
    <cbc:Description>The document was accepted without any validations being performed.</cbc:Description>
</cac:Response>
Example for rejection:
<cac:Response>
    <cbc:ResponseCode>RE</cbc:ResponseCode>
    <cbc:Description>The document was rejected because it failed validation</cbc:Description>
</cac:Response>

6.3. Document reference

The document reference is used to provide a reference to the envelope of the business document on which the message level response is based. The message level response message may only cover exactly one business document. The element cac:DocumentResponse/cac:DocumentReference/cbc:ID MUST contain the instance identifier of the envelope of the original business document.

Example:
<cac:DocumentReference>
          <cbc:ID>EnvelopeID-12456789</cbc:ID>
</cac:DocumentReference>

7. Peppol Identifiers

Peppol has defined a Peppol Policy for identifiers, policy 8 that specifies how to use identifiers in both its transport infrastructure and within the documents exchanged across that infrastructure. It also introduces principles for any identifiers used in the Peppol environment. The policies that apply to this BIS are the following:

7.1. Profiles and messages

All messages contains ProfileID and CustomizationID. ProfileID identifies what business process a given message is part of, and CustomizationID identifies the kind of message and the rules applied.

Profiles are connected to one business process, and may contain multiple document types. Valid document instances shall contain corresponding ProfileID and CustomizationID.

CustomizationID is a string without spaces. The list below contains spaces in CustomizationID to make them easier to read. Make sure to remove any spaces before use.

7.2. Customization and Profile identifiers

In the table below you will find the values to be used as the specification identifier and the business process type for this profile

Type Element cbc:CustomizationID Element cbc:ProfileID

Message level response (Trdm071)

urn:fdc:peppol.eu:poacc:trns:mlr:3

urn:fdc:peppol.eu:poacc:bis:mlr:3

7.3. Namespaces

The message level response data model is in this Peppol BIS bound to the UBL Application Response 2.1. The target namespace for the UBL-ApplicationResponse-2.1 is:

urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2