e-PRIOR Software Architecture Document · Open e-PRIOR Software Architecture Document – Page 5 /...

Commission européenne, B-1049 Bruxelles / Europese Commissie, B-1049 Brussel - Belgium. Telephone: (32-2) 299 11 11. Commission européenne, L-2920 Luxembourg. Telephone: (352) 43 01-1.

EUROPEAN COMMISSION DIRECTORATE-GENERAL INFORMATICS Information systems Directorate

European Commission

Open e-PRIOR Software Architecture Document

Date: 13/12/2010

Version: 2.01

Authors: Sandro D'Orazio, Marco Fichera, Joao Frade Rodrigues, Maarten Daniels

Revised by: Tanya Chetcuti

Approved by: Didier Thunus

Public:

Reference Number:

Open e-PRIOR Software Architecture Document Page i

TABLE OF CONTENTS

1. INTRODUCTION .................................................................................................................................... 4

1.1. Purpose .................................................................................................................................................... 4 1.2. Scope ....................................................................................................................................................... 4 1.3. References ............................................................................................................................................... 4 1.4. General Overview.................................................................................................................................... 6 1.5. PEPPOL overview................................................................................................................................... 7 1.5.1. PEPPOL transport Infrastructure.......................................................................................................... 7 1.5.2. Transport Profiles ................................................................................................................................. 8 1.5.3. PEPPOL Identifiers ............................................................................................................................ 11 1.5.4. Open e-PRIOR / PEPPOL interactions............................................................................................... 11 1.6. Document Content Overview ................................................................................................................ 13

2. ARCHITECTURAL REPRESENTATION......................................................................................... 13

3. ARCHITECTURAL GOALS AND CONSTRAINTS ........................................................................ 14

3.1.1. Supportability ..................................................................................................................................... 14 3.1.2. Usability ............................................................................................................................................. 14

4. SECURITY ............................................................................................................................................. 15

4.1. Security Overview ................................................................................................................................. 15 4.1.1. Introduction ........................................................................................................................................ 15 4.1.2. Transport Layer Security .................................................................................................................... 17 4.1.3. Message Level Security...................................................................................................................... 17 4.1.4. Application Level Security ................................................................................................................. 17 4.1.5. Logging and Auditing......................................................................................................................... 18 4.1.6. Other ................................................................................................................................................... 18 4.2. Scope ..................................................................................................................................................... 18 4.3. Assumptions .......................................................................................................................................... 18 4.4. The PEPPOL Gateway Security ............................................................................................................ 19 4.5. Mapping of Features to Requirements................................................................................................... 20 4.5.1. Mapping.............................................................................................................................................. 20 4.5.2. Database Security ............................................................................................................................... 21

5. USE-CASE VIEW .................................................................................................................................. 22

5.1.1. Use Cases Selection............................................................................................................................ 22 5.1.2. Architecturally significant Use Cases Diagram.................................................................................. 23

6. LOGICAL VIEW ................................................................................................................................... 24

6.1.1. Overview ............................................................................................................................................ 24 6.1.2. Architecturally Significant Design Packages ..................................................................................... 24 6.1.3. Use-Case Realizations ........................................................................................................................ 25 6.1.4. Main Interactions between Suppliers and Customers......................................................................... 45

Open e-PRIOR Software Architecture Document Page ii

7. DEPLOYMENT VIEW ......................................................................................................................... 46

8. IMPLEMENTATION VIEW................................................................................................................ 48

8.1. Overview ............................................................................................................................................... 48 8.2. Layers .................................................................................................................................................... 50 8.2.1. PEPPOL Acces Point Layer ............................................................................................................... 50 8.2.2. Service Bus Layer............................................................................................................................... 53 8.2.3. Process Manager Layer ...................................................................................................................... 54 8.2.4. Customer Integration Layer................................................................................................................ 54

9. DATA VIEW........................................................................................................................................... 55

9.1. Data Model ............................................................................................................................................ 55 9.2. State Machines....................................................................................................................................... 57 9.2.1. Introduction ........................................................................................................................................ 57 9.2.2. Legend ................................................................................................................................................ 58 9.2.3. Generic State Machines ...................................................................................................................... 58 9.2.4. State Machines for Generic Objects ................................................................................................... 59 9.2.5. State Machines for the "Invoicing" Functionality .............................................................................. 59 9.3. Queries and Virtual Inbox ..................................................................................................................... 60 9.3.1. Queries................................................................................................................................................ 60 9.3.2. Virtual Inbox ...................................................................................................................................... 60 9.3.3. Retrieval ............................................................................................................................................. 60

10. SIZE AND PERFORMANCE............................................................................................................. 60

10.1. Size ...................................................................................................................................................... 60 10.2. Performance......................................................................................................................................... 60

11. QUALITY ............................................................................................................................................. 61

11.1. Extensibility......................................................................................................................................... 61 11.2. Reliability ............................................................................................................................................ 61 11.3. Portability ............................................................................................................................................ 61

12. TEST INTERFACE SPECIFICATION............................................................................................. 62

Open e-PRIOR Software Architecture Document Page iii

Document History

Version Date Comment Modified Pages

0.01 22/04/2010 Fisrt Draft all

0.02 27/04/2010 Second draft all

1.00 27/04/2010 All comments incorporated All

2.00 27/09/2010 Added Submit Order Use Case implementation including PEPPOL outbound document sending.

Modified architecturally relevant use cases diagram.

Updated available services table with Submit Order and Submit Catalogue.

6, 23 (Modified)

39-45 (Added section 6.1.3.3)

2.01 13/12/2010 Added Retrieve Request Use Case 6

Open e-PRIOR Software Architecture Document – Page 4 / 63 Document Version 2.01 dated 14/12/2010

1. INTRODUCTION

1.1. Purpose

This document provides a comprehensive architectural overview of the system, using a number of different architectural views to depict different aspects of the system. It is intended to capture and convey the significant architectural decisions which have been made on the system.

1.2. Scope

The architecture described in this document concerns the system Open e-PRIOR of the European Commission and its integration with the PEPPOL gateway. This product is the open source version of e-PRIOR, also developed and used by the European Commission as part of the IDABC programme.

1.3. References

# Document Contents outline

[REF1] GIP of 07/02/2008 by DIGIT/B4 Global Implementation Plan written for the IDABC PEGCSO, and its annexes. Annex I: Feasibility Study; Annex II: Requirements Catalogue.

[REF2] e-PRIOR EDI validation by DIGIT/B4 Validation of the e-PRIOR system against the e-Invoicing and e-Archiving requirements, as mentioned in the EU Council Directive 2001/115/EC, now incorporated in Council directive 2006/112/EC.

[REF3] e-PRIOR Interface Control Document t v1.000 by DIGIT/B4 of 06/02/2009

Interface control document for front-offices and external systems

[REF4] Test Management Plan by DIGIT/B4 Description of the test strategy and implementation of e-PRIOR.

[REF5] Enterprise Integration Patterns Patterns and best practices for Enterprise Integration by Gregor Hohpe

[REF6] Spring Integration Extension of the Spring programming model to support the well-known Enterprise Integration Patterns

[REF7] Spring Web Services Spring Web Services is a product of the Spring community focused on creating document-driven Web services

[REF8] Apache XMLBeans XMLBeans is a technology for accessing XML by binding it to Java types

[REF9] Schematron Rule-based validation language for making assertions about the presence or absence of patterns in XML trees

[REF10] JBoss Application Server Java EE certified open source application server

[REF11] JBoss JBPM JBoss business process management suite

[REF12] EJB Enterprise Java Beans

http://www.eaipatterns.com/

http://www.springsource.org/spring-integration

http://static.springsource.org/spring-ws/sites/1.5/

http://xmlbeans.apache.org/

http://www.schematron.com/

http://www.jboss.org/

http://www.jboss.org/jbpm

http://java.sun.com/products/ejb/


[REF13] REST Representational State Transfer

[REF14] SOAP Simple Object Access Protocol

[REF15] WS-Addressing Web Services Addressing provides transport-neutral mechanisms to address Web services and messages

[REF16] WS-Transfer Web Services Transfer : This specification describes a general SOAP-based protocol for accessing XML representations of Web service-based resources

[REF17] WS-Reliability WS-Reliability is a SOAP-based ([SOAP 1.1] and [SOAP 1.2 Part 1]) specification that fulfillsreliable messaging requirements critical to some applications of Web Services

[REF18] WS-Security Standard set of SOAP [SOAP11, SOAP12] extensions that can be used when building secure Web services to implement message content integrity and confidentiality

[REF19] WS-Policy The Web Services Policy Framework (WS-Policy) provides a general purpose model and corresponding syntax to describe the policies of a Web Service

[REF20] WS-SecurityPolicy WS-Policy defines a framework for allowing web services to express their constraints and requirements. These are security related policies

[REF21] SAML 2.0 This specification defines the use of Security Assertion Markup Language

[REF22] X.509 Public-Key Infrastructure (X.509)

[REF23] PEPPOL Common Definitions Contains the definitions and terms that are common between the Business Document Exchange Network (BUSDOX) service metadata and transport specifications

[REF24] PEPPOL Service Metadata Publishing Describes the REST (Representational State Transfer) interface for Service Metadata Publication within the Business Document Exchange Network (BUSDOX)

[REF25] PEPPOL Service Metadata Locator This document defines the profiles for the discovery and management interfaces for the Business Document Exchange Network (BUSDOX) Service Metadata Locator service

[REF26] PEPPOL START Profile This document describes the SOAP-based profile that is used by Business Document Exchange Network(BUSDOX) Access Points to communicate and the SAML 2.0 assertions that are used in that communication

[REF27] PEPPOL LIME Profile The Lightweight Message Exchange Profile (LIME) provides a simple low-cost approach for Small and Medium Enterprises (SMEs) to access

http://en.wikipedia.org/wiki/Representational_State_Transfer

http://www.w3.org/TR/soap/

http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/

http://www.w3.org/Submission/WS-Transfer/

http://docs.oasis-open.org/wsrm/ws-reliability/v1.1/wsrm-ws_reliability-1.1-spec-os.pdf

http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

http://www.w3.org/Submission/WS-Policy/

http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/ws-securitypolicy-1.2-spec-os.html

http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.0.pdf

http://datatracker.ietf.org/wg/pkix/charter/

http://www.peppol.eu/work_in_progress/wp8-Solutions architecture%2C design and validation/specifications/v1-0-specifications/commondefinitions/at_download/file

http://www.peppol.eu/work_in_progress/wp8-Solutions architecture%2C design and validation/specifications/v1-0-specifications/service-metadata-publishing/at_download/file

http://www.peppol.eu/work_in_progress/wp8-Solutions architecture%2C design and validation/specifications/v1-0-specifications/service-metadata-locator-profile/at_download/file

http://www.peppol.eu/work_in_progress/wp8-Solutions architecture%2C design and validation/specifications/v1-0-specifications/secure-trusted-asynchronous-reliable-transport-start/at_download/file

http://www.peppol.eu/work_in_progress/wp8-Solutions architecture%2C design and validation/specifications/v1-0-specifications/lightweight-message-exchange-profile-lime/at_download/file


Business Document Exchange Network (BUSDOX) infrastructure

[REF28] PEPPOL AP WSDL The wsdl service definition of the PEPPOL Access point

[REF29] JAX-WS JAX-WS Webservice API definition

[REF30] Metro The Metro webservice stack (JAX-WS implementation)

[REF31] BPMN Business Process Modeling Notation

[REF32] CEN-BII CENBII specification is a meant to facilitate effective public procurement solution with focus on cross-border interoperability.

1.4. General Overview

Open e-PRIOR is an enterprise e-Procurement application aiming at making available, via electronic means, several services related to the post-awarding stages of procurement (i.e. e-Catalogues, e-Ordering and e-Invoicing). Open e-PRIOR enables Customers to execute their procurement processes electronically.

To make this possible, Suppliers and Customers uses the electronic services of Open e-PRIOR, via machine-to-machine interactions. Open e-PRIOR plays the role of intermediary between the external world and the back-office applications of the Customer. Open e-PRIOR is designed to interoperate with a large number of applications of heterogeneous nature.Furthermore, Open e-PRIOR is connected to the PEPPOL infrastructure via its own PEPPOL gateway. This enables the exchange of electronic documents via the PEPPOL infrastructure.

The following table shows the services available via the interface provided by e-PRIOR and the ones available via the Open e-PRIOR PEPPOL Access Point :

Service Open e-PRIOR Interface PEPPOL Access Point

Submit Invoice X X

Submit CreditNote X X

Submit AttachedDocument X X

View Document X

Query Request X

Status Request X

Retrieve Request X

Submit Order X X

Submit Catalogue X X

https://jax-ws.dev.java.net/

https://metro.dev.java.net/

http://www.bpmn.org/

http://spec.cenbii.eu/


1.5. PEPPOL overview

The Open e-PRIOR system is able to send and receive documents from the Pan-European Public Procurement Online (PEPPOL) network through its shipped in access point. This chapter gives an overview of PEPPOL to help the reader understand what PEPPOL is and the impact of this integation on the System architecture.

1.5.1. PEPPOL transport Infrastructure The PEPPOL transport infrastructure is a set of standardized communication protocols which allows the Member States to exchange electronic documents in an interoperable, secure and reliable way. Public agencies and private enterprises could use the PEPPOL infrastructure to send and receive e-documents by connecting to the Access Points, which are the base element of the infrastructure, sharing the same transport protocol and the same document format, and using modern digital signatures algorithms to secure message content.

The figure below shows the main components involved in the PEPPOL infrastructure.

Figure 1: PEPPOL Infrastructure

The sender of an electronic document (for example an e-Invoice, an e-Order or an e-Catalogue), which can be an SME or a public administration, uses an Access Point to connect to the PEPPOL network, specifying the type of document being sent and the recipient, uniquely identified in the network by a business ID.

In order to route the documents received from the sender to the correct recipient, the Access Points in the network need to discover each other. To do so, the strategy used by the PEPPOL infrastructure is to centralize addressing and metadata information into servers called "Service


Metadata Publishers" (SMPs) [REF24], which servers contain the addresses of the Access Points related to a given party. SMPs are used to store information about the parties connected to the PEPPOL network, giving details about the document types supported and the business collaboration profiles.

The last main entity in the infrastructure is the Service Metadata Locator (SML) [REF25]. Since every participant in the PEPPOL network, whethere a sender or a recipient, could be registered in one and only one SMP, the Access Points must know which one to connect to, in order to retrieve the metadata about that specific recipient party. The SML is the entity which contains, for every business ID, the related SMP.

1.5.2. Transport Profiles PEPPOL Transport Infrastructure specification defines two different "profiles", or communication protocols, to let all the parties involved to exchange messages in a standard way.

The START (Secure Trusted Asynchronous Reliable Transport) [REF26] profile is the full profile which includes all the security and realiability features provided by the infrastructure, and it is used for the communication between two Acces Points (AP). It is based on Web-Service technologies, and it uses several WS-* standards:

• WS-Addressing [REF15], to address remote resources (APs, SMP/SML)

• WS-Transfer [REF16], built on top of WS-Addressing to create/modify remote resources

• WS-Reliabilty [REF17], to ensure reliability of message exchange

• WS-Security [REF18], to manage authentication, authorization and signatures on

exchanged messages.

WS-Addressing [REF15] standard is used by PEPPOL for addressing an AP in the network. Every access point must have its own EPR (Endpoint Reference), in order to be called by other access points. Whenever a sender AP requests the address of a receiver from the SMP, the EPR of the receiver AP is provided by the SMP.

WS-Transfer [REF16] protocol is used to create new resources on the PEPPOL infrastructure. Whenever a document has to be sent to a receiver AP using his EPR, a Wst:Create request has to be sent to the receiver AP.

WS-Reliability [REF17] protocol is used to ensure the delivery of both requests and responses. When a document has to be sent a WSRM sequence must be initiated. Multiple messages must be sent to the destination AP in order to complete the sequence:

• wsrm:CreateSequence

• Business Message(s) (inside a WS-Transfer Create request)

• wsrm:TerminateSequence

• wsrm:CloseSequence

On the next page, an overview of the messages exchanged between the different components of the infrastructure is shown.


Figure 2: Message exchange using the START profile

WS-Security [REF18] standard is used in the PEPPOL infrastructure to secure all the messages exchanged between APs. Many fragments of the SOAP [REF14] message (SOAP Body, some parts of SOAP Header) have to be signed by the sender AP before sending the message to the receiver, to preserve security and integrity of the message itself.

WS-Security SOAP headers carry the signature generated from the message by the sender AP and the security token used to sign.

SAML 2.0 [REF21] security tokens are used to carry security information across the infrastructure. SAML 2.0 protocol is based upon "assertions", which carry the security claims (keys, certificates, references to external authorities) and the conditions under which the information is valid.

A compliant implementation of a PEPPOL AP must be able to support the START profile [REF26] and thus support all the standards listed above.

The START profile, as stated above, does not involve the communication between the actual sender/recipients (public agencies, private companies) and the APs. The PEPPOL specification leaves the implementation free to final users/businesses, so existing technologies can be used.

Nevertheless, PEPPOL infrastructure defines a standard protocol to address this issue: the LIME (Lightweight Message Exchange) profile [REF27]. This profile can be used by senders and/or recipients to connect to the APs of the PEPPOL infrastructure. It is based upon a subset of PEPPOL infrastructure specification, and it can be easily implemented by SME or individuals who want to connect to the network.

WS-Transfer protocol is used to send and retrieve messages from the AP. Wst:Create and Wst:Put operations of WS-Transfer specification are used to create resources (documents) into


the AP, while wst:Get operation is used to retrieve the incoming documents stored into the AP. Messages can be deleted using the wst:Delete operation.

The picture below shows the message exchange pattern between the sender/recipient of the message and the LIME AP. In this complete scenario, LIME profile is used by the final endpoint to send messages to the AP, while START profile is used for the communication between the two involved AP. The pattern is as follows:

• The sender (Company 1) sends a message directed to the recipient (Company 2) to the AP1 using the LIME profile.

• The AP1 looks for the address of the AP2 using the service provided by the SMP.

• The SMP returns to the AP1 the address (EPR) of the AP2.

• The AP1 sends the message to AP2 using the START profile.

• The AP2 delivers the message to Company2 (using LIME profile or existing technologies).

• The reply produced by Company 2 is sent to Company 1 following the same pattern.

• Company 1 retrives the reply message from AP1 using LIME profile (Wst:Get operation).

Figure 3: Message exchange using the LIME profile


1.5.3. PEPPOL Identifiers PEPPOL transport infrastructure uses a set of identifiers to address resources and to define them univocally:

• Business Identifier: uniquely identifies a sender/receiver on the PEPPOL network. Standard schemes like GLN, DUNS, CVR can be used.

Ex: 0010:5798000000001

• Document Identifier: uniquely identifies a document type in the PEPPOL network. Ex: urn:oasis:names:specification:ubl:schema:xsd:Order-2::Order##OIOUBL-2.02

• Process Identifier: identifies the process in which the document can participate.

• Message Identifier: identifies the single message across multiple hops in the network. The above information is carried along in the header of the SOAP messages defined by START and LIME profiles.

SMPs use the identifiers to return to the requesting AP the address of the recipient AP. APs have to submit the recipient business identifier, the document identifier and the process identifier in their queries to the SMP.

As for document and process types and schemas, PEPPOL supports (and encourages) the use of UBL 2.0 documents and CEN/BII profiles.

Further details about the identifiers can be found on the PEPPOL website [REF23].

1.5.4. Open e-PRIOR / PEPPOL interactions One of the goals of the Open e-PRIOR projects is to support PEPPOL transport infrastructure, by giving to users the means to send and receive documents via the PEPPOL network.

In order to fulfil this objective, a PEPPOL Access Point has been included in the Open e-PRIOR software. The Access Point, compliant with the START profile [REF26], will address the following requirements:

• Receiving documents (for ex. e-Invoices) from Suppliers connected to the PEPPOL network and forwarding them to Open e-PRIOR for processing.

• Sending electronic documents (for ex. e-Orders, Invoice responses) coming from Customer Back Offices via Open e-PRIOR to Suppliers via the PEPPOL Network.

Following is a typical interaction scenario:

• The Supplier system connects to a PEPPOL Access Point in its country (AP1) and sends a document to a Customer using Open e-PRIOR.

• AP1 queries the Service Metadata Publisher (SMP) for the Customer AP address, submitting the business ID of the receiver, the document type and the process type.

• SMP returns the address of the Open e-PRIOR PEPPOL Access Point (AP2).

• AP1 sends the message containing the document to AP2.

• AP2 forward the message to Open e-PRIOR.

• Open e-PRIOR processes the document and sends it to the Customer Back Office. If required by the process, a response can be generated and the following steps will take place:

• The Back Office generates a response and sends it to Open e-PRIOR.

• Open e-PRIOR forwards the response to AP2.


• AP2 queries the Service Metadata Publisher (SMP) for the Supplier AP address, submitting the business ID of the Supplier, the document type and the process type.

• SMP returns the address of the Supplier's PEPPOL Access Point (AP1).

• AP2 sends the message containing the response to AP1.

• AP1 forwards the response to the Supplier. Below, a diagram showing the message flow.

Figure 4: Message flow between Open e-PRIOR and PEPPOL


In case that the Customer has to send a document to the Supplier (for instance an e-Order), a similar scenario could be followed, starting from the Customer instead of the Supplier.

No direct connections between the Customer and Open e-PRIOR Access Point are required for the above scenario. Indeed, the Open e-PRIOR Access Point will communicate only with Open e-PRIOR application (via existing technology, for example JMS queues) and with other PEPPOL Access Points (using the START profile [REF26]). Therefore, to fulfil the requirements there is no need for Open e-PRIOR to implement the LIME [REF27] profile.

1.6. Document Content Overview

After summarizing the architectural representation, goals and constraints, this document details the security architecture and exposes the system using several architectural views (Use Case, logical, process, deployment, implementation and data). It then concludes with size, performance and quality considerations.

2. ARCHITECTURAL REPRESENTATION

The next two sections will describe architectural goals and constraints and the system security because they have important consequences on the system architecture.

Architecturally relevant Use Cases will be presented with a Use Case diagram and a short explanation detailing its impact on the architecture. The following views will also be provided:

- A logical view will show the main services the application must provide and theinteractions with system users. Package diagrams will be used in the Logical View. They must be understood as a logical representation of the main concepts handled by the system and not as implementation packages. Moreover, to keep a high degree of granularity, groups of related services will be modeled as "aggregate" packages. This will help the reader to easily view relations between groups of services, and it will keep diagrams simple. Sequence diagrams will also be used to represent main interactions between the services provided and the main interactions between Suppliers and Customers.

- An implementation view will describe the software layers decomposition and the main software components. Component diagram will be used in the implementation view.

- A deployment view will provide a description of the hardware components and how they are linked together. This view gives a technical description of protocols and hardware nodes used. Deployment diagram will be used to describe the deployment view.

- a data view that will provide information about data persistency describing in particular persistent entities. A class diagram will be used in the Data View to model main system data.

UML diagrams will be used systematically to represent the different views of the system, since it is a mature international standard. The goal of these diagrams is to represent our ideas and to let people understand them easily.


3. ARCHITECTURAL GOALS AND CONSTRAINTS

3.1.1. Supportability Interface Versioning

Subtype: Adaptability

The system should support the versioning of its interface to external applications.

Multilingualism support

Subtype: Localizability

The system should enable users to submit requests in their own language, or in a limited set of languages at EU level. The response must comply with the language of the request.

3.1.2. Usability Exposure of an applications interface for data communications

Subtype: Accessibility

The system must expose an interface for data communications with external and/or internal applications. This interface must facilitate the access to the system's services.

Discovery of services


The system must facilitate the discovery of its services by its users.

Distribution of data schemas and data definitions


The system must facilitate the distribution of the data schemas and data definitions needed by users for accessing its services.

Maximum level of transparency, minimum effort and agreed level of security

Subtype: Operability

The system's services should have a maximum level of transparency, involve minimum effort and provide the agreed level of security.

Understandable data schemas

Subtype: Understandability

The system must use data schemas enclosing data definitions which are understandable both at the level of the logical concept and also at the level of its applicability.


Use of a single syntax

Subtype: Learnability

The system must use a single syntax in the description of the meaning and structure of the underlying data.

Access to support documentation

Subtype: Learnability

The system must facilitate the access to support documentation directed to its users/ end-users (e.g. user manual, data dictionary).

4. SECURITY

4.1. Security Overview

4.1.1. Introduction The Open e-PRIOR solution will consist of several components that cover different zones of trust. The core system should be deployed within the secure zone of the public Authorities that will use it. The main goal is to deliver a secure and simple way of processing electronic documents. To reach this goal, a balance has to be found between security and simplicity by obtaining a high level of safety without turning the project into a complex unworkable fortified solution. Open e-PRIOR integrates the PEPPOL gateway in order to allow the exchange of cross border electronic documents. This document will also explain how the security is implemented in the gateway.

The overall philosophy of protection that will be used in Open e-PRIOR is to provide a manageable and working solution that will be used in a day to day environment while keeping an adequate level of security. Care will be taken however that the solution will not turn into an unworkable system filled with extensive security measures just for the purpose of adding technical specifications. It is assumed that a good level of technical security, together with well designed procedures, audit controls and logging provide the best balance between cost and benefits.

In designing the solution, attention has been given to conform to all legal requirements that exist for electronic Invoicing and Ordering. From a legal perspective, the solution can be classified as an EDI system. A full description of the EDI requirements and a validation of e-PRIOR, and thus of Open e-PRIOR, against these requirements can be found in [REF2]. These requirements include processes for authentication, integrity and validity of documents both during transmission and storage. Besides these it is also important to include measures for authorization, confidentiality, auditing and non-repudiation.

A short description of the security requirements indicates these needs:

– Authentication ensures that the parties involved in communication are really who they say they are.

– Integrity guarantees that a message is not modified in transition.

– Validity certifies a stored message does not lose its legal attributes.

– Authorization ensures that users only have access to the resources they are granted access to.

– Confidentiality is needed to prevent third parties from eavesdropping on information that is being transmitted.


– Auditing controls enable relevant parties like authorized bodies to inspect transactions afterwards.

– Non-repudiation measures prevent users from denying actions they have undertaken.

Besides technical security measures, there is also a focus on other aspects that have a positive impact on security. These other aspects comprise procedures and logging. The use of adequate business procedures can guarantee a high level of security without having technical measures that are too strict and thus are workable in a day to day environment.

An appropriate level of logging and audit trails will provide involved parties a timely indication of possible issues and a starting point for debugging or investigating.

Finally, in addition to operational needs for security, care is also taken to extend security measures from the system to the archiving of Invoices, Orders and associated data. Legal constraints impose extra requirements to guarantee that archived Invoices remain unmodified and readable throughout their storage period which lasts more than ten years.

Figure 5: Security Overview

The first focus lies on technical security measures. In IT architecture there are various levels at which security measures can be applied. These layers include transport, message and the application layer.


4.1.2. Transport Layer Security Transport layer security provides point to point security between two communicating parties. This can be viewed as a protected tunnel that will be set up between two points. Information inserted into the tunnel is protected until it leaves the tunnel at the endpoint. This has the repercussion that the start point and endpoint need to be in a secure environment themselves. Otherwise your data could be compromised when it leaves the tunnel. At the transport level the public authorities using Open e-PRIOR should use https.

As Open e-PRIOR has no control on the infrastructure in place at the site of the Customer willing to use it, transport level security will have to be implemented by the Customer himself.

HTTPS is a secure version of the HTTP protocol and is used to protect data transactions for commercial and financial purposes. It uses a Secure Socket Layer (SSL) and digital certificates to encrypt a data transfer session over an otherwise unsecure HTTP connection. SSL transactions are negotiated by means of a key based encryption algorithm between the client and the server. A digital certificate is being sent by the server to the client to prove its identity. To verify the certificate, the client must possess the root certificate for the key that was used to sign the server's certificate. This can be enabled by either exchanging and installing the root certificate in front or using a root authority that is trusted between both parties. Note that normally HTTPS only guarantees the identity of the server and that the client does not need to identify itself to setup a communication channel. To overcome this problem and to meet the requirement of non repudiation, mutual authentication is needed by using either client certificates or a security token. Following, we shall discuss both client certificates and tokens and list the impacts of using either one of them. Firstly there are client certificates which, just like server certificates, can verify the identity of the client and which can be used to set up a secure communication channel or to digitally sign messages. The drawback however is that the use of client certificates is rather complex and requires every Supplier to obtain and manage its own certificates and the setup of a PKI (Public Key Infrastructure) to provide a repository of digital identities. Secondly, there are security tokens which can be used to alleviate the complexity of client certificates. Security tokens can exist in many forms: from one time passwords (OTP's) generated by a hardware device to normal passwords which we are used to acces websites on a day to day basis. Our assumption is that normal passwords are the best balance between security and simplicity. Given the fact that we are already applying HTTPS to set up the initial secure connection, using HTTP basic authentication with normal passwords over this secure connection gives us enough confidentiality that passwords are not stolen. Our assumption however does not hold if cautious care has not been taken to prevent password stealing by key logging or phishing techniques.

The transport level measures on itself will provide restricted access to the system, confidentiality and integrity of message exchange. Authenticity of origin and integrity of received and stored content can be assured in combination with auditing and logging features that will be described below.

4.1.3. Message Level Security The next level of security protects the message exchange and the data itself instead of the transportation channel. In fact, message level security could completely replace transport level security, but this is not really practical for the intended architecture and its inherent limitations.

4.1.4. Application Level Security The highest level in the protocol stack is the application level. Application level security manages access to the services the system provides. To achieve a controllable method of handling access, user profiles will be used. A user profile is a set of user attributes that can be combined with access rights to facilitate management of system resource utilisation

Data-ownership is managed by giving users access to only the data they have created or to the data they have sufficient rights to browse.


4.1.5. Logging and Auditing Logging and auditing will be used as a complementary feature besides the technical security measures described above. It is foreseen that logging and auditing will occur at various levels in the system.

Firstly, all messages exchanges between the system and the users of the system will be logged to a database. The level of logging will not only provide guarantees to the sending and reception of messages to support the feature of non-repudiation, but will also help technicians and architects resolve technical errors in case of system malfunction.

All gathered logs will be maintained in a database that has restricted access and should be backed up regularly by the Customer. It is assumed that the logs cannot be tampered with in order to support their non repudiation characteristics.

4.1.6. Other It is assumed that the employed security measures guarantee a maximum and agreed level of security while incurring minimal effort for the users of the system. The solution should be well protected but workable.

An important security related aspect of the system is legal data protection and privacy. The system must ensure that all data exchanged between the system and its users are protected from disclosure to any unauthorized party. Additionally, it is mandatory that all gathered information about the users of the system is treated in harmony with existing European privacy protection regulations.

4.2. Scope

Like already stated in the security overview, Open e-PRIOR will consist in several components that cover different zones of trust. The core system will be deployed within the secure zone of the Customer but will need communication channels to the outside world. This means that it is expected that the secure zone of the Customer will provide a level of safety that will prevent attackers from compromising the system from within the boundaries of the secure zone of Customers. On a more detailed level this means that it is assumed that communication between different machines in this secure zone cannot be intercepted or altered by third parties.

4.3. Assumptions

The databases that will contain Invoicing data, logging information and audit trails will be kept in a secure environment where only authorized users have access to and audit trails are kept to ensure that the data is not tampered with. Additionally, it is assumed that regular backups of the databases are generated and securely archived.


4.4. The PEPPOL Gateway Security

This section will describe the authorisation and security requirements that must be met by messages sent or received by the Open e-PRIOR PEPPOL Access Point.

Security requirements are checked at SOAP level when the PEPPOL Access Point Web Service gateway is called by another external access point. A WS-SecurityPolicy [REF20] document included into the service contract [REF28] is used to check if the incoming message violates the security constraints. The same security requirements also apply to outgoing messages (coming from Open e-PRIOR), which must be validated by the destination AP.

The main security requirements are listed below (all the details can be found in [REF26]):

• X.509 Certificates: X.509 [REF22] certificates must be used to sign specific parts of the SOAP [REF14] message. Here is the an extract of the WS-SecurityPolicy document which specifies the parts to sign:

Figure 6: Extract of the WS-SecurityPolicy document

The AP must rely on a trust store to validate incoming certificates and on a key store to include its own certificate and to sign outgoing messages. Key stores and trust stores are defined in the WS-SecurityPolicy document for incoming messages and in the JAX-WS wsit-client.xml file for outgoing messages.

• SAML 2.0: a SAML 2.0 [REF21] assertion must be included in the SOAP header. The main content of the assertion are: subject (sender) ID, identity and signature of the token Issuer, strength of authentication method, time of the authentication, lifetime of the token, audience of the token and subject confirmation.

SAML 2.0 tokens can be generated by the sender AP, or be provided by external entities (Security Token Services). In both cases the signature of the entity which generated the token (the token issuer) must be embedded in the token itself, along with the signing X.509 certificate.

• WS-Security Timestamp: timestamp must be included in the exchanged messages. <wsu:Created> and <wsu:Expires> elements must then be present in the SOAP header.

<wsp:Policy wsu:Id="ResourceBinding_Get_Input_Policy"> <wsp:ExactlyOne> <wsp:All> <sp:SupportingTokens/> <sp:SignedParts> <sp:Body/> <sp:Header Name="To" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="From"Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="FaultTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="ReplyTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="MessageID" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="RelatesTo" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="Action" Namespace="http://www.w3.org/2005/08/addressing"/> <sp:Header Name="AckRequested" Namespace="http://docs.oasis-open.org/ws-rx/wsrm/200702"/> <sp:Header Name="SequenceAcknowledgement" Namespace="http://docs.oasis-open.org/ws-rx/wsrm/200702"/> <sp:Header Name="Sequence" Namespace="http://docs.oasis-open.org/ws-rx/wsrm/200702"/> <sp:Header Name="CreateSequence" Namespace="http://docs.oasis-open.org/ws-rx/wsrm/200702"/> </sp:SignedParts> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>


4.5. Mapping of Features to Requirements

4.5.1. Mapping The following table lists the security requirements together with the features which implement them.

Requirement Feature

Access to the system HTTPS with basic HTTP username and password authentication should be used.

Confidentiality of message exchange

HTTPS provides a secure transport channel and prevents untrusted third parties from reading exchanged messages.

Exchanged data integrity HTTPS provides a secure transport channel and prevents untrusted third parties from tampering with exchanged data during transport.

Authenticity of origin and integrity of content

Authentication with username and password, together with a secure transport channel, logging of exchanged data and secure database storage provides security about the origin and integrity of the content.

Access to services and user profiles

User profiles will be used that can be combined with access rights to facilitate management of system resource utilisation.

Data ownership Data ownership is assured by only giving users access to the data they have created or have sufficient rights to read or modify.

Access to logs and logging modification

Logs will be stored in a secure database with restricted access and regular protected backups.

Maximum level of transparency, minimum effort and agreed level of security

The architectural design covers a balance between usability and protection of the system without compromising any security aspects.

Legal data protection and privacy

All exchanged data between the system and its users are protected and personal data about users of the system is stored securely where unauthorized users or untrusted parties do not have access to.

Table 1: Security Requirements and Features


4.5.2. Database Security Many of the security features listed above rely on the fact that the database storage is secured (Authenticity of origin and integrity of content, Data ownership, Access to logs and logging modification, Legal data protection and privacy…). The table below lists the database security requirements that should be implemented by Public Authorities and the ones provided by Open e-PRIOR.

Requirement Implementation

Privilege restriction

Public Authorities hosting an instance of Open e-PRIOR should restrict the access to the application database. No database administration rights and no unnecessary privileges should be granted to the system user connecting to the database.

Strong user authentication

Databases are protected by standard encrypted passwords at the Operating System and database levels. All passwords have minimum complexity requirements. All administrative passwords should be changed on a regular basis.

The passwords of the Open e-PRIOR users (Suppliers and Customers) are kept encrypted in the database.

Data integrity Primary, unique and foreign keys and integrity constraints are used where appropriate to guarantee data integrity.

SQL injection is hampered by using parametrized statements and escaping in the embedded SQL.

Data encryption Only the passwords of Open e-PRIOR users (Suppliers and Customers) are kept encrypted in the database. No other data encryption requirement has been identified.

Auditing All database connections and disconnections should be audited (username, terminal, logon time, logoff time). This concerns all normal users as well as DBAs.

Application security

The security of the application is implemented at the level of the application, not at the level of the database. This means that the "One Big Application User" model is adopted for the database security. The advantage is that only the data sources and administration users are granted access to the database.

Backup and Restore

Customers using Open e-PRIOR should back up the database at regular intervals

Table 2: Database Security Requirements and Features


5. USE-CASE VIEW

This section provides a representation of the architecturally significant Use Cases.

5.1.1. Use Cases Selection The architecturally significant Use Cases have been selected based on the following criteria:

– Use Cases affecting multiple components of the system, thereby providing a cross-cutting view of the system architecture.

– Use Cases representing critical parts of the architecture, thereby addressing the technical risks of the project at an earlier stage.

The following Use Cases have been selected.

• Use Cases addressing the submission of documents by external applications (UC8 Submit Invoice and UC7 Submit Attachment)

• A Use Case addressing the submission of binary attachments (UC7 Submit Attachment)

• A Use Case addressing enquiries by external applications (UC15 Request Status)

• Use Cases addressing the interface with internal back-office systems (UC23 Route document).

• Use Cases on the system's infrastructure capabilities such as security (UC18 User Access).


5.1.2. Architecturally significant Use Cases Diagram

Figure 7: Use Cases Diagram


6. LOGICAL VIEW

6.1.1. Overview In this chapter we describe the main application packages, how they interact and how they implement system Use Cases.

In subsection 6.1.2 we describe the main packages of the system, how they are called by the system users and what subsystem (back-offices) they are interacting with.

In subsection 6.1.3 we explain how these packages participate to the implementation of two architecturally relevant Use Cases. Sequence diagrams are provided to illustrate packages interactions.

Subsection 6.1.4 provides a description of the possible high level interactions between Suppliers and Customers.

6.1.2. Architecturally Significant Design Packages The following diagram provides a high level view of the main packages composing the system. This diagram shows also the system users (represented as UML actors).

It is important to understand that even if just one Back Office is shown on the diagram there is no limit to the number of Back Offices that the Customer might interface with Open e-PRIOR.

Figure 8: System Users and Main Packages

Client Layer

• Services Client: Suppliers must use a client supporting messaging standards and protocols. Such client could be developed by the Supplier or third party companies.

• PEPPOL Network: the Open e-PRIOR system is able to send and receive electronics document via the PEPPOL network through its built in gateway.


Business Layer

• Supplier Integration Bus: the service bus allows the management of services in SOA architecture. The service bus generally calls the Process Manager that orchestrates services interactions. The Service Bus is the system entry point to services. It centralizes important functionalities like access management and logging. This Bus is the entry point from the external world (Suppliers) to the system. It is reached from Internet network and must be protected by the Customer's infrastructure security components (Firewalls, etc.). This bus is also the entry point for messages coming from the PEPPOL Network.

• Access Management: every call to the system services must be authenticated and the sender must be authorized to use the target service. The access management prevents unauthorized users from accessing certain services.

• Logging: actions taken within the system must be logged. Every access to the system must be logged and logs must provide information about who does what when and with which role. Moreover, specific activities must be logged to record business information during workflows' activities.

• Process Manager: a process manager allows the orchestration of services. Indeed complex interactions are needed to implement a workflow. The process manager provides the infrastructure to manage such workflows, handle correlation between message exchanges, asynchronous messaging, etc.

• The Customer Integration Bus is the mirror image of the Supplier Integration Bus for Customer. It provides entry points to the system for the Customers.

• Persistent Data: the system must keep track ofexchanged messages, information relative to Suppliers, System back-office interfaces, internal internationalized codes and legal information.

Back-Office Layer

• Customer Back Offices: This item represents the Customer legacy systems for invoicing and ordering.

6.1.3. Use-Case Realizations The following Use Cases have been chosen, to describe how software components behave:

• A Supplier submits an Invoice;

• A Supplier request the status of a document;

Indeed these two Use Cases use all the main components of the architecture. Open e-PRIOR offers both synchronous and asynchronous services and the two Use Cases chosen are an example of the two different behaviours of Open e-PRIOR. All the "submit document" Use Cases realizations can be easily extrapolated from the Submit Invoice described in this document and all the "read" Use Cases can be extrapolated from the Status request realization.


6.1.3.1. A Supplier Submits an Invoice When a Supplier submits an invoice, it does it either by using a client application if using the interface provided by Open e-PRIOR or via the provided PEPPOL Access Point if the submission of the invoice is done through the PEPPOL network. In both cases the application is accessed via the Supplier service bus. The main difference between the two methods of access is that the synchronous part of the invoice submission is skipped when accessing the system via the access point (explained in detail later). As is described in Section 4.1, the access is done using HTTPS and HTTP basic authentication (the user provides a password to let the system authenticate her/him). Service Bus uses the access management component to manage user authorizations; it logs the call and records information for the system monitoring.

The Supplier service bus is a lightweight ESB implemented using the Spring Integration [REF6] Framework which implements the well known Enterprise Integration Patterns [REF5].

The ESB component generally calls the Process Manager component to let it orchestrate the business services calls. The Process Manager also logs important business information by using the logging component and orchestrates business service calls.

The business service is called and it manages the actual communication with back-office(s). That communication will usually be asynchronous for scalability and fault tolerance reasons.

Back-office responses are received by a specific listener on the business service. The service then calls the Process Manager that continues to manage service orchestration.

The following diagram describes the process of submitting and processing an invoice in Open e-PRIOR via its set of provided services or via its PEPPOL Access Point. Such a process is described using "Enterprise integration patterns" notation. The next chapters describe all the elements presented in this diagram.


AutorisationService Activator

Invoice Endpoint

submitInvoiceRequestChannel

submitInvoiceResponseChannel

HeaderEnricher

Message IntegrityChecker

Message Internal Translator

Submit Invoice Service Activator

JmsDocumentOut channel

JMS Adapter to documentQueue

Header Value Router

JmsDocumentInvoiceIn channel

Invoice validation Service Activator

Invoice Schematron service Activator

Invoice Canonical Transformer service

Activator

Invoice synchronous processing

Invoice asynchronous processing

JMS Process Out channel

JMS Adapter to processQueue

JMS Process In channel

Header Value Router Process Manager

PEPPOL Acces Point

JMS Document In Channel

JMS Interface InboundAdapter

JMS Interface Inbound Channel


PEPPOL Entry Point

WebService Entry Point

Asynchronous Processing

jmsInvoiceProcessphase2a_SubmitInvoice service Activator

Peppol to JMS Message Translator

PEPPOL AP Database

PEPPOL Opene-PRIOR Integration

Session BeanPEPPOL AP

Session Bean

JMS Interface to Open E-Prior

Message Translator

Figure 9: Process of Submitting and Processing an Invoice


6.1.3.1.1. Submit Invoice via the PEPPOL Access Point

This chapter describes the processing of submitting an invoice via the PEPPOL Access Point.

The Supplier uses his own Access Point (or an Access Point in his network), to submit the invoice to Open e-PRIOR, by specifying the Customer Business ID. It is the Supplier's AP which then submits the document to the Open e-PRIOR Access Point.

When the Open e-PRIOR Access Point receives the Invoice (see section 8.2.1 for a detailed explaination of the PEPPOL components):

• PEPPOL Web Service gateway checks the incoming message by using its policy document and forwards it to the PEPPOL Session Bean;

• PEPPOL Access Point Session Bean queries the SMP by submitting as parameters the Recipient Business ID, the invoice document type and the basic invoice profile. This operation is performed to check if the recipient is a Customer using Open e-PRIOR for the given document/process types.

• PEPPOL Access Point Session Bean forwards the message to PEPPOL/Open e-PRIOR Integration Session Bean, which transforms the message, stores it into the database and sends it to the Open e-PRIOR JMS Interface Inbound Queue.

• Open e-PRIOR Service Bus reads the message from the queue, transforms it into an internal message format, checks internal authorisations (if the given Supplier has the right to send invoices to the given recipient) and submits it for asynchronous processing (see Section 6.1.3.1.2.2)

6.1.3.1.2. Submit Invoice in the Supplier Integration BUS

This chapter describes the processing of submitting an invoice in the Supplier service bus.

6.1.3.1.2.1. Synchronous invoice processing

6.1.3.1.2.1.1. Invoice endpoint

This is the endpoint for invoice processing. Calls to the Submit invoice web service are routed to this endpoint. Open e-PRIOR uses the Spring-ws [REF7] web service implementation. Soap calls are intercepted by the Spring Message dispatcher servlet which dispatches messages to an instance of spring-ws PayloadRootQNameEndpointMapping. This bean routes the incoming soap messages to the appropriate Spring Integration Endpoint according to the payload of the message (content based routing).

The message dispatcher servlet is configured as follows in the web.xml file of the OpenEPriorIntegration application:

<servlet> <description> This servlet is the entry point of the webservices end points of open eprior application that delegates the handling of incoming webservice calls to the Spring Integration messaging endpoint

</description> <servlet-name>services</servlet-name> <servlet-class> org.springframework.ws.transport.http.MessageDispatcherServlet

</servlet-class> </servlet> <servlet-mapping> <servlet-name>services</servlet-name> <url-pattern>/services/*</url-pattern> </servlet-mapping>

Figure 10: Invoice endpoint - Message Dispatcher Servlet Configuration

Access to this servlet is restricted by a security constraint that enforces basic authentication defined in the same file:

Figure 11: Invoice endpoint – Servlet Access Restriction

e-PRIOR security Realm is defined at JBoss [REF11] application server level in the JBoss login-config.xml file as follows:

Figure 12: Invoice endpoint – e-PRIOR Security Realm

This Jboss application-policy uses the Open e-PRIOR database to get users and roles. Passwords are stored encrypted in the database using SHA-1 algorithm and base 64 encoding.

 <security-constraint>

<display-name>epriorConstraint</display-name> <web-resource-collection> <web-resource-name>services</web-resource-name> <url-pattern>/services/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>SUP</role-name> <role-name>BCK</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>epriorRealm</realm-name> </login-config> <security-role> <role-name>SUP</role-name> </security-role>

<application-policy name = "epriorRealm"> <authentication>

<login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule" flag = "required"> <module-option name="dsJndiName"> java:/JbpmDS </module-option> <module-option name="principalsQuery"> SELECT USR_PASSWORD FROM EPR_VW_ALLUSERS WHERE USR_NAME=? </module-option> <module-option name="rolesQuery"> SELECT USR_TYPE,'Roles' FROM EPR_VW_ALLUSERS WHERE USR_NAME=? </module-option> <module-option name="hashAlgorithm">SHA-1</module-option> <module-option name="hashEncoding">base64</module-option> </login-module> </authentication> </application-policy>

Once the user is successfully authenticated the message dispatcher servlet dispatches the incoming soap message to the PayloadRootQNameEndpointMapping content base router that will route to the appropriate Spring integration Endpoint:

Figure 13: Invoice endpoint – Routing to the appropriate Spring Integration Endpoint

In the case of an invoice the message will be routed to the invoice endpoint. This endpoint is an instance of the EPriorSoapInboundGateway (used as endpoint for all the webservice calls). This class extends the Spring Integration Simple messaging gateway. This custom gateway allows customised handling of the incoming Soap Messages and of the SOAP faults. The gateway transforms the incoming Soap message into a Spring Integration Message

Figure 14: Invoice endpoint – Routing of SubmitInvoice Service Calls

This endpoint defines also the request and response channels for the Spring integration message.

The synchronous processing of the invoice is performed via a message handler chain configured to process messages submitted to the submitInvoiceRequestChannel :

 <bean id="endpointMapping" class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">

<property name="mappings"> <props> <prop key="{ec:services:wsdl:Invoice-0.1}SubmitInvoiceRequest"> invoiceEndpoint </prop> <prop key="{ec:services:wsdl:StatusRequest-0.2}SubmitStatusRequestRequest"> statusRequestEndpoint </prop> …… </props> </property> </bean>

 <bean id="invoiceEndpoint"

class="eu.cec.openeprior.esb.gateway.EPriorSoapInboundGateway"> <property name="requestChannel" ref="submitInvoiceRequestChannel" /> <property name="replyChannel" ref="submitInvoiceResponseChannel" /> </bean>

 <int:chain input-channel="submitInvoiceRequestChannel" output-channel="submitInvoiceResponseChannel">  <int:header-enricher> <int:header name="msgType" value="Invoice"/> <int:header name="operationType" value="SubmitInvoiceRequest"/> <int:header name="endPointId" value="0"/> <int:header name="phraseId" value="56"/> <int:header name="profile" value="0"/> <int:header name="MSG_TYPE" value="Phase2a_Invoice"/> </int:header-enricher > <int:service-activator ref="messageIntegrityChecker" method="checkMessageIntegrity" /> <int:transformer ref="messageTransformer" method="transformIncomingMessage" /> <int:service-activator ref="authorisationService" method="getAgreementForWrite" /> <int:service-activator ref="invoiceService" method="submitInvoice" /> </int:chain>


6.1.3.1.2.1.2. Header Enricher

This message Enricher is used to add technical information to the Spring Integration Message header.

6.1.3.1.2.1.3. Message Integrity Checker

This service activator is used to check the integrity of the incoming messages through checking that the incoming message contains only one document supported by the system. In the case of the invoice the system checks that the incoming document contains only one Invoice.

6.1.3.1.2.1.4. Message Translator

This is a common message translator that transforms the incoming soap message payload to an OpenEpriorIncomingMessage. It extracts information from the original message and stores it into an object structure. It also transforms the XML payload of the Soap Message to an Apache XMLBeans [REF8] representation of the incoming UBL document.

6.1.3.1.2.1.5. Authorization service activator

This service uses the authorization information stored in the Open e-PRIOR database to check if the Supplier is authorized to send an invoice to the target Customer. The Customer and Supplier GLN are specified in the SOAP Header of the incoming message.

6.1.3.1.2.1.6. Invoice Service Activator

This is the last element of the message handler chain; it sends the message to a JMS queue for asynchronous processing and builds the acknowledgment message that is returned to the Supplier.

6.1.3.1.2.1.7. Error handling

If an error occurs during the synchronous processing of the invoice, the error is translated into a SOAP fault that is then returned to the Supplier.

6.1.3.1.2.2. Asynchronous invoice processing

The time consuming operations for processing the invoices are done asynchronously by the Supplier Integration bus. As stated before the Synchronous processing of the invoice ends when the system sends the incoming message to the jmsDocumentOut message Channel which places the message in the documentQueue JMS Queue.

The JMS Adapter to document queue sends the messages to the JMS document in channel:

Figure 15: Asynchronous Invoice Processing

All the message types supported by Open e-PRIOR are posted to the documentQueue. It's the responsibility of the ePriorHeaderValueRouter to route the messages to the appropriate channel according to their type.

6.1.3.1.2.2.1. Invoice Validation service activator

This service activator validates the incoming invoice against the UBL 2.0 invoice schema. If the validation fails the system generates an Application response containing the validation errors. This Application response message is sent to the process manager for later processing.

6.1.3.1.2.2.2. Invoice Schematron validation service activator

This service activator performs the business validation of the UBL invoice which is done by validating it against a set of schematron rules. The schematron [REF9] validation rules are stored in the system as an XSLT transformation that is applied to the UBL Invoice document. If the validation produces warnings, these warnings are stored in the message and the message is passed to the next element in the message handler chain.

In case of Schematron errors, the system generates an Application Response message that is sent to the process manager for later processing.

6.1.3.1.2.2.3. Invoice Canonical Transformer Service Activator

In order to shield the process manager from changes in the format of the Invoice and to have the possibility to support different standards for the incoming documents without having to change to the process manager we use the Canonical format.

Open e-PRIOR applies a transformation to the incoming documents and the outcome of the transformation in the Canonical format is for the moment an XML message containing the UBL invoice plus some extra information.

If an error occurs this service activator creates an Application response message containing the error description that is sent to the process manager.

 <int:channel id="jmsDocumentOut" />  <int:channel id="jmsDocumentIn" />  <jms:outbound-channel-adapter id="jmsDocumentOutAdapter" jms-template="jmsTemplate" channel="jmsDocumentOut" />  <jms:inbound-channel-adapter id="jmsDocumentInAdapter" jms-template="jmsTemplate" channel="jmsDocumentIn" extract-payload="false"> <int:poller> <int:interval-trigger interval="3000" /> </int:poller> </jms:inbound-channel-adapter>  <int:router input-channel="jmsDocumentIn" ref="ePRIORHeaderValueRouter" method="route"/>


The service activator sends the message to the processQueue which is the entry point of the Open e-PRIOR Process Manager.

6.1.3.1.3. Submit Invoice in the Process Manager

The Process Manager is used to orchestrate the different service calls to the Customer Back Office. The Process Manager also holds the state machine of the different documents. The Process Manager is implemented using JBoss JBPM 4 [REF11] Business Process Manager and is packaged as a separate web application. This application also uses the Spring Integration framework to read messages posted in the processQueue jms entry point of the Process Manager. These incoming messages are routed to the appropriate message channel according to their types.

In the case of submit invoice, messages are routed to the jmsInvoiceProcessChannel that calls the jbpm Process engine to start an instance of the phase2a_SubmitInvoice process.

The JBPM process manager is configured to share its Spring application context with the one of the Process Web Application.With this configuration all the JBPM activities are defined as "Spring beans" which can benefit of the Spring framework transaction management and Dependency Injection capabilities:

Figure 16: Submit Invoice in the Process Manager

This configuration also allows avoiding having to deploy the classes containing the business logic accessed by the JBPM Process Engine as a separate JAR file on the JBoss Application Server.

<bean id="jbpmConfiguration" class="org.jbpm.pvm.internal.cfg.SpringConfiguration" > <constructor-arg value="eu/cec/openeprior/process/jbpm.cfg.xml" /> </bean> <bean id="processEngine" factory-bean="jbpmConfiguration" factory-method="buildProcessEngine" lazy-init="true" /> <bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" lazy-init="true"/> <bean id="executionService" factory-bean="processEngine" factory-method="getExecutionService" lazy-init="true"/>


6.1.3.1.3.1. phase2a_SubmitInvoice process

Figure 17: phase2a_SubmitInvoice Process


6.1.3.1.3.1.1. logInfo Activity

This a generic activity called by JBPM processes to log information. Open e-PRIOR use a simple log4J logger but Customers might be willing to implement their own auditing mechanism.

This is a simple JBPM java activity. The underlying LogActivity class is a POJO called by the process engine to log information:

Figure 18: logInfo Activity

The expr="#{logActivity}" attribute in the java element refers to a bean present in the spring application context. The method attribute refers to the method that must be called on the logActivity bean. This method is called by the Process engine with the arguments specified in the list of arg elements.

6.1.3.1.3.1.2. Repository Activity

This is a custom JBPM activity. Custom activities are Java classes that implement the ActivityBehaviour interface. By implementing this interface the custom activities can access the Process Execution context and are able to create and modify several process variables.

Java Activities can create or modify only one process variable at a time by specifying the var attribute in the java element. By doing so the Process Manager will assign the return value of the method execution to a Process variable of the name specified in the var attribute.

This is a generic activity called by JBPM Processes to get messages from the Open e-PRIOR database. In order to avoid sending large messages to the Process Layer Input queue, the Integration layer stores the incoming message to the database and just sends the message ID to the Process Layer . This activity gets the repository message with its ID and passes the result as JBPM process Variable.

Figure 19: Repository Activity

6.1.3.1.3.1.3. IsApplicationResponse Activity

This a common activity called by JBPM processes to check if messages coming from the Open e-PRIOR Supplier Integration Bus are Application Responses. The Supplier Integration Bus sends Application Response Messages to the Process Manager in case of errors (xsd or schematron validation ) that occurred during the asynchronous processing of the document. The result of this check is set as a Process variable which is used afterwards to branch the Process.

<java expr="#{logActivity}" g="220,85,92,52" method="logInfo" name="logInfo"> <arg><object expr="#{agreement}"/></arg> <arg><object expr="#{message}"/></arg> <arg><object expr="#{END_POINT_ID}"/></arg> <arg><object expr="#{PHRASE_ID}"/></arg> <arg><string value="Start asynchronous submit invoice instance"/></arg> <transition g="10,-10" name="to RepositoryActivity" to="RepositoryActivity"/> </java>

<custom expr="#{repositoryActivity}" g="212,161,108,52" name="RepositoryActivity"> <transition g="12,-13" name="to isApplicationResponseActivity" to="isApplicationResponseActivity"/>

</custom>


6.1.3.1.3.1.4. saveError Activity

This a common activity called by JBPM processes to handle errors. In this specific case errors mean that the Supplier Integration Bus sends an Application Response to the process layer instead of a valid document (Invoice CreditNote ...). This java activity creates an Error Application Response message in the Open e-PRIOR database that will be available in the Supplier Inbox or via SatusRequest call.

6.1.3.1.3.1.5. completeError Activity

This Activity updates the process state to "completed" in case of error.

6.1.3.1.3.1.6. castInvoice Activity

This java Activity casts the Generic repository message to an InvoiceReceivedDocument which is the XML Bean representation of the InvoiceDocument canonical format. The InvoiceReceivedDocument returned by this method call is set as a Process Variable by the Process engine.

6.1.3.1.3.1.7. Persist Activity

This Custom JBPM activity tries to save the received document in the Open e-PRIOR repository. It also checks the uniqueness of the document and passes the result of this check to the Process execution. This Activity also creates and saves the invoice human readable readable format.

6.1.3.1.3.1.8. invoiceAlreadyExistsActivity

If the submitted Invoice already exists in Open e-PRIOR this Java Activity will create an Error Application Response message in the Open e-PRIOR database and which message will be available in the Supplier Inbox or via the SatusRequest call.

6.1.3.1.3.1.9. sendMessageActivity

This generic activity sends messages to the JMS Inbound Queue of the Back Office. Customer Back Offices should read messages from that queue and process them. The outcome of this activity is that the process enters the waitForBackendState and waits for a Back Office reply.

6.1.3.1.3.1.10. logReception/ logReceivedInvoiceid

These two java activities log information when the Open e-PRIOR system receives a response from the Back Office.

6.1.3.1.3.1.11. convertResponse Activity

This a common activity called by JBPM processes to convert messages coming from the Back Offices to Application Responses Documents.

6.1.3.1.3.1.12. invoiceResponseOk Activity

This is a common java activity that checks if the Invoice has been successfully processed by the Back Office.

6.1.3.1.3.1.13. saveInvoiceProcessedActivity

This Custom JBPM activity is called when the invoice have been successfully processed by the Customer Back Office. This activity saves the success message in the Open e-PRIOR internal repository.

6.1.3.1.3.1.14. saveInvoiceErrorActivity

This Custom JBPM activity is called when the Customer Back Office did not process the Invoice successfully. This activity saves the error in the Open e-PRIOR internal repository.


6.1.3.1.3.1.15. completeProcess Ativity

This a common Java activity called by JBPM processes to indicate that the processing of a specific document (invoice, credit note) is completed.

6.1.3.2. A Supplier requests the status of a document The status request service is a webservice provided by Open e-PRIOR that allows the Supplier to retrieve the status of a submitted document. This is a synchronous service and, as all other synchronous services provided to the Suppliers by the System, it is implemented in the Supplier Integration Bus.

This use case realization applies to all the synchronous services provided by Open e-PRIOR.

Status Request Endpoint

statusRequestRequestChannel

statusRequestResponseChannel


HeaderEnricher

Message IntegrityChecker

Message Internal Translator

ValidationService Activator

Status RequestService Activator

Message Internal Transformer

Figure 20: Status Request Use Case Realisation

6.1.3.2.1. Status Request Endpoint

Calls to the Status Request Web Service are routed to this endpoint. All the webservices endpoints of Open e-PRIOR are implemented in the same manner. The description of the Spring-WS Configuration, of the security realm, the content base routing mechanism and the OpenEPriorinboundGateway written in chapter 6.1.3.1.1.1.1 also applies for the Status Request endpoint.

This is the configuration of the Satus Request Endpoint:

Figure 21: Status Request Endpoint Configuration

The processing of the Status request message is handled by the following message handler chain:

Figure 22: Status Request Message Handler Chain

 <bean id="statusRequestEndpoint"

class="eu.cec.openeprior.esb.gateway.EPriorSoapInboundGateway"> <property name="requestChannel" ref="statusRequestRequestChannel" /> <property name="replyChannel" ref="statusRequestResponseChannel" /> </bean>

 <int:chain input-channel="statusRequestRequestChannel" output-channel= "statusRequestResponseChannel">  <int:header-enricher>

<int:header name="msgType" value="StatusRequest"/> <int:header name="responseRootElement" value="StatusResponse"/> <int:header name="operationType" value="SubmitStatusRequestRequest"/> <int:header name="endPointId" value="2"/> <int:header name="phraseId" value="58"/> </int:header-enricher > <int:service-activator ref="messageIntegrityChecker" method="checkMessageIntegrity" /> <int:transformer ref="messageTransformer" method="transformIncomingMessage" /> <int:service-activator ref="authorisationService" method="getSupplierAgreement" /> <int:service-activator ref="validationService" method="validateMessage" /> <int:service-activator ref="statusRequestService" method="requestSatus" /> <int:transformer ref="messageTransformer" method="transformOutgoingMessage" /> </int:chain>


6.1.3.2.2. Header Enricher

This message Enricher is used to add technical information to the Spring Integration Message header.

6.1.3.2.3. Message Integrity Checker

This service activator is used to check the integrity of the incoming messagesthrough checking that the incoming message contains only one document supported by the system.

6.1.3.2.4. Message Translator

This is a common message translator that transforms the incoming Soap Message payload to an OpenEpriorIncomingMessage. It extracts information from the original message and stores it into an object structure. It also transforms the XML payload of the Soap Message to an Apache XML Bean representation of the incoming UBL document.

6.1.3.2.5. Authorization service activator

This service uses the authorization information stored in the Open e-PRIOR database to check if the Supplier is authorized to request the status of the document specified in the Status Request Message. The Customer and Supplier GLN are specified in the SOAP Header of the incoming message.

6.1.3.2.6. Validation Service Activator

For the synchronous services the validation of the incoming message is done synchronously in the Supplier Integration Bus by the Validation Service Activator.

6.1.3.2.7. Status Request Service Activator

This Service Activator retrieves the status of the document from the Open e-PRIOR repository and builds a StatusResponse document from the result of the query.

6.1.3.2.8. Message Translator (for outgoing message)

This message translator transforms the outgoing message to a status request Web Service response.

6.1.3.2.9. Error handling

If an error occurs during the synchronous processing of the invoice an exception is thrown. The exception is caught by the EPriorSoapInboundGateway that transforms it into a Soap Fault.

6.1.3.3. A Customer submits an order The submit order service is a service (via JMS queue) provided by Open e-PRIOR that allows the Customer to submit an Order to the Supplier. This is an asynchronous service and it's implemented using the Service Bus Layer and Process Manager Layer.

When a Customer submits an Order using the backend JMS queue, the document is read by the Service Bus and transformed into the Service Bus internal format. The document is then checked by a router, which decides the correct service to dispatch the message to, and puts it into the appropriate message channel.

Then the authorisation for the Customer is checked on the Database (whether a Customer Agreement is present, and whether the Customer has the right to send a document).

If the authorization succeds, the Order is checked against the validation rules (XSD for XML format, and schematron file for hard business rules), and, if no fatal errors are raised, it is transformed in the Canonical Model.

The valid Order is then submitted via a JMS Queue to the Process Manager layer, which stores it into the database, ready to be retrieved by the Supplier via the synchronous services.

The Process Manager layer is also in charge of submitting, if required, the Order document to the PEPPOL Access Point, to reach the Supplier via the PEPPOL infrastructure.

6.1.3.3.1. Submit Order in the Service Bus

The Service Bus is used as the entry point for the incoming Order document from the backend. It performs all the required authorisation and validation checks, and trasforms the message into the Open e-PRIOR internal format.

All the core service activators are grouped inside an integration chain, whose output is sent to the Process Manager for further processing (see section 6.1.3.3.2).

 <int:chain input-channel="orderFromBOChannel" >  <int:header-enricher> <int:header name="msgType" value="Order"/>

<int:header name="operationType" value="SubmitOrderRequest"/> <int:header name="endPointId" value="0"/> <int:header name="phraseId" value="83"/> <int:header name="profile" value="2"/> <int:header name="MSG_TYPE" value="Phase2a_Order"/> </int:header-enricher > <int:transformer ref="OpenEPriorBackendMessageTransformer" method="transform" /> <int:service-activator ref="backendMessageIntegrityChecker" method="checkMessageIntegrity" /> <int:service-activator ref="authorisationService" method="getCustomerAgreement" /> <int:service-activator ref="authorisationService" method="getAgreementForWrite" /> <int:service-activator ref="orderValidationService" method="asynchValidateMessage" /> <int:service-activator ref="orderSchematronService"/> <int:service-activator ref="orderCanonicalTransformerService" /> </int:chain>

Figure 23: Submit Order Message Handler Chain

6.1.3.3.1.1. JMS Message Converter

Once a message is dequeued from the backend queue, it is processed by the message converter, which extacts the JMS payload and put it into a String object. This object will be used afterwards to create the xml payload of the OpenEPriorIncomingMessage.

6.1.3.3.1.2. JMS Header Mapper

The JMS Header Mapper extracts the JMS Headers from the JMS message, and builds a Map of properties which will be added to the OpenEPriorIncomingMessage. In detail, the following headers are created:

• Jms Correlation ID: the correlation ID of the JMS message

• Message Date: the reception date of the message (it is set as the current date)

• Message User: the backend user who logged into the system

• Message Backend Name: the name of the Backend which the message is received from. It is taken from the Database starting from the User name.

• Channel Type: the type of the interface by which the message has been received. It is set as "backendJMS".

6.1.3.3.1.3. Backend Message Router  <bean id="fromBackendJmsRouter" class="eu.cec.openeprior.esb.message.XMLTypeRouter"> <property name="channelMap"> <map> <entry key="urn:oasis:names:specification:ubl:schema:xsd:Order-2:Order" value-ref="orderFromBOChannel"/> </map> </property> </bean>

Figure 24: Spring Backend Message Router

The xml message payload root is checked by the Message Router, which finds the correct channel to dispatch the message to. If the message is an Order (i.e., the root name and namespace of the document correspond to the Order ones), the message is put into the "Order from Back Office" channel. An integration chain is listening on that channel. The services of the chain are the ones described in the next subsections.

6.1.3.3.1.4. Header Enricher


The Header Enricher is the first step of the Order integration chain, which adds technical and security headers to the message before activating the first service of the chain itself.

6.1.3.3.1.5. Message Translator

This is a common message translator that transforms the incoming JMS message payload to an OpenEpriorIncomingMessage. It extracts information from the original message and stores it into an object structure. It also transforms the XML payload of the JMS Message to an Apache XMLBeans representation of the incoming UBL Order.

6.1.3.3.1.6. Authorisation Service Activator

The Authorisation Service checks if the Customer has the rights to post a message to Open e-PRIOR, by querying the information in the Open e-PRIOR internal Database . Two different authorisation checks are performed by this Service:

• Customer Agreement: checks if the couple User/CustomerID exists as a Customer Agreement in the Database.

• Agreement for Write: checks if the couple User/CustomerID has the rights to submit an Order to the given Supplier.

6.1.3.3.1.7. Order Validation Service Activator

The Order Validation Service checks the incoming XML message against the XSD schema file. This task is performed using XMLBeans validation features.

If the incoming document doesn't pass the validation, an Application Response reporting the error is created and sent Process Manager Layer for later processing.

6.1.3.3.1.8. Order Schematron Validation Service Activator

The Order Schematron Validation Service checks the incoming XML message against the Schematron [REF9] business rules file. This task is accomplished by performing an XSLT transformation deriving from the Schematron file itself.

If hard business rules are violated by the incoming document, an Application Response reporting the error(s) is created ans sent to the Process Manager Layer for later processing.

6.1.3.3.1.9. Order Canonical Transformation Service Activator

Open e-PRIOR applies a transformation to the incoming documents and the outcome of the transformation in the Canonical format is for the moment an XML message containing the UBL invoice plus some extra information.

If an error occurs this service activator creates an Application response message containing the error description that is sent to the process manager.

6.1.3.3.2. Submit Order in the Process Manager

The Submit Order Process is used by Open e-PRIOR to persist the Order (or the Application Response) coming from the Service Bus in the internal Open e-PRIOR database.


Figure 25: phase2a_SubmitOrder Process


First, the incoming message is checked to see if it is an Application Response. The Service Bus sends Application Responses to the Process Manager if an error has occurred during the validation or the canonical transformation of the Order.

If the incoming message is an Application Resposne, the error is persisted in the database.

If the message is an Order, the message is persisted, and a check is performed to see if the document ID already existed. If so, an Application Response containing the error is created and inserted in the database. If not, the document is then ready to be retrieved by the Supplier using the Open e-PRIOR synchronous services.

After the document persistence into the Database the PEPPOL flag is checked, in order to decide if, according to the current interchange agreement, the Order document should be sent to the PEPPOL Access Point. In case of a positive decision, an activity takes charge of accomplishing this task.

A diagram showing the Submit Order Process is shown in the previous page.

The details of each activity are explained in the next sections.

6.1.3.3.2.1. Log info activity

This activity is used to log the event of the reception of the Order in the events table of Open e-PRIOR internal database.

6.1.3.3.2.2. Repository activity

This activity retrieves the XML message from the the Open e-PRIOR repository table where it has been stored by the Service Bus Layer. Indeed, the Service Bus sends just the repository ID of the message to the Process Manager inbound queue. The full XML message is retrieved by this activity by querying the repository using the given ID.

6.1.3.3.2.3. IsApplicationResponse Activity

This activity checks whether the retrived message is or not an application response, by checking the root of the XML message. A process variable is set by this activity, which is read and used by the subsequent decision point.

6.1.3.3.2.4. Cast Order Activity

This activity transforms the plain XML message read from the repository into an Apache XMLBeans object. The XMLBeans object is then set as a process variable which will be used by the subsequent activities.

6.1.3.3.2.5. Persist Activity

This activity persists the Order in the Open e-PRIOR internal Database. It also checks if the ID of the document already exists. If so, a process variable ("idAlreadyExists") is set, which will be read by the subsequent decision point.

6.1.3.3.2.6. Order Already Exists Activity

This activity is called when the ID of the Order that should have been persisted by the Persist Activity already existed in the Database. This activity creates an Application Response reporting the error, and saves it in the internal database.

6.1.3.3.2.7. Send To Peppol Access Point Activity

This activity is called only if the PEPPOL flag for the current interchange agreement is set to "Y". In this case, a JMS message is created (containing the Order and the PEPPOL headers), and sent to the queue connected to the Access Point. The Access Point will then take charge of sending the message to the remote supplier via the PEPPOL infrastructure.

6.1.3.3.2.8. Save Error Activity


This activity is called when an Application Response is coming from the Service Bus (i.e. an error has been found in the Integration Layer). The activity takes charge of persisting the error in the database for later processing.

6.1.3.3.2.9. Complete Error Activity

This activity "completes" an error previously saved in the database by setting the status of the message in the repository to "Processed".

6.1.4. Main Interactions between Suppliers and Customers The following sequence diagrams describe the main possible interactions between Suppliers and Customers at a high level abstract view.

Submit from Supplier

Supplier : <Actor Name>

Customer : <Actor Name>Submit Document

Acknowledge Submit

Work (long)

Get

Response

Submit from Supplier

Figure 26: Submit from Supplier

Submit from Customer


Customer : <Actor Name>


Submit Document

Acknowledge Submit

Work

Send Response

Acknowledge

Submit from Customer

Figure 27: Submit from Customer

Business notification

Customer : <Actor Name>


Work

Get

Response

Business Notification

Figure 28: Business Notification

7. DEPLOYMENT VIEW

The following is a description of the hardware nodes running the Execution Environment for the system.


The following diagram, a UML deployment diagram, provides a view of hardware components involved in this project.

Figure 29: System Hardware Components

It is important to note that not all physical nodes are represented on this diagram. Indeed Database Servers and Application Servers could be duplicated for scalability and availability reasons. Moreover, security equipments like firewalls are not shown.


The following are the identified hardware nodes.

Front-end side:

• Supplier Client Application: Supplier client application of Open e-PRIOR;

• Supplier Access point: the PEPPOL network acces point used by the Supplier to submit documents.

Business side:

• System Application Server: The whole e-PRIOR System can run on a JBoss Application Server but clustering is possible.

• System Database Servers: the system's persistent data will be recorded in relational databases. The current version of Open e-PRIOR uses HSQL JBoss embedded database but scripts and installation guide to migrate to oracle are available.

Back-Office side:

• Back-Office Servers: These are the Customer's Back Office Application Servers.

8. IMPLEMENTATION VIEW

8.1. Overview

Following is a diagram that describes the software layers of the system and their components coupled with an explanation of each element. This is described through a short overview of typical system behaviour when a Supplier sends an invoice.

Suppliers access the system through the Supplier Service Bus Layer which realizes security checks, information structure validation, logging and executes a call to the Process Manager Layer by sending a message on a JMS queue.

The Process Manager reads the queue and starts a new Submit Invoice process instance which orchestrates calls to Backend and realizes tasks like logging and some validations.

Communications with Backend are handled by Business Services that listen on given JMS queue. The Process Manager sends messages on an output queue and Business Services reply on an input queue. The communication is totally asynchronous because some processing could take several days to achieve.


Figure 30: System Software Layers and Components


8.2. Layers

8.2.1. PEPPOL Acces Point Layer

8.2.1.1. PEPPOL Access Point Web Service: The PEPPOL Access Point Web Service is the entry point of the messages coming from other Access Points over the internet. The service is built with Java Metro 2.0 [REF28], a Web Service framework built on top of JAX-WS [REF29] specification. Therefore, the Application Server on which the service is deployed must support Java Metro 2.0.

The service is compliant with START profile specifications. All the following features are supported:

• WS-Addressing

• WS-Reliability

• WS-Security

• SAML 2.0 Tokens

• WS-Transfer

Following the JAX-WS standard, the service is implemented as a servlet, which is mapped to an instance of a com.sun.xml.ws.transport.http.servlet.WSServlet class.

Here is the definition of the servlet inside the web.xml file of the Web Application: <servlet>

<servlet-name>accesspointService</servlet-name>

<servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet

</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>accesspointService</servlet-name>

<url-pattern>/accesspointService</url-pattern>

</servlet-mapping>

Figure 31: PEPPOL Access Point Web Application Servlet

The actual implementation class of the Web Service is mapped to the Servlet Class using the JAX-WS file sun-jaxws.xml: <endpoints version="2.0" xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime">

<endpoint implementation="org.busdox.transport.start.server.AccesspointService"

name="accesspointService" url-pattern="/accesspointService" />

</endpoints>

Figure 32: PEPPOL Access Point Web Service and Servlet Mapping


Metro 2.0 stack is able to configure all the reliability and security requirements of a Web Service using a WS-Policy xml document [REF24] attached to the Service Contract (WSDL) of the service. The WS-Policy is used at runtime to check if all the requirements needed to access the service are met by the incoming message.

In detail, the following requirements are specified in the WS-Policy:

• WS-Addressing: <wsa:To>, <wsa:Action>, <wsa:ReplyTo> and <wsa:MessageID> headers must be included in the SOAP header of the message;

• WS-ReliableMessaging: a WS-RM sequence must be initiated before sending the actual message to the Access Point. The sequence must be terminated after document posting;

• WS-Security: see section [REF18] for security requirements.

A SOAP-fault is returned to the client if the incoming message is not compliant with the Web Service Policy.

When a document is sent to the Access Point, the SOAP body of the message must be a WS-Transfer Create Request (<wst:Create>). The Create Request XML must include as first child the document which has to be sent to the Access Point.

After performing an inbound message check, the service takes care of translating the message's SOAP Body and Header into Java Classes (Metro uses JAXB libraries to perform this operation), which are passed as parameters to the PEPPOL Access Point Session Bean described in the next section.

8.2.1.2. Access Point Session Bean: The PEPPOL Access Point Session Bean is the central component of the implementation.

It is an EJB 3.0 [REF12] which reuses the source code of the PEPPOL Access Point Reference Implementation 1.0.1. The Session Bean is used both for incoming and outgoing messages. In the first case, the messages are coming from the Supplier via the Web Service Gateway. In the latter, the source is Open e-PRIOR, and the message are coming from the Outbound Message Listener Message Driven Bean .The main purpose of the component is to query the Service Metadata Publisher (SMP) in order to find the destination of the message and to route it accordingly. PEPPOL SMP client libraries are used by the Bean to create a REST query to the SMP.

When a message is submitted to the bean, through the call of the create(..) method, the behaviour is as follows:

• If the message is a Ping Request (a PEPPOL defined message to check the availability of an Access Point), a Ping Response is returned as response to the Caller.

• If the message is not a Ping Request, a query to the SMP containing the Business ID of the recipient, the Document ID and the Process ID is submitted to the SMP.

• If the SMP returns an error (for example no metadata has been found for the given Recipient ID), an exception is raised. If the EJB has been called by the Web Service Gateway, the exception generates a SOAP-fault which is returned to the Caller.

• If the SMP returns a correct response (the Recipient Access Point Address) the system checks if the Recipient Access Point Address is the same as the local one. In this case the message is routed to Open e-PRIOR through the Integration Bean that will send a <wst:Create> response back to the client if everything goes fine. If the message cannot be stored in the database a message storing exception is thrown and a SOAP Fault is returned to the Caller.


• If the Recipient Access Point Address is different from the local one, the message is forwarded to the destination Access Point, by using PEPPOL START Profile Client Libraries.

8.2.1.3. PEPPOL / Open e-PRIOR Integration Session Bean This PEPPOL Open e-PRIOR session bean is the component called to forward a message coming from the Web Service Gateway to Open e-PRIOR.

Two main operations are provided by this Bean, which are called sequentially by the PEPPOL Access Point Bean :

• Store message: the Bean stores the received message into the PEPPOL Access Point Database by using the Data Access Object. PEPPOL messages (headers and payload) are transformed into Data Transfer Objects classes before calling the DAO. All incoming messages have to be stored inside a local database before being sent to Open e-PRIOR.

This implements the actual "resource creation" of WS-Transfer Create Operation. If the insertion into the database table ends with success, the creation of the resource can be considered as successful, and the Client Bean can return a WS-Transfer acknowledgment to the Web Service Gateway Client. Otherwise, an exception will be raised, and a SOAP Fault is returned to the Gateway Client.

• Forward the message to Open e-PRIOR: by using a Java JMS client, the Session Bean forwards the message to Open e-PRIOR JMSInterface queue. Before inserting the message into the queue, the Bean transforms it into a JMS message, by translating PEPPOL message headers (Business IDs, DocumentID, ProcessID, etc.) into JMS headers. Exceptions raised during this operation will not cause Soap-Fault to be generated and returned to client.

8.2.1.4. PEPPOL Access Point Message DAO PEPPOL Access Point Message DAO is the component in charge of storing PEPPOL messages inside the local Access Point database. The DAO stores the following information, coming from the PEPPOL message payload and headers:

• Message ID

• Sender ID

• Recipient ID

• Document Type ID

• Process Type ID

• XML content of the actual document

• Message direction (Inbound/Outbound)

• Message status

Exceptions generated by the DAO are rethrown to the caller, in order to wrap them into high level exceptions (Message Storing Exception).


8.2.1.5. Open e-PRIOR Outbound Message Listener MDB This Message Driven Bean is the interface towards Open e-PRIOR for outbound messages, i.e. messages coming from Customer's Back Offices which need to be sent to Suppliers via the PEPPOL network. The Bean is a subscriber of the JMSInterface Outbound Queue, into which the Open e-PRIOR Service Bus inserts the documents to be sent to the Access Point.

When a document is inserted into the queue:

• The MDB reads the JMS message from the queue.

• The JMS message is translated into a DTO message and sent to the DAO for persistence.

• The JMS message is translated into a PEPPOL message (body and metadata) using a helper class.

• The PEPPOL Access Point Session Bean is called to send the message to the AP.

• The PEPPOL Access Point Session Bean will then call the SMP and forward the message to the correct destination.

8.2.2. Service Bus Layer This layer is running on JBoss Application Server. It uses the Spring Integration Framework.

Open e-PRIOR Services: these services are Web Services published on the Supplier Integration Bus and are implemented using the Spring Web Service Framework.

Internal Queue: this queue allows the asynchronize message processing for resources consuming tasks like validation and transformation.

WSDL Document: the xml definition of the provided Web services.

CEN-BII schemas: these documents define format for XML documents. They will be used to validate XML information received from Suppliers. They are XSD documents.

Schematron Documents: these documents describe syntax rules for XML documents sent by Suppliers. They are XSLT (XML) documents.

JMS Interface Queue: The JMS queue used as an interface between Open e-PRIOR and the PEPPOL Access Point.

Message Channels: "Message Channel is a logical channel in a messaging system. They are used to sort the incoming messages into different message types." (from [REF5]) Open e-PRIOR uses different channels for Invoices, CreditNotes etc. Channels are configured via the Spring Integration framework.

Channel Adapters: "The adapter acts as a messaging client to the messaging system and invokes applications functions via an application-supplied interface" (from [REF5]). Open e-PRIOR uses Channel adapters to send message to JMS queues or to read messages from them.

Message Translators: Message translators are used to transform incoming external messages to internal Open e-PRIOR messages and vice versa.

Message Routers: "Message routers are special filter which consumes a Message from one Message Channel and republishes it to a different Message Channel channel depending on a set of conditions" (from [REF5]) . Used to route documents to the appropriate channel according to their types.

Service Activators: "Service Activator connects the messages on the channel to the service being accessed" (from [REF5]). These are usually simple method calls to Spring configured POJO's.

Canonical schemas: XSD documents defining canonical XML format. This internal format is based on UBL and is used to shield the system from multiple evolutions of the incoming


formats. This intermediary format should indeed evolve much slowly than the incoming formats (CEN-BII).

8.2.3. Process Manager Layer This layer is running on a Jboss server with JBPM installed. The Process layer also uses Spring Integration to receive and route messages coming from the Supplier Integration Bus to the appropriate Process Layer Message Channel. The same pattern is applied for messages coming from the Customer Integration Layer or from the Customer Back Offices.

JMS Process Queue: This is the Entry Point of JMS queues for both the Supplier and Customer integration layers.

Document Processes : These are a set of JBPM processes that orchestrates the services calls. It also logs information, saves the process state, etc. They are described using the BPMN [REF28] notation and are designed using the JBPM designer tool. It is important to note that communications with Back Offices are handled through JMS queues and so correlation IDs are used to correlate a request with its response.

Document Output Queue: this queue is a JMS queue configured on JBOSS server. It is used to send messages to the Customer Back Offices.

Document Input Queue: this queue is a JMS queue configured on JBOSS server. It is used to receive messages from the Customer Back Offices.

8.2.4. Customer Integration Layer This layer is running on a JBOSS Server. This layer is the mirror image of the Supplier Integration Layer and is meant to provide services to the Customers.

It uses the same components and artefacts that the Supplier Integration Layer so the description of the Supplier Integration Layer described in Chapter 9.2.1 also applies to this layer. The main difference is that services published in this layer are only Web Services and they cannot be accessed via the PEPPOL network.


9. DATA VIEW

9.1. Data Model

The following diagram shows a high level abstraction of the data classes which must be implemented by the system:

Profile

idnamesource

(from Data Model)

State

idname

(from Data Model)

User

idnamepasswordeMailAddress

(from Data Model)

BackEnd

idfunctionalityCodenameuserNameuserPassword

(from Data Model)

InterchangeAgreement

supplierAgreementIdintDeptIdprofileId

(from Data Model)

+supports

Functionality

codephraseId

(from Data Model)

+manages

Support

profileIdobjectTypeCode

(from Data Model)+for

LogLevel

interchangeAgreementIdendPointIdeventLevelCode

(from Data Model)

+is set for

Translation

phraseIdlangIdvalue

(from Data Model)

Statement

codephraseId

(from Data Model)

EventLevel

idphraseId

(from Data Model)

+is set to

Language

idphraseId

(from Data Model)

+in

ObjectType

codephraseIdfunctionalityCode

(from Data Model)

+plays a role in

+of

EndPoint

idserviceIdversion

(from Data Model)

+is set for

Service

idphraseId

(from Data Model)

+is a version of

Supplier

idnameeanCodelegalEntityIdlanguageId

(from Data Model) +understands

Object

idobjectTypeobjectIdmessageIdcorrelationId

(from Data Model)

+references

+has

Event

messageIddateeventTypecontents

(from Data Model)

+has

MessageType

idphraseIdobjectTypeCodeorderNumberstateIdcodeListId

(from Data Model)

+sets object to

+belongs to

SupplierAgreement

supplierIduserIdprofileId

(from Data Model)

+can send on behalf

+delegates

+is involved in

InternalDepartment

ideanCodenameorganisation

(from Data Model)

nn

+uses

{An InternalDepartment can have 0 or 1 BackEnd for each Functionality}

+is involved in

+understands

Binary

idcontents

(from Data Model)

Phrase

iddefaultValue

(from Data Model)

+means

+says

+is named

+is named

+is named

+is named

Message

idobjectIdsupplierIdagreementIdintDeptIdinOutFlrawContentscanonicalContentshumanReadableContentsmessageTypeIdissueDatereceiptDatedocumentIdreadFlphraseIdbinaryIdmessageId

(from Data Model)

+to

+belongs to

+references

+about

+has

+from

{A Message will hav e either an agreementId (inbound) or a supplierId

(outbound)}

+from or to+belongs to

+is title of

+references

Figure 33: Open e-PRIOR Data Model

The Supplier entity represents the companies which will send messages or on behalf of which messages will be sent. The User entity represents the users who will connect to the system to send the messages. If a Supplier works directly with the system, a User entry will also be needed for it. If a Supplier uses a third-party to send documents (a factoring company for the invoices, for example), then it will be linked to the User entry which identifies the third-party. The third-party itself will not need a Supplier entry. The link between a Supplier and a User is implemented by the SupplierAgreement entity. A Supplier can be linked to more than one User, for example a factoring company for its invoices and its own User for other documents.

The BackEnd entity represents an application implementing functionality for an Internal Department. Its userName is the system user name which the Back Office will use to call Open e-PRIOR Services.


The Functionality entity represents the possible functionalities of a BackEnd: invoicing, ordering, archiving, requesting etc. An InternalDepartment should have one Back Office per Functionality. A SupplierAgreement and an InternalDepartment sign an InterchangeAgreement, whereby they agree to exchange documents according to a given Profile.

The Profile entity is inspired by the CEN-BII [REF32] profiles, and will have 3 values for a start: Basic Invoice, Invoice with Dispute, and Procurement Cycle. A Profile is linked to an InterchangeAgreement.

The ObjectType entity represents all the types of objects supported by Open e-PRIOR (Invoice, Dispute, Credit Note, Attachment, Error). The Object entity represents a specific object of a given type, which will be handled by Open e-PRIOR via the sending of Messages. Optionally, it can reference a message from another object (e.g. a Credit Note object can reference an Invoice message from an Invoice object) or even a specific message in another object (e.g. an Attachment can reference any message of any object).

An ObjectType also relates to only one Functionality (for ex. the object types "Invoice", "Dispute" and "Credit Note" belong to the "invoicing" functionality, the object types "Initial Request" and "Extension Request" belong to the "request" functionality).

Its correlationId is the ID of the process instance which manages the object. The interface with the Back Office needs it in order to resume the workflow when it communicates information back to Open e-PRIOR, via an outgoing message.

The Support entity indicates which ObjectTypes are supported by a given Profile. For example, the 'Invoice with Dispute' Profile supports the Invoice, Dispute, Credit Note and Attachment object types.

The Message entity represents the messages which will transit through Open e-PRIOR. The inOutFl indicates whether it is an inbound message (from a Supplier system) or an outbound message (from the Customer Back Office). If it is an inbound message, then the sender is identified by a SupplierAgreement ID whereas if it is an outbound message, the destination is identified by the Supplier ID. In other words, a message can be sent by a User on behalf of the Supplier, but a reply will always be sent to the Supplier. The Message entity makes up the storage of the messages which will be subject to registration, filing and archiving. It contains a rawContents attribute which will receive the payload of the XML, and a canonicalContents attribute which will receive, when applicable, the canonical version of the XML. It also contains a humanReadableContents attribute, which will contain the result of the transformation of the XML to a format readable by a user.

A Message can reference another Message (via the messageId)including a Message from another Object.

Its phraseId will point to a phrase which will serve as title for the message. Its binaryId will point, if applicable, to binary which was removed from the message for size reason. Its documentId will be the ID found inside the payload.

The Binary entity will receive the binary data which can be inside a message. To avoid size problems, the binary data is removed from the message and placed here. The message then just contains a pointer to the Binary element.

A Message will have a type, implemented by the MessageType entity. Examples of message types are Invoice, Dispute, Credit Note, Signed Order. A MessageType is linked to an ObjectType, for example, the Dispute and Credit Note message types belong to the Dispute object type. A MessageType will also have a state, which corresponds to the state in which the related object will be when such a message is sent for the object. The states are implemented by the State entity. For example, the state of the MessageType "Credit Note" will be "Credit Note Received". This means that when a Credit Note is received for a specific


Dispute object, the Dispute object will receive the state "Credit Note Received". The State Machines below illustrate the different states of the different objects (as well as the links between objects and attachments).

The Event entity records every event occurring inside Open e-PRIOR. When the event concerns a Message, it holds a pointer to the Message. It implements the log file. The Event Level provides a list of levels for the events: debug, info, warning, error. The developers will associate an event level to each action performed by the system. If the level is at least the current level of the system, then the action will be recorded as an event. The current level is determined by the LogLevel entity, which associates an event level to a specific context: a specific InterchangeAgreeement using a specific EndPoint.

The Service entity implements the services of the system: "Submit Invoice", "Request Status", "View Document". An EndPoint is a specific version of a service and it corresponds to a WSDL.

The Statement entity contains sentences, error messages or any string used for the communication between the system and a Supplier.

The Phrase and Translation entities are linked to all entities containing an attribute whose value can be displayed on screen, and so contributes to the multilingual functionality, together with the Language entity.

The queues are not represented in this diagram.

9.2. State Machines

9.2.1. Introduction Each object of the system (Invoice, Dispute, Credit Note, Attachment etc.) will have its own state machine. A state machine can be initiated by a Supplier or by a Customer and it starts with a specific message (eg. "the Supplier sends an Invoice").

Only a message (inbound or outbound) will be capable of passing an object from a state to the next one. A state machine will never represent the workflow of the object in the Back Office. While the object is in the Back Office, the state of the object remains the same in Open e-PRIOR, until the Back Office notifies (via an outbound message) that the workflow is complete.

The following sections illustrate the state machines which have to be supported by Open e-PRIOR.

Notes:

• Once a state machine instance is started, each state transition is performed by the transmission of a message. Each message is subject to logging.

• Everytime an outbound message is sent, an e-mail notification is also sent to the Supplier via SMTP. This has no influence on the architecture because we do not use SMTP as a protocol for asynchronous communication, and will not be represented in the diagrams either.


9.2.2. Legend

Intermediary State

Entry point

Outgoing Message

Incoming Message

Final State

Figure 34: Legend

9.2.3. Generic State Machines

9.2.3.1. Generic State Machine for an Incoming Object Most of the incoming objects (documents received by the Back Office) will have the following state machine:

Received

Processed Rejected

Application Response

Application Response

Document

Figure 35: Generic State Machines

9.2.3.2. Generic State Machine for an Outgoing Object Most of the outgoing objects (documents sent by the Back Office) will have the following state machine:


Figure 36: Generic State Machine for an Outgoing Message

9.2.4. State Machines for Generic Objects

9.2.4.1. State Machine for an Attachment When an attachment is sent by the Back Office, it has the Generic State Machine for an Outgoing Object. When it is sent to the Back Office, it has the Generic State Machine for an Incoming Object.

9.2.4.2. State Machine for an Error An error can be sent at any moment by Open e-PRIOR to the Supplier when something is wrong with a received message and it cannot be linked to an existing object. Typically, the XSD validation could send such an Error.

An Error object has the Generic State Machine for an Outgoing Object.

Errors can only happen before a state machine starts. If something goes wrong after the object is identified (ie. after a state machine starts), then a message of type "Rejected", linked to the object, will be sent instead.

9.2.5. State Machines for the "Invoicing" Functionality

9.2.5.1. State Machine for an Invoice Parent object: None Potential attachments: Time sheet (Mulitple) State machine: Generic State Machine for an Incoming Object

9.2.5.2. State Machine for a Credit Note Parent object: Invoice Potential attachments: Time sheet (Multiple) State machine: Generic State Machine for an Incoming Object


9.3. Queries and Virtual Inbox

9.3.1. Queries The Supplier can query the system at any moment with the following parameters:

• Object type(s).

• Date range.

• State(s).

The system must respond with a structured answer containing at least the unique identifiers of the messages, and preferrably their state. In any case, for performance reason, it will not contain information coming from the Back-Office.

9.3.2. Virtual Inbox A predefined query will also be made available to the Supplier, with hard-coded values for the parameters, which is likely to become their default query, making sure that every message of interest for the Supplier is provided to him at least once. This implements a "Virtual Inbox". It will still be the responsibility of the Supplier to call it on a regular basis.

The implementation of a user interface for that Inbox will be one of the main tasks of the developers of any Supplier portal. The presentation of it can exploit the existing references from an object to another one in order to present in a logical order (for example an Order with all its Invoices under it, indented, and for each Invoice all its Attachments and Disputes under it, again indented).

9.3.3. Retrieval Once the Supplier has obtained the unique ID of a message, it can call the service of retrieval, in order to obtain the details of that message. In return, the service will provide all the details of the message, which might include information coming from the Back Office. It should also provide the list of objects which reference it.

The Inbox functionality of a Supplier Portal should also call the retrieval service in order to show the details of a message.

10. SIZE AND PERFORMANCE

10.1. Size

Size restrictions, not on the application or its components themselves, but on the data that is being processed by Open e-PRIOR, have an impact on the architecture and configuration of the system.

Due to constraints on the size of messages in the JMS queues, an AttachedDocument’s binary content will not be stored in a JMS queue. To accomplish this, the binary content will be carried in the SOAP header of a message while the AttachedDocument’s alphanumeric data will be carried within the SOAP message body. Once the SOAP envelope is received, the binary content will be persisted in a database table. The alphanumeric payload will be persisted in the JMS queue and further processed by the system.

10.2. Performance

An important architectural decision that benefits the performance of Open e-PRIOR includes the decoupling of the solution into a synchronous and an asynchronous mode of


communication. The synchronous mode of communication mode is used by services in which the business response is immediate and which requires limited processing. The asynchronous mode however is aimed at services whose processing involves a series of long-running business actions which often require workflow steps performed by the Back Office. In this mode, an incoming message will be stored in a queue where it waits to be picked up for further processing.

11. QUALITY

For a list of non-functional requirements or contraints that Open e-PRIOR implements, please refer to “3 Architectural Goals and Constraints”.

In addition to the items mentioned above, the architecture of Open e-PRIOR contributes to quality aspects of extensibility, reliability and portability in the following ways.

11.1. Extensibility

As indicated in “6.1.2 Architecturally Significant Design Packages” and “8 Implementation View”, Open e-PRIOR is designed in a layered fashion and consists in multiple interconnected modules. This modular design facilitates upgrades by replacing existing modules and extensions by adding additional modules.

11.2. Reliability

The reliability of Open e-PRIOR is enhanced through the decoupling of each architectural layer by JMS queues.

11.3. Portability

As well as being extensible, Open e-PRIOR is carefully designed in such a way that it is independent of the specific Back Office that it is serving. The custom logic for a Back Office is isolated in the back-office layer, leaving the front-end layer and business layer unaffected when an additional Back Office needs to be supported by Open e-PRIOR.


12. TEST INTERFACE SPECIFICATION

The majority of tests for Open e-PRIOR can be executed using the standard interfaces of the system without any additional requirements.

A minority of tests can also be executed using the standard interfaces, but need specific settings to be modified before or during the execution of the tests. These settings and the procedure to modify them are documented in an annex to the Test Management Plan (refer to [REF4]).

A single set of tests is more intrusive and requires special care. This set of tests verifies that the system can handle a lost connection with the user while he is consuming a service. The requirements for this particular scenario are that there should be a method to introduce a delay between a user request and the system response. This delay will allow a tester to break the connection and verify the behaviour of the system.

e-PRIOR Software Architecture Document · Open e-PRIOR Software Architecture Document – Page 5 /...

Documents

Transcript of e-PRIOR Software Architecture Document · Open e-PRIOR Software Architecture Document – Page 5 /...