This document describes the data formats used when trading partners exchange Punch Out electronically (Norwegian: Elektronisk Handelsformat; EHF). It is prepared as part of the initiative taken by the Norwegian “Agency of Public Management and eGovernment” (Difi) within the standardization of electronic trade processes.
|
Reporting bugs
Please use Github Issues to report bugs and lack of content when discovered.
Users currently not registered on Github may create an account for free.
|
1. Introduction
1.1. Background and Objective
The government white paper labeled “St.Meld. nr. 36 (2008-2009) Det gode innkjøp” (The good procurement), states among other things:
It’s the Government’s opinion that increased use of electronic solutions is important to improve and increase the efficiency of public procurement. The use of electronic solutions may reduce time spent on public procurement, increase the competition and arrange for purchases to be more transparent and easier to re-examine. By spending less time and money on procurement, resources will be available for both modernizing the public sector and more welfare. The goal for introducing electronic solutions is to contribute to a better, simpler and more secure procurement.
The previous «Ministry of Government Administration, Reform and Church Affairs» (FAD) considered use of open standards as a vital means to build a well-functioning public administration, with good internal collaboration and a high level of service for both inhabitants and businesses.
An open standard is characterized by its reputation and will be maintained by a non-commercial organization, and the continuing development is based on decision processes open to every interested party. The standard is published and the documentation is available, either free of charge or for a small, insignificant fee. Anyone must be allowed to copy, distribute and use the standard free of charge or for a small, insignificant fee. The intellectual rights related to the standard (e.g. patents) are irrevocably available, without any royalties. There is no reservation regarding re-use of the standard.
The purpose of this document is to describe a common format for invoice messages in the Norwegian market, and to facilitate an efficient implementation and increased use of electronic collaboration regarding the invoicing process based on this format.
1.2. Audience
The audience for this document is organizations wishing to be EHF enabled for exchanging electronic orders, 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
1.3. Scope
The intention of this EHF is the synchronization of the Punch Out catalogue information between the selling and the buying side in a business relationship, where the selling side is the source of the information and the buying side the receiver. In this EHF, the selling side can be any Economic Operator and the buying side any Contracting Authority. The intended scope for this EHF includes business-to-government (B2G) and business-to-business (B2B) relationships. Although this EHF is a basis for an EDI agreement between two parties, it does not address all business level details of such an agreement. It is the provider’s responsibility that data contained in the shopping cart transaction is valid from a technical, as well as a business point of view.
The transaction, specified in this EHF are intended to be exchanged between the procurement systems of contracting authorities and systems for shopping cart transactions of economic operators. This document recognizes that when using Punch Out it is common to use synchronous message transfer methods but technical specification of that including the login- and logout transactions are outside scope of this EHF.
In this EHF, synchronization of shopping cart transaction information covers the submission of new information, no update or deletion of information is covered by this EHF. In case of an update/change, the buyer will simply generate a new product- or service list by repeating the process.
The information sourced with the EHF Punch Out may be used in following business process, such as ordering. The order transaction is outside scope of this EHF, we then refer to EHF Order Only or EHF Ordering.
2. Changelog
2.1. Consequences of Implementing this version
Version 1.0.3 is a revision of EHF Punch Out 1.0, and this version is backwards compatible to EHF Punch Out 1.0. This means that any instance documents valid towards EHF Punch Out 1.0 is also valid in version 1.0.3. Please note that valid here reflects the validity against the implementation guide of EHF Punch Out 1.0, as this is the normative reference.
2.2. Version 1.x
Version 1.0.2 (2019-02-27)
| Issue | Description | Type |
|---|---|---|
- |
Fixing syntax, resulting in updated basic validation rules. |
Syntax |
| Validation rules expected to be updated to trigger error in next release: All basic validation rules (EHF-TXX-BXXXXXX). |
Version 1.0.1 (2018-11-15)
| Issue | Description | Type |
|---|---|---|
- |
Moving example files into a example file archive. Appendix is updated with the new link. |
Guide |
- |
Replacing listing of validation rules with links to all relevant validation rules. |
Guide |
- |
Adding "basic" validation rules automatically created from syntax. Rules are identified as 'EHF-T77-BXXXXX' where 'XXXXX' is a running number. |
Validator |
| Validation rules expected to be updated to trigger error in next release: All basic validation rules (EHF-TXX-BXXXXXX). |
3. Electronic Commerce Format (EHF)
3.1. About EHF
EHF is an anagram of the Norwegian expression «Elektronisk handelsformat» (Electronic Commerce Format).
EHF is based on the work performed by CEN BII. This is further adjusted to comply with the Norwegian accounting regulations and current practices for the different business processes in the Norwegian market. Difi pursues the goal to cover the full trading process using EHF documents, both before and after awarding (signing of a contract).
Documents, from the tender catalogue to the credit note will be gathered under the EHF umbrella. During 2013 Difi will prepare for the use of EHF formats in what is known as the post award process, i.e. the part of the business process that starts when a supplier and a customer have signed a contract.
By using the EHF documents the collaboration between the supplier and the customer will be predictable. Elements from the tender Catalogue will be re-used in the Order, and elements from the Order will be re-used in the Invoice. This leads to a holistic use of all the documents under the EHF umbrella.
Difi has chosen to use CEN BII as a base for the EHF formats and the Universal Business Language (UBL) as a foundation for the implemented syntax. Both EHF and UBL are open standards and as such not liable to any licensing fees or royalties.
EHF is managed and maintained by Difi.
3.2. Information Consistency
The different EHF formats mentioned above contain a number of common information elements (supplier, customer, item etc.). It is important to preserve consistency in those common information elements, and that means that elements with identical content are declared in the same way and as far as possible given the same element tag name.
EHF invoicing formats will for instance re-use elements from the Catalogue and Order to ensure consistency between the messages and to make sure that the information from the business transactions are reflected in the invoicing documents. This makes it possible to implement an efficient and automated control of the invoice and the originating transactions.
3.3. Empty Elements
The use of empty elements is prohibited in UBL, which is the base for EHF. The reason for this, is that empty elements may be interpreted to have a certain meaning, it could mean that the information was not available at the time of sending as an example. In addition, numeric- and date elements have requirements that would generate validation errors if they were empty.
| The use of empty elements is, for the above mentioned reasons, not allowed in EHF. |
3.4. Use of Collaboration Agreements
The combination of the ELMA registration and the implementation guides referred to in that context eliminates the need for any formal collaboration agreement between the sender and the receiver. The ELMA registration verifies that an actor has declared the ability and the commitment to receive business documents composed according to the specific implementation guide, and any party is free to send the business document to this actor.
Exchanging Catalogue and Order requires no registration in ELMA, and actors are advised to include the use of electronic messages in the purchase contract or to supply an collaboration agreement as an attachment, in order to link the electronic collaboration with the mercantile regulations and thus achieve a regularly revision of the electronic process.
3.5. Versioning
Difi claims the right to exchange the current format with a new one as and when needed. If so, Difi will inform the public via the web site and their registered users via e-mail.
Difi manages the formats in this way:
- Main Version
-
A new main version will be announced at least 5 months prior to release. When a main version is released, there will be at least a 12 months implementation period before the new version is made mandatory.
Difi intends to relate every main version to the regulations concerning IT standards in the public sector.
- Sub Version
-
A new sub version will be announced at least 3 months prior to release and is made mandatory 5 months after release.
All sub versions must be backwards compatible. 2 months after the new sub version has become mandatory, the support (validation service and implementation guide) is ceased for preceding versions.
- Revision
-
A revision is in principle a result of bug fixing the latest sub version, and will be announced at release time and should be implemented without further delay.
4. Principles and prerequisites
This chapter describes the principles and assumptions that underlie the use of EHF Punch out. It is based on the CENBII 18 Punch out.
This document identifies, explains and justifies the business requirements for the Punch Out-process. It provides syntax bindings to OASIS UBL 2.1. It also includes a syntax implementation guide.
The EHF Punch Out describes a process where the buyer accesses the seller’s web-based catalogue, and adds and/or configures items (such as a PC) to a product or service list. The product- or service lists are sent to the buyer´s procurement system, and can later be used as a basis for an order or an item comparison in the buyer’s catalogue tool. The order is prepared and sent from the buyers´s procurement system, not from the seller´s website.
4.1. Parties and roles
The table below gives the definitions of the parties and roles of the punch out process.
| Business partners | Description |
|---|---|
Customer |
The customer is the legal person or organization who is in demand of a product or service. Examples of customer roles: buyer, consignee/delivery part, debtor, contracting body. |
Supplier |
The supplier is the legal person or organization who provides a product or service. Examples of supplier roles: seller, consignor, creditor, economic operator. |
| Role/actor | Description |
|---|---|
Buyer |
The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services. In the Punch Out the buyer accesses the punch out system, selects the items and quantities he wants and completes the action by punching-out |
Seller |
The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the customer. In the Punch Out the seller provides the punch out system into which the buyer logs on. The seller is responsible for providing up-to-date information on items and other relevant information in the punch out system. |
The following diagram links the business processes to the roles performed by the Business Partners.
4.2. Benefits
Based on success with automation of invoicing there is a growing interest in automation of ordering. This approach has two dimensions: Support further automation of invoicing and using structured catalogues as basis for ordering. The Punch Out process is a sourcing process that preceeds and supports the ordering. It enables the buyer to retrieve information from the seller and use that information to place an order that can then be used in an order-to-invoice matching process. The Punch Out is a specific type of a sourcing process that supports the growing use of purchasing web portals offered by sellers. Implementing this EHF is an important step for many companies and government agencies towards full procurement automation.
For the sellers, the buyers automated purchasing process can be integrated into their web portals to provide up to date information on items, quantities and prices.
For the procuring agency, up to date item information and prices can be retrieved when required and used for comparison and selection and input to ordering.
Other potential benefits of using this EHF are, among others:
-
Can be used by procuring agencies 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 procurement sourcing information into electronic form.
-
Large companies can implement this EHF as standardized documents for general operations.
-
Can be used as basis for restructuring of in-house processes of sourcing and ordering.
-
Significant saving can be realized by the procuring agency by automating and streamlining in-house processing.
-
Significant saving can be realized by the sellers by automating and streamlining in-house processing. Linking to picking and invoicing can be improved significantly based on increased order quality, restructuring of invoice dispute resolution and shorter payment cycles.
-
For the procuring agency, sourcing and ordering can be structured.
4.3. Process flow
The Punch Out process flow can be described as follows:
The Buyer is “re-directed” from his procurement system to the seller’s Punch Out enabled website. The buyer searches the website.
At the website the buyer search and select articles which are added to a shopping cart. When the buyer checks out of the website, a transaction (Punch Out) with item information of the selected item is sent to the buyer’s procurement system. = Business process diagram
5. Use cases
The Punch Out includes the sending of Shopping cart information from a Seller to a Buyer.
5.1. Use case 1 – Punch out used for ordering
This use case describes when a buyer uses the Punch out to retrieve item information that he can use in his procurement systems for ordering.
| Use Case number | 1 |
|---|---|
Use Case Name |
Punch Out used for ordering |
Use Case Description |
The customer/buyer is working in the in-house procurement system, selects a seller that has a Punch Out Catalogue, and clicks to see that seller’s products. The procurement system then automatically sends a login request to the seller’s website, and the procurement system opens the remote website. |
Parties involved |
Buyer |
Assumptions |
The Seller has a website that allows the customer/buyer to automatically log into from his purchasing system. The seller’s website shows what items are contracted. |
The flow |
The buyer searches the website for items needed, and chooses to add some to the shopping cart. It is clearly visible which items are contracted. After selecting all required items, the buyer then chooses to check out. A transaction with information of the selected items is sent to the buyer’s procurement system, all information being real time, resulting in correct and up to date information on price, availability and lead-time. Seller’s website logs out the buyer, and the buyer is redirected back to the procurement system. The buyer then follows the normal order approval procedure, and places an order based on the items in the cart. |
Result |
The buyer has received information about the items that he selected into his cart in a message that is structured like a catalogue that can be imported into his purchasing system and used as basis for an order. |
XML example file |
See Use Case 1. |
5.2. Use case 2 – User configures product/services
This use case describes a process where a buyer uses a punch out system to configure a product by selecting several components and features from a catalogue.
| Use Case number | 2 |
|---|---|
Use Case Name |
User configures product/services |
Use Case Description |
The buyer uses the functionality in the sellers website to configure a product or a service. |
Parties involved |
Buyer |
Assumptions |
The Seller has a website that allows the customer/buyer to automatically log into from his purchasing system. |
The flow |
The customer/buyer is working in their procurement system, and is searching for a seller of PC’s. The buyer selects a seller to see that seller’s products. The selected seller’s catalogue is Punch Out enabled. The procurement system then automatically sends a login request to the seller’s website, and the procurement system opens the website. The buyer then use the functionality in the seller’s website to select and configure a PC. When the buyer checks out of the website the item information of the configured item is automatically sent to the buyer’s procurement system. The procurement system automatically logout of the seller’s website, and the buyer is redirected back to the procurement system. From the procurement system, the buyer follows the normal ordering procedures when ordering the PC, using the identifier of the configured item as a reference for the seller. |
Result |
The buyer has retrieved information about a configured item. |
XML example file |
See Use Case 2. |
6. Description of selected parts of the shopping cart message
A shopping cart message must at minimum contain the following information:
-
The cart identifier.
-
The date and time when the shopping cart message was created.
-
Identifier of the business process that it belongs to.
-
Identifier of the message specification that applies to the shopping cart message.
-
The name of the party that provides the cart message, i.e. the seller.
-
The name of the party that receives the cart message, i.e. the buyer.
-
One or more message lines each of which contains at minimum the following:
-
A line identifier.
-
The line quantity.
-
The name of the item.
-
The price of the item.
-
The VAT category and percentage rate for the item.
-
In addition to the mandatory information the shopping cart may optionally contain additional information details. The following sections detail show different parts of the shopping cart message are used.
6.1. The Shopping Cart
6.1.1. Identification and dates
In the beginning of the shopping cart message there is information that identifies the shopping cart itself which allows for managing it in a processing flow as well as referencing it from other documents and processes. This is given by an identifier as well as the date and time when the shopping cart message is created. This would normally be the time when the buyer punches out from the sellers web store.
The identifier is created by the seller and may be of any format. The date and time must not be in the future.
<cbc:ID>1387</cbc:ID>
<cbc:IssueDate>2017-09-15</cbc:IssueDate>
<cbc:IssueTime>09:00:00</cbc:IssueTime>6.1.2. Sellers conditions
The shopping cart allows the seller to set conditions on how the buyer may order.
The seller may set a limit of the validity time for the information in the shopping cart. A shopping cart is valid from the time it is issued until the time stated in the validity period. That time may not be before the time when the cart is issued. If only validity end date is given the cart is valid until end of that day in the sellers time zone. The seller may also set validity time for individual lines. Validity end time is given as follows.
<cac:ValidityPeriod>
<cbc:EndDate>2017-12-31</cbc:EndDate>
<cbc:EndTime>18:00:00</cbc:EndTime>
</cac:ValidityPeriod>The seller may set the condition that the offer made in the shopping cart is only valid if all item in the cart are ordered. That is the buyer may not select only certain items or change the quantities of the items listed in the cart. This is given by the complete cart indicator. If the value of the indicator is "true" the buyer must either order all or none of the cart. The default value of the indicator is "false" meaning that if the element is not included in the message the buyer may order part of the cart. Following is an example.
<cbc:ActionCode>true</cbc:ActionCode>The seller may reference a contract that governs the offer made in the shopping cart. The terms and conditions of a referenced contract supersedes the information given in individual shopping carts. Following is an example:
<cac:ReferencedContract>
<cbc:ID>CRT1387</cbc:ID>
</cac:ReferencedContract>6.1.3. Parties
The following parties/roles may be specified in the message:
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 given as the Provider Party in UBL and is mandatory in the EHF Shopping Cart message. The seller must be identified with a name but may additionally be identified with an identifier.
The end point identifier is the EHF network address and the schemeID identifies the governance of the identifier used, in line with EHF specifications on the use of identifiers.
<cac:ProviderParty>
<cbc:EndpointID schemeID="NO:ORGNR">965678996</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="NO:ORGNR">965678996</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Seller AS</cbc:Name>
</cac:PartyName>
</cac:ProviderParty>Buyer
The buyer is the legal person or organization acting on behalf of the customer who buys or purchases the goods or services. The buyer is given as the ReceiverParty in UBL and is mandatory in the EHF Shopping cart message.
The endpoint identifier is the EHF network address and the schemeID identifies the governance of the identifier used, in line with EHF specifications on the use of identifiers. The buyer must be identified with his name but may additionally be identified with the sellers customer identifier and/or a registered identifier.
<cac:ReceiverParty>
<cbc:EndpointID schemeID="NO:ORGNR">984661185</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="NO:ORGNR">984661185</cbc:ID>
</cac:PartyIdentification>
<cac:PartyIdentification>
<cbc:ID schemeID="ZZZ">SELLERASSIGNEDID</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Buyer AS</cbc:Name>
</cac:PartyName>
<cac:Contact>
<cbc:ID>Buyers ref no</cbc:ID>
</cac:Contact>
</cac:ReceiverParty>6.2. The shopping cart line
Each shopping cart line must have an id to support processing and referencing of individual lines. The ID is created by the seller and may be of any structure but a line id must be unique within the shopping cart message. Example of a series of line identifiers is 1, 2, 3, 4, 5 … or any other structure. The lines do not need to be ordered in the message. An example of a line identifier is below:
<cac:CatalogueLine>
<cbc:ID>1</cbc:ID>6.2.1. Configured products
The seller may define a configured product in a shopping cart and then list the individual items that are part of the configured product in a structured way as described in this clause. The seller may also describe a configured product in an unstructured way as item description. The items that are part of a configured product reference the Sellers Item number for the configured product that it is part of. No reference is made from the configured product to the item.
A shopping cart line that is part of a configured product can not be ordered individually. If configured products are part of a shopping cart that has complete cart indicator as true then a full ordering of the cart means purchase of its configured products only but not additionally the individual items that are part of them. These items can be offered individually with additional lines in the cart where the item is not stated as "part of" the configured product. If information for individual items conflict with the information given for the configured items the configured item supersedes. An example of an item that is part of a configured product.
<cac:AdditionalItemProperty>
<cbc:Name>PartOf</cbc:Name>
<cbc:Value>PC01</cbc:Value>
</cac:AdditionalItemProperty>Example: Item PC01 is configured by 1 of item MNTR01 and 2 of item INST01. The order will be ONLY on Item PC01.
Catalogue line 1 – the configured product
<cac:CatalogueLine>
<cbc:ID>1</cbc:ID>
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="NOK">1000.00</cbc:PriceAmount>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="C62">1</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>
<cac:Item>
<cac:SellersItemIdentification>
<cbc:ID>PC01</cbc:ID>
</cac:SellersItemIdentification>
</cac:Item>
</cac:CatalogueLine>Catalogue line 2 – an item that is part of the configured product.
<cac:CatalogueLine>
<cbc:ID>2</cbc:ID>
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="NOK">11000.00</cbc:PriceAmount>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="C62">1</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>
<cac:Item>
<cac:SellersItemIdentification>
<cbc:ID>MNTR01</cbc:ID>
</cac:SellersItemIdentification>
<cac:AdditionalItemProperty>
<cbc:Name>PartOf</cbc:Name>
<cbc:Value>PC01</cbc:Value>
</cac:AdditionalItemProperty>
</cac:Item>
</cac:CatalogueLine>Catalogue line 3 – another item, two of which are part of the configured product.
<cac:CatalogueLine>
<cbc:ID>3</cbc:ID>
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="NOK">200.00</cbc:PriceAmount>
</cac:Price>
<cac:DeliveryUnit>
<cbc:BatchQuantity unitCode="HUR">2</cbc:BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>
<cac:Item>
<cac:SellersItemIdentification>
<cbc:ID>INST01</cbc:ID>
</cac:SellersItemIdentification>
<cac:AdditionalItemProperty>
<cbc:Name>PartOf</cbc:Name>
<cbc:Value>PC01</cbc:Value>
</cac:AdditionalItemProperty>
</cac:Item>
</cac:CatalogueLine>Note that the sum of the price multiplied by quantity of the items contained in the configured item does not have to equal the price of the configured product. The price of the contained items may show the pr. unit price but the configured price may include a price reduction.
6.2.2. Availability dates and lead time
A shopping cart line may state the item availability date which is first day before the end of which the particular item can and will be shipped from the seller. If availability date is before the cart issue date then the item is immediately available. The availability of all items in the cart ends when the validity period of the cart ends. Availability date for an item is given as follows.
<cac:LineValidityPeriod>
<cbc:StartDate>2017-11-15</cbc:StartDate>
</cac:LineValidityPeriod>A shopping cart line may state the lead time for the item. This is the maximum number of working days that may pass from the day the seller receives an order until the day the item is shipped from the seller. The seller may ship earlier. A lead day of one (1) means that an item will be shipped no later than the end of next working day accoding to the sellers regional calendar. The delivery lead time is given as follows:
<cbc:LeadTimeMeasure unitCode="DAY">10</cbc:LeadTimeMeasure>When an availability start date is earlier than the end of the lead time the seller may ship at or before the end of the lead time.
6.2.3. Contract reference
An individual line may reference a contract. Different lines may reference different contracts. If a contract is referenced on the cart level that contract applies to all items in the shopping cart and is only superseded by the line reference where there is a conflict. As example, if a cart level contract reference give payment terms and the line level contract only states delivery conditions for the item then the payment terms apply as well. An example of line level contract reference is as follows. "Contracted item indicator", should be used when shopping from sellers webshop under framework agreements.
<cbc:ContractSubdivision>CRT1387</cbc:ContractSubdivision>6.2.4. Item information
Product identification
Which identifier to use depends on what is known at the time of ordering or what is commonly used in the relevant business sector.
Each cart line MUST have an item name and an identifier. Product identification must be done using one or both of the identifiers described below:
-
Sellers ID
-
Standard ID, e.g. the GS1 Global Trade Item Number (GTIN) used by the seller [GS1]
Manufacturers item identification can not be used alone to identify a product. The Product name must be sent in tag Item/Name on line level.
Example of an EHF Shopping Cart item using both Sellers ID, Manufacturers ID and Standard ID (GTIN):
<cac:SellersItemIdentification>
<cbc:ID>PC01</cbc:ID>
</cac:SellersItemIdentification>
<cac:ManufacturersItemIdentification>
<cbc:ID>PC01349087993</cbc:ID>
</cac:ManufacturersItemIdentification>
<cac:StandardItemIdentification>
<cbc:ID schemeID="GTIN">1234567890123</cbc:ID>
</cac:StandardItemIdentification>The name of the manufacturing party may also be given as follows:
<cac:ManufacturerParty>
<cac:PartyName>
<cbc:Name>The PC Manufacturing Party</cbc:Name>
</cac:PartyName>
</cac:ManufacturerParty>Item name and description
Description of a product can be sent in Item/Description.
The Product name is sent in the shopping cart from buyer to seller. Example in an EHF Shopping Cart message:
The Name is preferably short so that it is suitable for use in a order or invoice line or as a heading. A description allows for longer text that describes the item in detail.
<cbc:Description>One Personal Computer package with a monitor and setup service</cbc:Description>
<cbc:Name>PC computer package</cbc:Name>Item properties
A shopping cart line may state if the item described in the line is a service by stating the item property ServiceIndicator as true. The line may also indentify that the item is not a service with the value false. There is no default value so if the ServiceIndicator is not given the item may be either a service or not. An item that is a service is identified as follows:
<cac:AdditionalItemProperty>
<cbc:Name>ServiceIndicator</cbc:Name>
<cbc:Value>true</cbc:Value>
</cac:AdditionalItemProperty>A shopping cart line may give a list of various attibutes of an item such as size, color and so on for an item. For each property the property name and value must be given. Additionally the seller may give a property classification code to support automation in comparison of attribute and if the attribute value can be quantified it may be restated with the Unit of measure as an attribute. As example an items property may be that it has 16 GB of RAM memory.
<cac:AdditionalItemProperty>
<cbc:Name>RAM memory</cbc:Name>
<cbc:NameCode>Item property classification code</cbc:NameCode>
<cbc:Value>16 GB</cbc:Value>
<cbc:ValueQuantity unitCode="AD">16000000</cbc:ValueQuantity>
</cac:AdditionalItemProperty>Item classification and labelling
A shopping cart line may give information about the items
<cac:CommodityClassification>
<cbc:ItemClassificationCode listID="UNSPSC">20101601</cbc:ItemClassificationCode>
</cac:CommodityClassification>A shopping cart line may give information about labels and certifications that apply to the item. Examples of such are environmental, health, social, quality, cultural and so fort. For each label the name of the label must be given and the certificate of the label as well. If a label has no levels it is recommended to set the type as active. Due to UBL syntax requirements the tags CertificateTypeCode and IssuerParty must also be included when the certificate class is used. These elements are not required by this EHF but in order to comply with the syntax requirement it is recommended to fill in the elements with the word "NA". As example
<cac:Certificate>
<cbc:ID>EU Ecolabel</cbc:ID>
<cbc:CertificateTypeCode>NA</cbc:CertificateTypeCode>
<cbc:CertificateType>active</cbc:CertificateType>
<cac:IssuerParty>
<cac:PartyName>
<cbc:Name>NA</cbc:Name>
</cac:PartyName>
</cac:IssuerParty>
</cac:Certificate>Tax information
For correctly handling taxes for the item the line must state the items VAT category and percentage rate as follows where the standard rate of VAT is 25 percent:
<cac:ClassifiedTaxCategory>
<cbc:ID schemeID="UNCL5305">S</cbc:ID>
<cbc:Percent>25</cbc:Percent>
<cac:TaxScheme>
<cbc:ID>VAT</cbc:ID>
</cac:TaxScheme>
</cac:ClassifiedTaxCategory>Additionally the item country of origin may be given as follows:
<cac:OriginCountry>
<cbc:IdentificationCode listID="ISO3166-1:Alpha2">CH</cbc:IdentificationCode>
</cac:OriginCountry>Prices and quantities
Each line in the Shopping Cart must show the number of items that have been selected by the buyer. For each item there must be a price. The price must be given for the same units as the quantity but the number of units that the price is based on may be different than the quantity.
As example. A buyer may select 360 pieces of an item where the price is €24 for each dozen (12 pieces). In this case the item unit is pieces, and the price for each piece is €24/12 or €2 for each item. Base quantity is optional, with default value 1; when some other base quantity applies it must be stated.
In the shopping cart message this information would be given as follows:
<cac:RequiredItemLocationQuantity>
<cac:Price>
<PriceAmount currencyID="EUR">24.00</PriceAmount>
<BaseQuantity unitCode="C62" >12</BaseQuantity>
</cac:Price>
<cac:DeliveryUnit>
<BatchQuantity unitCode="C62">360</BatchQuantity>
</cac:DeliveryUnit>
</cac:RequiredItemLocationQuantity>6.2.5. Attached Item Specifications
Non-XML documents can be sent as attachments to the EHF Shopping Cart to further specify the item. This could be pictures, drawings or timesheets or other documents relevant for the order. The attachment can either be sent as a binary object encoded in Base64 embedded in the message or as a URI to an external address as a link.
One of these attachments can be identified specifically as being the main image for the item. Identifying it specifically allows automated retrieval of the image into the image location in the receiving system.
It is recommended to send attachments as embedded, binary objects and not as external references.
Example of attachment as an embedded, binary object in an EHF Shopping Cart.
<cac:ItemSpecificationDocumentReference>
<cbc:ID>PC01specs</cbc:ID>
<cbc:DocumentType>Picture of the computer</cbc:DocumentType>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf">UjNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:ItemSpecificationDocumentReference>When sending an object that is the main image for the item the following example applies. The DocumentTypeCode MAINIMAGE identifies that this is the main image for the item.
<cac:ItemSpecificationDocumentReference>
<cbc:ID>PC01image</cbc:ID>
<cbc:DocumentTypeCode>MAINIMAGE</cbc:DocumentTypeCode>
<cbc:DocumentType>Picture of the computer</cbc:DocumentType>
<cac:Attachment>
<cbc:EmbeddedDocumentBinaryObject mimeCode="image/jpeg">UjNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
</cac:Attachment>
</cac:ItemSpecificationDocumentReference>7. Code lists
7.1. Code lists for coded elements
7.1.2. Mime code of attached document
Qualifier |
None |
|---|---|
Document location |
|
Source codelist |
Subset of IANA. |
Structured content |
application/xml |
|---|---|
Documents |
application/pdf |
Images |
image/png |
image/jpeg |
|
image/tiff |
|
image/gif |
7.1.3. Country code
Qualifier |
|
|---|---|
Document location |
|
Source codelist |
7.1.5. Item VAT category code
Qualifier |
|
|---|---|
Document location |
|
Source codelist |
Subset of UN/CEFACT code list 5305 |
| Code | Description |
|---|---|
AE |
Vat Reverse Charge |
E |
Exempt from Tax |
S |
Standard rate |
Z |
Zero rated goods |
H |
Higher rate |
AA |
Lower rate |
7.1.6. Commodity code
| Qualifier | None |
|---|---|
Document location |
|
Source codelist |
COMMODITY SCHEME ID – CENBII |
| Code | Description |
|---|---|
CV |
Customs Article Number |
GN |
National Product Group Code |
HS |
Harmonised System |
CPV |
Common Procurement Vocabulary |
UNSPSC |
|
eCLASS |
eCLASS |
GPC |
GS1 Global Product Classification |
7.2. Codelists for identifier schemes
Table of the code lists used to constrain the values of schemeID for identifiers in the Punch Out transaction:
| Business Term | Allowed SchemeID | Applicable Xpath | Note |
|---|---|---|---|
Party Identifier |
cbc:EndpointID/@schemeID |
Mandatory |
|
Business process type identifier |
See Profile ID |
cbc:ProfileID |
Mandatory |
Specification identification |
See Customization ID |
cbc:CustomizationID |
Mandatory |
8. Message transport and identifiers
EHF has defined a “Policy for Using Identifiers” 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 EHF environment. The policies that apply to this EHF are the following:
8.1. Party Identifiers
The “schemeID” attribute must be populated in all instances of the “ID” element when used within a “PartyIdentification”-container and in all instances of the “EndpointID” element when used within a “Party”-container.
<cac:PartyIdentification>
<cbc:ID schemeID="NO:ORGNR">965678996</cbc:ID>
</cac:PartyIdentification>8.2. Version ID
This EHF is using the UBL 2.1 syntax UBL_Catalogue. The namespace of the XML-message does only communicate the major version number. Since it is important for the receiver to also know what minor version of the syntax that is used, the element UBLVersionID must be stated with the value 2.1:
<cbc:UBLVersionID>2.1</cbc:UBLVersionID>8.3. Profile ID
The ProfileID identifies the process that the business document is part of. EHF uses the identification system according to BII:
The following process identifier is used for Punch Out:
ProfileID: urn:www.cenbii.eu:profile:bii18:ver1.0
<cbc:ProfileID>urn:www.cenbii.eu:profile:bii18:ver1.0</cbc:ProfileID>8.4. Customization ID
The EHF Customization ID identifies the specification of content and rules that apply to the transaction. This EHF has required some minor additions and changes to the CEN BII transaction. Following the CENBII methodology any extension must be communicated by adding an extension ID onto the Customization ID CENBII. The full syntax is:
<transactionId>:(restrictive|extended|partly):<extensionId>[(restrictive|extended|partly):<extensionId>]Where:
-
CENBII Transaction ID is:
urn:www.cenbii.eu:transaction:biitrns077:ver2.0 -
Peppol extension ID is:
urn:www.peppol.eu:bis:peppol18a:ver1.0 -
EHF extension ID is:
urn:fdc:difi.no:2017:ehf:spec:1.0
By combining these according to the identifier syntax the CustomizationID to use in EHF is:
urn:www.cenbii.eu:transaction:biitrns077:ver2.0:extended:www.peppol.eu:bis:peppol18a:ver1.0:extends:urn:fdc:difi.no:2017:ehf:spec:1.0<cbc:CustomizationID>urn:www.cenbii.eu:transaction:biitrns077:ver2.0:extended:www.peppol.eu:bis:peppol18a:ver1.0:extended:urn:fdc:difi.no:2017:ehf:spec:1.0</cbc:CustomizationID>For implementers: Please note that CustomizationID element in the document instance MUST correspond to the Customization ID of the SMP Document Identifier.
8.5. Namespaces
The shopping cart datamodel is in this Punch Out bound to the UBL version 2.1 of the Catalogue document type UBL_Catalogue. The target namespace for the UBL-Catalogue-2.1 is:
urn:oasis:names:specification:ubl:schema:xsd:Catalogue-28.6. Message transport
The transactions defined in this EHF need to be transferred from the sending party to the receiving party through an agreed transport network and protocol. The EHF is specified independent of a transport network but it is designed with the requirement of the PEPPOL network in mind and does not specifically support other transport network that may be used.
8.6.1. The PEPPOL network
This EHF is based on PEPPOL transport network that is a four corner transport network that allows senders end receivers to exchange message from one service provider to another by using a single identifier for the parties.
Details about the PEPPOL network can be found at PEPPOL
The combination of the ELMA registration and the implementation guides referred to in that context eliminates the need for any formal collaboration agreement between the sender and the receiver. The ELMA registration verifies that an actor has declared the ability and the commitment to receive business documents composed according to the specific implementation guide, and any party is free to send the business document to this actor.
8.6.2. Synchronous message transfer
It is recognized that the use of Punch Out often requires synchronous methods for retrieving that data directly from the sellers shopping cart into the buyers purchasing system. Several methods are available including the following:
-
Direct database connections with HTTP using database interface specifications.
-
File download using Wget, HTTP, FTP or similar technology.
The following clauses only briefly introduce these transfer mechanism. Analysis of what is the most suitable methods and technical specification are not in scope for this EHF and are not provided by Difi.
8.6.3. Direct HTTP database connections
Direct database connection using HTTP are common when retrieving shopping carts. Most commonly these methods retrieve the data directly from the catalogue in structured format using input names as field identifiers. In order to read the data correctly into the buyer’s database its structure must be clearly defined.
This EHF provides a detailed structure of the shopping cart data, using UBL XML and detailed semantic specifications and rules. Such an XML message can be retrieved as payload with an HTTP connection. Once that XML file has been retrieved and saved it can be processes in the same way as an XML file that has been delivered, e.g., through the PEPPOL network.
A profile for such a message transfer is specified in the document "PEPPOL synchronous message transfer protocol" provided by OpenPEPPOL and may be used to transfer Punch Out messages.
8.6.4. Internet file transfer
Since the data of the shopping cart generated by using this Punch Out is captured into a single structured XML file, it lends itself to normal file transfer over the Internet. Such a file transfer can be done with several methods including.
-
File Transfer Protocol (FTP).
-
Wget over FTP or HTTP.
9. Validation
To optimize the flexibility in the validation process, each EHF document is validated in different stages with shifting focus in every stage. The pyramid below illustrates the different stages.
9.1. Validation Principles
Stages in the validation process:
-
Validation of syntax against UBL 2.1 Schema, for example:
-
Tag names and attributes must be correctly written and follow the UBL 2.1 sequence
-
All UBL 2.1 mandatory tag names must be present.
-
The element’s contents must be according to the element’s type definition.
-
-
Validation against CEN BII Core to verify that the message is according to international requirements, like:
-
Valid codes for currencies, countries, tax etc.
-
Mandatory tag names according to CEN BII Core.
-
Logical correlations between information element, i.e. that start date is at least lower than end date, sub totals must be totaled, multiplications give the correct result etc.
-
-
Validation against PEPPOL (EU) rules and regulations
-
Validation against EHF Common rules containing rules common to all EHF document types.
-
Validation against EHF rules and Norwegian legislation, like:
-
Organisation number must be specified for the seller/supplier.
-
«Your ref» must be specified.
-
Addresses, postal zone number and post office/city must be specified for the buyer/customer.
-
9.2. Dynamic Validation
The combination of ProfileID and CustomizationID in an XML document defines the validation rules applied to the document.
CustomizationID may be extended with more elements for specific trade or business validation rules.
9.5. Validation Service
Difi’s Validator is an application program used to validate EHF XML-files.
Further information can be found here: https://vefa.difi.no/ehf/knowledge-base/validation/
10. Appendix
Appendix A: Structure Table
Attached is structure tables providing a structured overview of the document types.
Appendix C: Example files
Example files are provided to help implementers. Example files for this implementation guideline is included in the example file archive.