The Business Interoperability Specification, “BIS” from here on after, has been developed by IMDA.

Link to main site of documentation

https://www.peppolguide.sg [Main documentation site]

1. Introduction to OpenPeppol and BIS

This BIS is a result of work within IMDA and key stakeholders.

The purpose of this document is to describe a common format for the order balance message as used by Singapore in the Peppol network, and to facilitate an efficient implementation and increased use of electronic collaboration regarding the ordering and billing process.

2. Principles and prerequisites

This chapter describes the principles and assumptions that underlie the use of SG BIS Order balance.

2.1. Scope

This BIS describes a process comprising a Buyer to issue an electronic order balance used to inform the Seller the current status of an order

The main activities supported by this profile are:

Buyer compiles current information of remaining quantity for an order and creates the order balance.

The Seller can use the order balance to keep track and verify the remaining quantity to deliver.

2.2. Parties and roles

The table below gives the definitions of the parties and roles of the reporting of Order balance process.

Business partners

Description

Customer

The customer is the legal person or organization who is in demand of a product or service. The customer reports the current order balance to the Supplier

Examples of customer roles: buyer

Supplier

The supplier is the legal person or organization who provides a product or service. Examples of supplier roles: seller

Role/actor

Description

Buyer
cac:BuyerCustomerParty

The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services.

Seller
cac:SellerSupplierParty

The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the customer.

The following diagram links the business processes to the roles performed by the Business Partners.

Roles in order process

2.3. Benefit

Based on success with automation of invoicing, there is a growing interest in automation of ordering also.

For the sellers, the order balance gives an up to date view on remaining quantity of an order.

For the procuring organization, the order balance helps to ensure that invoices can be automated and handled with less intervention.

Other potential benefits of using this BIS are, among others:

  • Can be used by procuring organizations as step towards automation of procurement. The flexibility of the specifications allows the buyers to gradually automate and structure ordering, based on a cost/benefit approach.

  • SME can offer their trading partners the option of exchanging standardized documents in a uniform way and thereby move all orders into electronic form.

2.4. Interoperability

This Peppol BIS structure is based on the European Interoperability Framework 2.0 EIF. This Peppol BIS applies the Framework as follows:

Organizational interoperability

  • Organization (Organization/Business):

    • This Peppol BIS supports B2B and B2G.

    • This Peppol BIS supports cross border, regional and domestic ordering in EU and EEA.

    • This Peppol BIS can function as a component in an EDI agreement within a trading community.

    • This Peppol BIS supports linking of business processes within the sending and receiving organization. The process of order balance transmission in electronic form can be linked into internal processes of both sender and receiver, which may differ for various reasons.

Semantic interoperability

  • Semantic: The set of information elements is assumed to be sufficient to support organizational business and processing requirements stated above.

Technical interoperability

  • Technical Interaction (Process and semantic implementation):

    • Binding to OASIS UBL 2.1, see UBL 2.1

    • ISO/IEC 19757-3 Schematron, for automation of document validation, see Schematron

3. Process and typical use cases

The Order balance process includes the sending the Order balances from a Buyer to a Seller.

3.1. Process flow

The Order balance process flow can be described as follows:

  • A Buyer submits an Order balance to the Seller informang of remaining quantity of goods or services

3.2. Business process Diagram

3.2.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 1. BPMN legend

The following diagram shows the choreography of the business process implemented by the BIS.

bpmn order

3.3. Use case 1 – Order balance of partially delivered and billed order

This use case contains an order balance which relates to an order which has been partially completed .

Use Case number 1

Use Case Name

Order balance of current remaining quantity

Use Case Description

  • After an order has been partially delivered and billed, the Buyer compiles the current remaining quantity

  • The order balance informs the Seller of remaining quantity

Parties involved

Buyer
Seller

Assumptions

An order has previously been submitted.
The Seller has partially delivered and billed the ordered items.

The flow

The Buyer creates the Order balance with the remaining quantity and submitt to the Seller.
The Seller receives the order balance.

Result

The seller can use the current information from the Order balance to ensure that expectations of remaining quantity is in line with the Seller owns records

XML example file

See Appendix A for a sample file illustrating Use Case 1 in the download section on the main page.

3.4. Use case 2 – Order balance of fully delivered order

This use case is a continuation of use case 1 (partially delivered order) where the order now is fully delivered.

Use Case number 2

Use Case Name

Order balance of fully delivered quantity

Use Case Description

  • After an order has been fully delivered and billed, the Buyer compiles an order balance with no remaining quantity

  • The order balance informs the Seller that the order is fully delivered and billed.

Parties involved

Buyer
Seller

Assumptions

An order has previously been submitted.
The Seller first made a partially delivered, billed the ordered items and received an order balance with the remaining quantity (see use case 1)
The Seller has then fully delivered the order.

The flow

The Buyer creates the order balance with showing that there is no remaining quantity.
The Seller receives the order balance.

Result

The seller can use the current information from the Order balance verify that it is inline with the Seller owns records

XML example file

See Appendix A for a sample file illustrating Use Case 2 in the download section on the main page.

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 [hh]:[mm]:[ss].

Time shall not 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

String

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="0195">SGUEN200254321Z</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="0195">SGUEN200254321Z</cbc:EndpointID> (1)
1 schemeID attribute is mandatory

6. Description of selected parts of the order message

6.1. Parties

The following parties/roles may be specified in the message:

6.1.1. SellerSupplierParty (Seller)

The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the buyer. The seller is mandatory in the SG BIS Order Balance

Example of seller information
<cac:SellerSupplierParty>
        <cac:Party>
                <cbc:EndpointID schemeID="0195">SGUEN200212345Z</cbc:EndpointID>
                <cac:PartyIdentification>
                        <cbc:ID>VendorID</cbc:ID>
                </cac:PartyIdentification>
                <cac:PartyLegalEntity>
                        <cbc:RegistrationName>Gallery Photo Supplier</cbc:RegistrationName>
                        <cbc:CompanyID>200212345Z</cbc:CompanyID>
                </cac:PartyLegalEntity>
                <cac:Contact>
                        <cbc:Name>Avery Lee</cbc:Name>
                        <cbc:Telephone>4621230</cbc:Telephone>
                        <cbc:ElectronicMail>avery@salescompany.sg</cbc:ElectronicMail>
                </cac:Contact>
        </cac:Party>
</cac:SellerSupplierParty>

6.1.2. BuyerCustomerParty (Buyer)

The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services. The buyer is mandatory in the SG BIS Order Balance

Example of buyer information
<cac:BuyerCustomerParty>
        <cac:Party>
                <cbc:EndpointID schemeID="0195">SGUEN200254321Z</cbc:EndpointID>
                <cac:PartyLegalEntity>
                        <cbc:RegistrationName>IMDA</cbc:RegistrationName>
                        <cbc:CompanyID>200254321Z</cbc:CompanyID>
                </cac:PartyLegalEntity>
                <cac:Contact>
                        <cbc:Name>Bill</cbc:Name>
                        <cbc:Telephone>5121230</cbc:Telephone>
                        <cbc:ElectronicMail>bill@imda.sg</cbc:ElectronicMail>
                </cac:Contact>
        </cac:Party>
</cac:BuyerCustomerParty>

6.2. Product name and description

The Product name shall be sent in tag cac:Item/cbc:Name on line level.

Example in an SG BIS Order balance message:
<cac:Item>
        <cbc:Name>Stapler</cbc:Name>
</cac:Item>

6.3. Quantities and units

Remaining quantity and unit can be stated in the SG BIS Order balance.

The table below shows the quantity and unit in the correct format. To all quantities there must be a valid Unit according to the Code list.

Example of an order balance line with a quantity of 120 litre (cbc:Quantity) and price is given per litre.
<cbc:Quantity unitCode="EA">120</cbc:Quantity>

6.4. Prices

Price sent is related to the articles or services within the order balance.

  • Prices excludes TAX amounts (e.g. VAT, GST or sales tax)

Example of price information in an Order message:
<cac:Price>
        <cbc:PriceAmount currencyID="SGD">50.000</cbc:PriceAmount>
</cac:Price>

6.5. Order Type Code

The following code value is used to specify that the message is of type Order balance.

Table 4. Code list
Code Name Description UBL Message type

348

Order status report

A message reporting the status of previously sent order.

Order
Example of order balance type code:
<cbc:OrderTypeCode>348</cbc:OrderTypeCode>

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

Order balance (tob)

urn:fdc:imda.gov.sg:trns:order_balance:1

urn:fdc:imda.gov.sg:bis:order_balance:1

7.3. Namespaces

  • The target namespace for the UBL 2.1 Order is:
    urn:oasis:names:specification:ubl:schema:xsd:Order-2