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.
Link to main site of documentation
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.
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.
2.2. Scope
The Message Level Response message is intended to inform the issuer of the following situations
-
The received message contained errors according to the relevant conformance rules.
-
The message will not be processed any further.
-
-
The received message passed the validation of conformance rules without any fatal errors.
-
The message will be processed further.
-
-
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. |
3. Process and typical use cases
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.
-
If the BusinessDocumentSender has requested an MLR back, the BusinessDocumentReceiver either:
-
Validates the business document and based on the result returns either an accept (no fatal errors) or a reject (fatal errors found)
-
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. |
-
If the BusinessDocumentSender hasn’t requested an MLR back, the BusinessDocumentReceiver either:
-
Validates the business document and if fatal errors are found, returns a reject.
-
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.
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 |
Assumptions |
|
The flow |
|
Result |
|
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 |
Assumptions |
|
The flow |
|
Result |
|
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 |
Assumptions |
|
The flow |
|
Result |
|
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. |
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 [hh]:[mm]:[ss].
Time shall not include timezone information. Decimal fraction on seconds SHALL not be used. |
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.
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 |
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
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.
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.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.
<cac:Response>
<cbc:ResponseCode>AP</cbc:ResponseCode>
</cac:Response>
<cac:Response>
<cbc:ResponseCode>AB</cbc:ResponseCode>
<cbc:Description>The document was accepted without any validations being performed.</cbc:Description>
</cac:Response>
<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.
<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