DIRECTORATE-GENERAL
INFORMATICS
Information systems Directorate
European Commission
e-Procurement Section, DIGIT B4
e-PRIOR Customer Interface Control Document
Date: / 1/08/2012Version: / 2.000
Authors: / e-PRIOR project team
Revised by: / Didier Thunus (European Commission, DIGIT B4)
Approved by:
Public:
Reference Number:
Single point of contact for support:
Table of Contents
1. Introduction 6
1.1. Purpose of the Customer Interface Control Document 6
1.2. Scope of this Document 7
1.3. Audience of this Document 8
1.4. Definitions, Acronyms, and Abbreviations 8
2. High-Level Architectural Mechanisms 10
2.1. Architectural Mechanisms of the documents to be exchanged 10
2.1.1. Reusable Schema Definitions 10
2.2. Architectural Mechanisms of the e-PRIOR Interface 10
2.2.1. Message Façade 10
2.2.1.1. Design by Contract 10
2.2.2. Content Based Routing 10
2.3. Architectural Mechanisms of the Communication Model 10
2.3.1. Asynchronous Mode (Synchronous Write / Synchronous Read) 10
2.3.2. Synchronous Mode 10
2.3.3. Notification Mode 11
3. Service Portfolio 12
3.1. User Profiles 12
3.2. Description of User Profiles 14
3.2.1. Read Services 14
3.2.2. Write Services 17
3.3. Communication Mode Detailed Description 18
3.3.1. Communication Mode Scenarios 18
3.3.2. Communication Mode Transport Protocol 19
Asynchronous Mode (Synchronous Write / Synchronous Read) 19
Synchronous Mode 19
Notification Mode 19
4. End-to-end Communication Workflows 20
4.1. Invoice 20
4.2. Credit Note 21
4.3. Attached Document 22
5. Realization 23
5.1. XML Schema Definitions 23
5.1.1. XML encoding 26
5.2. Boundary Interface Design Model 27
5.2.1. Message Bus Façade 27
5.2.1.1. WSDL types part 27
5.2.1.2. WSDL messages part 28
5.2.1.3. WSDL ports part 30
5.2.1.4. WSDL binding part 30
5.2.1.5. Binary Attachments 32
5.2.2. Content Based Routing 33
5.3. Security Considerations 33
5.3.1. Security Problem Statement 33
5.3.2. Operand Security Model 34
5.3.3. Boundary Interface Security Model 34
5.3.4. Communication Mode Security Model 36
5.4. Document Processing Considerations 37
5.4.1. Maximum Message Size 37
5.4.2. Unique Message ID and Reliable Message Delivery 37
5.4.3. What is the role of the message ID? 38
5.4.4. Transactions Atomicity 39
6. Appendix I: Glossary of Terms 40
Table of Figures
Figure 1 e-PRIOR multi-sided platform 6
Figure 2 Billing processes within the e-Procurement domain 8
Figure 3 Billing documents tree 12
Figure 4 Read Use Cases of e-PRIOR 14
Figure 5 Use Cases of the Back-Office following a Retrieve Request 16
Figure 6 Write Use Cases of e-PRIOR 17
Figure 7 e-Invoice scenario 18
Figure 8 Invoice communication workflow 20
Figure 9 Credit Note communication workflow 21
Figure 10 Attached Document communication workflow 22
Figure 11 UBL Documents Architecture 23
Figure 12 EC UBL subset: The default UBL document namespaces are used in most documents exchanged in e-PRIOR’s Write Services 24
Figure 13 Snippet of the UBL Payload in the context of a CEN/ISSS WS/BII Billing Profile 25
Figure 14 EC UBL subset: Custom document namespaces are used in most documents exchanged in e-PRIOR’s Read Services 25
Figure 15 UBL two-phase document validation 26
Figure 16 XML encoding 26
Figure 17 WSDL 1.1 Structure 27
Figure 18 WSDL types part 28
Figure 19 WSDL message part submitted from the Customer to e-PRIOR 28
Figure 20 WSDL message part submitted from e-PRIOR 28
Figure 21 WSDL fault message 29
Figure 22 SOAP fault of the Client type 29
Figure 23 SOAP fault of the Server type 30
Figure 24 WSDL ports part 30
Figure 25 WSDL binding part 30
Figure 26 SOAP Envelope Structure 31
Figure 27 WSDL binding part input/output 31
Figure 28 SOAP Body 32
Figure 29 MIME header at HTTP level 32
Figure 30 SOAP message with Attachment Part 32
Figure 31 SOAP Header 33
Figure 32 User Access Process 35
Figure 33 Interchange Agreement 36
Figure 34 Message ID 38
Document History
0.001 / 11/06/2010 / First draft / All pages
0.002 / 17/06/2010 / Implementation of internal comments / As required
0.003 / 18/03/2011 / Update throughout the document / As required
0.004 / 10/02/2012 / Update throughout the document / As required
0.005 / 12/07/2012 / Update throughout the document / As required
2.000 / 1/08/2012 / Update to services v2.0 / As required
1. Introduction
Public procurement accounts for 16% of GDP in OECD member countries. It is a versatile mechanism that can be used to pursue several aims such as process efficiency, innovation or social goals.
Across the EU, the uptake of e-Procurement is variable and the objective of transitioning to 100% e-Procurement is far from complete. In March 2010, the European Commission launched the Europe 2020 Strategy to turn the EU into a smarter, more sustainable and inclusive economy. The Digital Agenda for Europe, successor of the i2010 policy framework, is one of the seven flagship initiatives of Europe's 2020 Strategy. One of these key challenges is precisely the inter-connection of e-procurement communities in the EU. In order to bridge the gap between the costs of creating an e-Procurement infrastructure, the resources which are available, and to ensure its use to all Directorate Generals and Services of the European Commission, e-PRIOR was built by the Director General for Informatics (DIGIT).
DIGIT writes this document to demonstrate how e-PRIOR can be used to e-enable the existing Back-Office systems of the several European Commission and Services. The role of the European Commission, in addition to the creation of e-Procurement policy, is to lead by example.
1.1. Purpose of the Customer Interface Control Document
Customer and Supplier are the two key roles involved in the several e-Procurement processes. To interconnect them, e-PRIOR exposes an interface to the Information Systems used by Suppliers and another one to the information systems used by Customers. Conceptually, e-PRIOR is a multi-sided platform bringing together these two distinct but interdependent entities. The value of e-PRIOR is to facilitate interactions between them. In brief, e-PRIOR is an intermediary between the information systems of these business partners. In this context, the Directorate Generals, or Services, of the European Commission play the Customer role.
Figure 1 e-PRIOR multi-sided platform
While [REF1] specifies the interface exposed to Suppliers, this document describes the interface exposed to the internal systems of the European Institutions. Throughout this document they will be called "the Back-Office". In this document, a service should be understood as an abstract resource exposed by e-PRIOR and consumed by a Back-Office or, vice versa, exposed by a Back-Office and consumed by e-PRIOR.
A service is a mechanism to enable digitisation of one or more e-Procurement processes, where the access is provided using e-PRIOR’s interface and is executed consistent with the constraints and policies specified in this document. In this context, services are provided by DIGIT – the service provider – for use by the Directorate Generals, or Services, of the European Commission. The services of e-PRIOR are opaque since their implementation is hidden from their consumers, except for the information model exposed through the interface itself and the other technical information required to determine whether a given service is accessible by them. Interacting with the services of e-PRIOR involves sending and receiving messages. The information model and the sequence of exchanges are explained in detail in the next chapters.
The same Back-Office can be used by several Customers. e-PRIOR considers the Back-Office as a User and the Customer as a Business Partner. A Back-Office may serve several Customers. Each Business Partner is identified through a unique identifier. The Back-Office is given a Username and Password. A message sent by the Back-Office can only refer to one Business Partner.
As explained above, each Directorate General or Service of the European Commission connected to e-PRIOR is given a unique identifier to make itself known to the Suppliers submitting documents in electronic format to e-PRIOR. It goes without saying that the Supplier must always indicate, in the electronic message, the ID of the Directorate General or Service responsible for the business verification and approval of the document. As a result, and following a number of pre-emptive checks, e-PRIOR can easily route it to the Back-Office of the final receiver within the European Commission[1]. Once a document is received and processed by the Back-Office, the response from the Customer is also delivered to the Supplier via e-PRIOR. In this case, the Customer must indicate, in the electronic message, the ID of the Supplier to which the business response is addressed. The end-to-end communication workflows are included in chapter 4.
1.2. Scope of this Document
This document covers the service interface of e-PRIOR. It includes information about the transmission protocol, information model and the sequence of exchanges. This specification addresses no more than the service interface of e-PRIOR. All other aspects of its implementation are of no concern to the Back-Office (i.e. the service consumer). The ICD specification provides both the provider (i.e. the implementer) of the services and their consumers with a complete specification of the following aspects:
· Interface Functional Specification, this specifies the set of services and the operations provided by each service;
· Interface Behavioural Specification, this specifies the expected sequence of steps to be respected when calling a service or a set of services;
· Interface Message standards, this specifies the syntax and semantics of the data and metadata;
· Interface Policy Specification, this specifies constraints and policies regarding the operation of the service.
Although e-PRIOR embraces the full post-award procurement domain; this document is limited to the service model of the Billing business process. Traditionally, billing is initiated by the Supplier when invoicing the Customer for delivered goods or services. The messages to be exchanged between e-PRIOR and the Back-Office are provided in a separate annex to this document. Several annexes, also present in [REF1], should be used for the understanding of these schemas, in particular, the FAQ and Data Dictionary.
Figure 2 Billing processes within the e-Procurement domain
1.3. Audience of this Document
· The Directorate Generals and Services of the European Commission wanting to set up a connection between their Back-Office system and e-PRIOR for e-invoice enablement are the target audience of this document. In particular:
o Business Architects will find it useful for determining how to best exploit e-PRIOR to create a fully fledge e-Procurement solution.
o Analysts will find it useful to understand the Use-Cases of e-PRIOR.
o Architects will find it useful as a starting point for connecting a Back-Office system to e-PRIOR.
o Developers will find it essential as a basis of their development of e-Procurement services.
· The reader of this document is recommended to read chapter §1, §2 and §3 of [REF1]. These chapters contain all the background information required for the proper understanding of the services provided by e-PRIOR.
1.4. Definitions, Acronyms, and Abbreviations
The glossary in section 6 provides the reader with the terms used in this document.
Reference Documents
The table below provides the reader with the list of reference documents.
Reference / Document[REF1] / e-PRIOR Interface Control Document - if clicking this link does not refer you immediately to the correct location on CircaBC, enter the following link directly in your web browser: https://circabc.europa.eu/w/browse/5290b7b0-8ca8-454b-87eb-0ac990362861
[REF2] / OASIS Universal Business Language v2.0
[REF3] / ebXML (Electronic Business using eXtensible Markup Language)
[REF4] / CEN Business Interoperability Interfaces for Public procurement in Europe
[REF5] / W3C Web Services Architecture
[REF6] / European Interoperability Framework v.1.0 (EIF)
European Interoperability Framework v2.0 (Draft EIF)
[REF7] / Rational Unified Process version 7.5
[REF8] / Web Services Description Language (WSDL) 1.1
[REF9] / WS-I Basic Profile Version 1.1
[REF10] / Simple Object Access Protocol (SOAP) 1.1
[REF11] / XML Schema 1.1
[REF12] / Extensible Markup Language (XML) 1.0
[REF13] / Hypertext Transfer Protocol 1.1
[REF14] / HTTP Authentication: Basic and Digest Access Authentication
[REF15] / HTTP Over TLS
[REF16] / NES
[REF17] / Schematron
[REF18] / SOAP Messages with Attachments
[REF19] / CEN ISSS WS BII
[REF20] / GLN (Global Location Number) (also know as EAN)
[REF21] / ISO Schematron
[REF22] / RFC 2119
[REF23] / Reference Model for Service Oriented Architecture 1.0
2. High-Level Architectural Mechanisms
2.1. Architectural Mechanisms of the documents to be exchanged
2.1.1. Reusable Schema Definitions
Since compliance to legal and business regulations is crucial in B2G interactions, the several exchanged documents must have a common agreed-upon syntax and semantics. This mechanism allows the Customer to use documents assembled upon standard schemas which conform to a well-defined library of reusable data components. This approach promotes an enterprise-wide semantic model, implemented in standard schemas which decisively contribute to standard messages and therefore a stable interface.
2.2. Architectural Mechanisms of the e-PRIOR Interface
2.2.1. Message Façade
This mechanism allows the Customer, when using the aforementioned services, to dialogue with a unique system (i.e. e-PRIOR) using a unified interface via electronic messaging (i.e. e-PRIOR) instead of connecting to several internal systems of the European Commission. This approach promotes loose coupling and document-driven exchange of information. This approach ensures that high-volume, low latency, services are delivered competitively – in terms of cost, quality and timeliness. By doing so, they enable that Customers receive high quality services which adhere with European standards.
2.2.1.1. Design by Contract
This specification addresses no more than the service interface of e-PRIOR. All other aspects of its implementation (e.g. specific information on the software or hardware technology, physical location, etc…) are behind the scenes and are of no concern to the requester entity (i.e. the service consumer). This concept is also known as loose coupling. The use of Service-oriented architecture (SOA), promotes the use of a simple yet powerful technique, Design by Contract, that focuses on the agreement to the rights and responsibilities of each system based on the description of a service i.e. the Use-Case.