OIOUBL BIS Message Level Response

v3.0.1 RC

The Business Interoperability Specification, called the “OIOUBL BIS” from here on, has been developed by the Danish Business Authority.

1. Document Structure

This document is structured as follows:

Chapter 2 Provides general information on the business principles and processes
Chapter 3 Describes the business processes for typical use cases
Chapter 4 Provides information about identifiers, e.g. customization and profile identifiers
Chapter 5 Provides examples of selected parts of the Message Level Response
Chapter 6 Statement of license and copyright
Chapter 7 Link to the main site for additional documentation. documentation

2. Business Principles and Prerequisites

This chapter describes the principles and assumptions that underlie the use of the OIOUBL 3 Message Level Response.

A Messaging Level Response can be used where there is a requirement to inform the sending party about the technical validity (or not) of a received business document. It informs the sender about the results of the receiver’s validation and, in case of negative results, the details of the error(s).

The error information allows the sender party of the original business document to take appropriate action when required.

The Message Level Response covers two distinct types of error:

Syntax errors, which are errors that the sending Nemhandel access point had a duty to identify prior to sending the message (schematron errors).
Semantic errors, which are errors that are not identified by the automatic checks that the sending access point is obligated to execute, but which nonetheless make the document unreadable, illegal or otherwise structurally invalid.

These two classes of error correspond to the two different Message Level Response profiles: Message Level Response - Network (for syntax errors) and Message Level Response (for semantic errors).

This distinction is useful for ensuring that errors are addressed to the correct party in the transaction: A syntax error is the fault of the sending party’s access point, which has failed its obligation to validate all outgoing communication against the relevant schematrons. A semantic error is the fault of either the commercial sending party or their IT provider, which constructed a document that, although it passes all mandatory automated validations, cannot be meaningfully processed by the recipient.

The OIOUBL Message Level Response is only intended to be used in the context of documents transmitted through the Nemhandel eDelivery network. The OIOUBL Message Level Response references data from the Nemhandel eDelivery transmission protocol, which is not contained in the payload of the business document that it responds to.

The Message Level Response deviates from the general OIOUBL 3 design principles, in that fields that are not explicitly supported are excluded by default, rather than being merely unsupported. This is to ensure maximum compatibility with Peppol Message Level Responses.

The field /ApplicationResponse/UBLVersionID is an exception to the above deviation: This field is unsupported, but not excluded. This exception is to ensure compatibility with certain existing systems, which require this information in order to correctly associate the response documents to the original business document.

2.1. Message Level Response General

Once an electronic business message is delivered to the recipient, there may be a need to inform involved parties about the message’s status or validation results. These response types are different in nature, and for the purpose of this document they can be divided into the following main groups:

Transport acknowledgements: This message is exchanged within the transport network(s), to inform on the status of a message which is being exchanged between parties. These responses may inform a counterparty about the status of a delivery (success/failure/in process), and may contain details about relevant issues, such as why a delivery was not successful. The key feature of these responses is that they do not inform on results of validation or processing of the of the payload content that is being transported. These response messages are commonly called “acks”.
Message Level Responses: When a message has reached a given point in a data exchange, its content may be validated according to agreed specifications. Such specifications may be syntactical and/or semantic. The outcome of these validations may be reported to a relevant up-stream party. These outcomes include the success or failure of the validation, along with additional explanatory details on errors. An example could be an order message that is rejected after receipt, because the subtotals do not add up to the order total (syntax error), or because a free text field is used to provide information for which the BIS prescribes a specific data structure (semantic error). Message level responses do not report on the business content of the communication, only on syntactic and semantic (in)validity.
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-stream to a relevant party. An example is where a technically correct order may be received but the receiver decides to reject the order for a business reason such as an out-of-stock situation, expired contract etc. The key feature of these responses is that they report a business decision that is made on the message instance which is received.

This specification is only concerned with the Message Level Responses.

Figure 1. Flow of different response messages

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 errors.
Standard Compliance. violations (e.g. empty elements not allowed in 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.
Business error or dispute (in scope of Business Level Response).
- Examples:
  - Invoiced amount does not match delivered amount.
  - Ordered amount does not meet minimum orderable amount.
  - Payment terms not as agreed.

Note: Schema validation errors should be caught already in the Nemhandel eDelivery transport layer, but if this fails schema validation errors can be raised to the sender in a message level response.

2.3. Parties and roles

The table below gives the definitions of the parties and roles in the Message Level Response process.

Business partners

Description

Sender

The party sending an electronic Message Level Response back to the sending party of the business document.

This is always the receiving party of the business document being responded to (in the case of an invoice, the AccountingCustomerParty).

Receiver

The party an electronic Message Level Response was addressed to, and who is supposed to process the Message Level Response.

This is either:
* If the Message Level Response is sent with the Message Level Response profile, the Receiver is sending party of the business document being responded to (in the case of an invoice, the AccountingSupplierParty), or
* If the Message Level Response is sent with the Message Level Response - Network profile, the Receiver is the sending access point listed in the eDelivery document envelope or header, as specified in the Nemhandel eDelivery AS4 transport protocol specification.

3. Business Process and Typical Use Cases

The process starts when a Business Document Sender is preparing an electronic business document and then sends it. The Business Document Receiver receives the business document and potentially validates syntax and business rules.

If the Business Document Sender has not requested a Message Level Response, the Business Document Receiver shall either:
1. Validate the business document and return a 'reject' if fatal errors are found.
2. Not respond with a Message Level Response if no fatal errors are found.
If the Business Document Sender has requested an Message Level Response back, the Business Document Receiver shall either:
1. Validate the business document and based on the result returns either an 'accept' (no fatal errors) or a 'reject' (fatal errors found)
2. Not validate the business document and send a Message Level Response with a response code indicating the message is acknowledged.

This specification does not prescribe how a request for Message Level Response is made or communicated.

If a Message Level Response is returned, the Message Level Response Receiver must be notified and take appropriate action. If the response is positive, the Message Level Response Receiver may update the status of the business document or simply ignore the Message Level Response.

3.1. Typical use cases

3.1.1. Parties/Roles:

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

Business Document Sender	Sender party in the role of sending a business document
Business Document Receiver	Receiving party in the role of receiving a business document
Message Level Response Sender	Sender party in the role of sending a Message Level Response document
Message Level Response Receiver	Receiver party in the role of receiving a Message Level Response document
Service Provider (on behalf the Business Document Receiver)	Receiving party in the role of receiving a business document. The receiving access point (corner 3 in the eDelivery 4-corner framework).

In all the use cases the Business Document Sender is the same physical party as the Message Level Response Receiver and the Business Document Receiver is the same physical party as the Message Level Response Sender.

3.1.2. Use Case 1 – 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 rules.

Use Case number	1
Use Case Name	Negative response – violation of business rules, business rule warnings and violation of syntax
Use Case Description	This use case is a Message Level Response to a business document that contains errors and warnings, due to violation of business rules and syntax.
Parties involved	Business Document Sender Message Level Response Receiver Service Provider (on behalf of the Business Document Receiver) Message Level Response Sender
Assumptions	The Service Provider (on behalf of the Business Document Receiver) has received an electronic business document from the Business Document Sender. The Service Provider (on behalf of the Business Document Receiver) has validated the business document from the Business Document Sender. The result of the validation is not OK due to violation of business rules and/or syntax.
The flow	The Business Document Sender has prepared and sent an electronic business document to the Service Provider (who is working on behalf of the Business Document Receiver). The Service Provider (on behalf of the Business Document Receiver) has received the business document. The Service Provider (on behalf of the Business Document Receiver) has validated and rejected the business document. The Message Level Response Sender sends a Message Level Response back to the Message Level Response Receiver (using the Message Level Response Network document profile). The Message Level Response Receiver receives and processes the message level response message and performs appropriate action due to the rejection.
Result	The Message Level Response provides the Business Document Sender’s Service Provider with a confirmation that the business document was received and rejected by the Business Document Receiver’s Service Provider (on behalf of the Business Document Receiver), due to an error which should have been detected by the Business Document Sender’s Service Provider prior to sending (schema or syntax error). The Business Document Sender’s Service Provider must take appropriate action to correct and resend the business document, or follow up with the Business Document Sender to correct invalid data. The Business Document Sender’s Service Provider should also investigate the root cause of their failure to properly validate the document prior to sending, and take appropriate corrective action.

Use Case number

Use Case Name

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

Use Case Description

This use case is a Message Level Response to a business document that contains errors and warnings, due to violation of business rules and syntax.

Parties involved

Business Document Sender
Message Level Response Receiver
Service Provider (on behalf of the Business Document Receiver)
Message Level Response Sender

Assumptions

The Service Provider (on behalf of the Business Document Receiver) has received an electronic business document from the Business Document Sender.
The Service Provider (on behalf of the Business Document Receiver) has validated the business document from the Business Document Sender.
The result of the validation is not OK due to violation of business rules and/or syntax.

The flow

The Business Document Sender has prepared and sent an electronic business document to the Service Provider (who is working on behalf of the Business Document Receiver).
The Service Provider (on behalf of the Business Document Receiver) has received the business document.
The Service Provider (on behalf of the Business Document Receiver) has validated and rejected the business document.
The Message Level Response Sender sends a Message Level Response back to the Message Level Response Receiver (using the Message Level Response Network document profile).
The Message Level Response Receiver receives and processes the message level response message and performs appropriate action due to the rejection.

Result

The Message Level Response provides the Business Document Sender’s Service Provider with a confirmation that the business document was received and rejected by the Business Document Receiver’s Service Provider (on behalf of the Business Document Receiver), due to an error which should have been detected by the Business Document Sender’s Service Provider prior to sending (schema or syntax error). The Business Document Sender’s Service Provider must take appropriate action to correct and resend the business document, or follow up with the Business Document Sender to correct invalid data. The Business Document Sender’s Service Provider should also investigate the root cause of their failure to properly validate the document prior to sending, and take appropriate corrective action.

3.1.3. Use Case 2 – Positive response

This use case is a Message Level Response containing no errors, ie a positive response.

Use Case number	2
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	Business Document Sender Message Level Response Receiver Business Document Receiver Message Level Response Sender
Assumptions	The Business Document Receiver has received an electronic business document from the Business Document Sender. The Business Document Receiver has validated the business document from the Business Document Sender. The result of the validation is OK, no fatal errors.
The flow	The Business Document Sender has prepared and sent an electronic business document to the Business Document Receiver. The Business Document Receiver has received the business document. The Business Document Receiver has validated the business document. The Message Level Response Sender sends a Message Level Response back to the Business Document Sender (using the Message Level Response document profile). The Message Level Response Receiver receives and processes the message level response message.
Result	The Message Level Response provises the Business Document Sender a confirmation that the business document was received and validated with no errors by the Business Document Receiver.

Use Case number

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

Business Document Sender
Message Level Response Receiver
Business Document Receiver
Message Level Response Sender

Assumptions

The Business Document Receiver has received an electronic business document from the Business Document Sender.
The Business Document Receiver has validated the business document from the Business Document Sender.
The result of the validation is OK, no fatal errors.

The flow

The Business Document Sender has prepared and sent an electronic business document to the Business Document Receiver.
The Business Document Receiver has received the business document.
The Business Document Receiver has validated the business document.
The Message Level Response Sender sends a Message Level Response back to the Business Document Sender (using the Message Level Response document profile).
The Message Level Response Receiver receives and processes the message level response message.

Result

The Message Level Response provises the Business Document Sender a confirmation that the business document was received and validated with no errors by the Business Document Receiver.

3.1.4. Use Case 3 – Negative response – violation of business rules

This use case is a Message Level Response containing errors due to violation of semantic rules, which are not captured by the syntax validation.

Use Case number	3
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 the semantic data model.
Parties involved	Business Document Sender Message Level Response Receiver Business Document Receiver Message Level Response Sender
Assumptions	The Business Document Receiver has received an electronic business document from the Business Document Sender. The Business Document Receiver has validated the business document from the Business Document Sender. The result of the validation is not OK due to a semantic error.
The flow	The Business Document Sender has prepared and sent an electronic business document to the Business Document Receiver. The Business Document Receiver has received the business document. The Business Document Receiver has validated and rejected the business document. The Message Level Response Sender sends a message level response message back to the Business Document Sender (using the Message Level Response document profile). The Message Level Response Receiver receives and processes the message level response message and takes appropriate action due to the rejection.
Result	The Message Level Response communicated to the Business Document Sender a confirmation that the business document was received and rejected by the Business Document Receiver. The Business Document Sender must take appropriate action to correct and resend the business document.

Use Case number

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 the semantic data model.

Parties involved

Business Document Sender
Message Level Response Receiver
Business Document Receiver
Message Level Response Sender

Assumptions

The Business Document Receiver has received an electronic business document from the Business Document Sender.
The Business Document Receiver has validated the business document from the Business Document Sender.
The result of the validation is not OK due to a semantic error.

The flow

The Business Document Sender has prepared and sent an electronic business document to the Business Document Receiver.
The Business Document Receiver has received the business document.
The Business Document Receiver has validated and rejected the business document.
The Message Level Response Sender sends a message level response message back to the Business Document Sender (using the Message Level Response document profile).
The Message Level Response Receiver receives and processes the message level response message and takes appropriate action due to the rejection.

Result

The Message Level Response communicated to the Business Document Sender a confirmation that the business document was received and rejected by the Business Document Receiver. The Business Document Sender must take appropriate action to correct and resend the business document.

4. OIOUBL 3 Identifiers

OIOUBL 3 has defined how to use identifiers in the documents exchanged across the Nemhandel eDelivery infrastructure (Based on the Peppol identifier policy).

It also introduces principles for any identifiers used in the Nemhandel eDelivery environment. The policies that apply to this OIOUBL 3 BIS at the follows:

4.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 which are applied.

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

4.2. Customization and Profile identifiers

Type Element cbc:CustomizationID Element cbc:ProfileID

Type	Element `cbc:CustomizationID`	Element `cbc:ProfileID`
Message Level Response	`urn:fdc:peppol.eu:poacc:trns:mlr:3@urn:fdc:oioubl.dk:trns:message_level_response:3.0`	`urn:fdc:oioubl.dk:bis:message_level_response:3`
Message Level Response Network	`urn:fdc:peppol.eu:poacc:trns:mlr:3@urn:fdc:oioubl.dk:trns:message_level_response:3.0`	`urn:fdc:oioubl.dk:bis:message_level_response_network:3`

Message Level Response

urn:fdc:peppol.eu:poacc:trns:mlr:3@urn:fdc:oioubl.dk:trns:message_level_response:3.0

urn:fdc:oioubl.dk:bis:message_level_response:3

Message Level Response Network

urn:fdc:peppol.eu:poacc:trns:mlr:3@urn:fdc:oioubl.dk:trns:message_level_response:3.0

urn:fdc:oioubl.dk:bis:message_level_response_network:3

4.3. Namespaces

All document types in OIOUBL BIS Message Level Response are bound to the UBL 2.1. The target namespaces are:

Type Namespace

Type	Namespace
Message Level Response	`urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2`

Message Level Response

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

5. Description of Selected Elements in the Message Level Response

5.1. Document response

The document response is used to indicate the result of business document validation.

To be able to define more correct use of document response codes, two different document profiles are defined as a part of this OIOUBL BIS Message Level Response. See the details in section for OIOUBL 3 identifiers.

Table 1. Valid document response codes in the two different document profiles.
Document response code name	Document response code id	Profile Message Level Response	Profile Message Level Response Network
Rejected	RE	Default	Default - and only allowed value
Message acknowledgement	AB	Allowed	Not allowed
Accepted	AP	Allowed	Not allowed

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

5.1.1. Rejected

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

Example for rejection:

<cac:Response>
    <cbc:ResponseCode>RE</cbc:ResponseCode>
    <cbc:Description>The document was rejected because it failed validation</cbc:Description>
</cac:Response>

5.1.2. Accepted

Example for acceptance:

<cac:Response>
    <cbc:ResponseCode>AP</cbc:ResponseCode>
</cac:Response>

5.1.3. Acknowledgement

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>

5.2. Line response

In case of a negative response (rejection), the cac:LineResponse element is used to specify the errors in the business document. The cbc:LineID element is mandatory in UBL but not relevant since the line responses are listing errors on both header level and line level from the original document and should have the value: NA (“Not Applicable”, must be all uppercase).

Example:

<cac:LineResponse>
    <cac:LineReference>
        <cbc:LineID>NA</cbc:LineID>
    </cac:LineReference>
    <cac:Response>
        <cbc:Description>BR-CO-13: Invoice tax exclusive amount MUST equal the sum of lines plus allowances and charges on header level</cbc:Description>
        <cac:Status>
            <cbc:StatusReasonCode>BV</cbc:StatusReasonCode>
        </cac:Status>
    </cac:Response>
</cac:LineResponse>

5.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 (see the Nemhandel eDelivery AS4 specification for the syntax and data model of the message envelope).

Example for document references:

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

5.4. Party identification

5.4.1. Sender Party

The element cac:SenderParty/cbc:EndpointID MUST contain the party identification of the receiver of the original envelope. If the response is a Message Level Response, this is the original business recipient (corner 4). If the response is a Message Level Response - Network, this is the technical endpoint of the business recipient’s service provider (corner 3).

Example:

<cac:SenderParty>
    <cbc:EndpointID schemeID="0184">98754325</cbc:EndpointID>
</cac:SenderParty>

5.4.2. Receiver Party

The element cac:ReceiverParty/cbc:EndpointID MUST contain the party identification of the sender of the original envelope. If the response is a Message Level Response, this is the EndpointID of the sending Party per the relevant BIS (for invoices this would be AccountingSupplierParty). If the response is a Message Level Response - Network, this is the technical endpoint of the sending party’s service provider, which is found in the message envelope, per the Nemhandel eDelivery specification.

Example:

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

6. OIOUBL License and Statement of Copyright

License & Copyright Statement

7. Links to main site of documentation

OIOUBL 3 Main documentation site