Competitiveness and Innovation Framework Programme

COMPETITIVENESS AND INNOVATION FRAMEWORK PROGRAMME

ICT Policy Support Programme (ICT PSP)

ICT PSP call identifier: ICT PSP-2008-2

ICT PSP main Theme identifier: CIP-ICT-PSP.2008.1.1

Project acronym: SPOCS

Project full title: Simple Procedures Online for Cross-border Services

Grant agreement no.: 238935

eSafe document exchange protocol Open Module documentation
Integrating the eSafe Open Modules in the portal
applications and publishing the SPOCS functionalities
Deliverable Id : / D3.3
Deliverable Name : / eSafe document exchange protocol Open Module
Status : / Final
Dissemination Level : / SPOCS internal and EU Commission
Due date of deliverable : / 20.5.2011
Actual submission date : / 20.5.2011, Update V1.2.0 on 31.08.2012
Work Package : / WP3 Interoperable delivery, eSafe, secure and interoperable exchanges and
acknowledgement of receipt
Organisation name of lead contractor for this deliverable : / BVA (DE)
Author(s): / AtosIT Solutions and Services GmbH (DE)
Partner(s) contributing :
Abstract: This document offers a simple cookbook for integration activities.

History

Version / Date / Modification reason / Modified by
1.2.0 / 31.08.2011 / Release V1.2.0 / Peter Worofka
1.1.0 / 19.07.2011 / Additional descriptions regarding testing / Peter Worofka
1.1.0 / 15.07.2011 / Release V1.1.0 / Peter Worofka
1.0.0 / 20.05.2011 / Release V1.0.0 / Peter Worofka
0.92 / 12.04.2011 / Update V0.92 / Peter Worofka
0.9 / 14.02.2011 / Initial version / Peter Worofka

History

Table of contents

List of figures

List of Tables

List of Abbreviations

1Overview on the procedure for integration

1.1Integrate the delivered modules/libraries

1.2Extend and enable SPOCS functionality

1.3Initiate entry in TSL for the component

2Sources of documentation

2.1Design documents

2.2JavaDoc

2.3Source usage and system environment

3Testing the eSafe Open Modules

3.1So far preferred test environments

3.2JUnit Tests

3.3Studying and testing the integration with the demo portals

3.3.1Components of the PSCDemo Portal

3.3.2Components of the eSafeDemo Portal

3.3.3Starting the demo portals and testing the configuration

3.3.4Scenario test with the demo portals

3.3.5Stress test with the demo portals

4Testing the eSafe Open Modules addons

4.1Testing the PSC Client Web Services

4.2Testing the eSafe Client Web Services

5Test documentation

List of figures

Figure 1: A typical Sparx Enterprise Architect UML diagram

Figure 2: Demo Portal Home page

Figure 3: One of the Demo Portal’s About pages

Figure 4: Starting the demo scenario

Figure 5: Transferring documents from the demo eSafe to the demo PSC

Figure 6: The document transfer has finished

Figure 7: Ready to run the stress test

Figure 8: Stress test result

Figure 9: The PSC Module Container’s About/Portal integration page

Figure 10: Testing the PSC Module Container with soapUi

Figure 11: The eSafe Module Container’s About/Portal integration page

Figure 12: The .NET eSafe portal simulation instruction page

List of Tables

Table 1: Test protocols

List of Abbreviations

Abbreviation Explanation

SPOCSSimple Procedures Online for Cross-border Service

1Overview on the procedure for integration

1.1Integrate the delivered modules/libraries

Configure the basic module‘s settings, e.g.

Address of the TSL provider
portal‘s name
web site URL
certificates
folder for storing document transfer packages
maximum document transfer package size
transfer options (e.g. frame size)
timeouts, etc. (see module configuration files documentation for further details)

Register the portal’s UI entry points (URL templates) relevant to the
eSafe document exchange protocol in the Open Modules‘ configuration files
Include the module in the application startup procedure
Configure the server environment like SSL and firewall settings

1.2Extend and enable SPOCS functionality

Implement the SPOCS-specific UIs
Use the module‘s API (e.g. session object) for accessing the module‘s functionality
Implement the module‘s SPI (e.g. DocumentSelection) for

providing the relevant data (selection and provision of documents, metadata, etc.) and for
implementing optional hooks (e.g. event listeners) depending on the portal’s role (PSC or eSafe)

Publish the Open Module‘s web services (e.g. registering in
the portal’s web.xml)

1.3Initiate entry in TSL for the component

Each role (PSC, eSafe) needs to be included in the TSL
Resources required

Standard TSL attributes

Service name  should be unique, eg. qualified with the domain
Service digital identity  Trustworthy SSL Certificate
Service Supply point  URL of the InfoService WSDL

countryCode
document transfer principle (PUSH, PULL)
(note: delivered modules support and provide PUSH principle)

2Sources of documentation

The documentation provided to help the portals’ developers can be found in the Subversion repository folder SPWP3s_Documentation.

2.1Design documents

Figure 1: A typical Sparx Enterprise Architect UML diagram

One important item is the file ESafeDocx_Design.eap, which is an Sparx Enterprise Architect (UML 2.1) repository file, showing

the design of the eSafe document exchange protocol
and the design of the Open Modules implementation, including the communication that has to be implemented between a portal application and the eSafe Open Modules.

For the initial release (only) the Domain Objects descriptions and the Activity Diagrams have been exported as Word documents and shipped with the documentation as well. However, we strongly recommend the usage of Sparx Enterprise Architect.

A free Read-Only version can be downloaded from the Sparx Systems web site ( See < EA Lite is available for FREE to allow your entire team and clientele to view the progress of your projects, ensuring excellent communication and understanding between all involved. EA Lite supports all features except documentation output and "save".

2.2JavaDoc

The public API (Application Programming Interface) and SPI (Service Provider Interface) is attached as JavaDoc.

2.3Source usage and system environment

Although the effort was to create sources, configuration files and other artifacts that are (as much as possible) independent of the specific development environment and usage scenario some configuration files, server or Eclipse settings as well as helper scripts and other supplemental tools may need to be adapted to fit to your environment. The document “Source Usage and Configuration.doc” gives help on that topic.

Note: We expect that one thing or the other could be improved in usability. The team will be pleased to gain benefit from your feedback.

3Testingthe eSafe Open Modules

3.1So far preferred test environments

The current eSafe Open Modules have been developed and tested mainly using

Apache Tomcat 6.0.29
JBoss 5.1.0 GA

both using JDK 6.

3.2JUnit Tests

For automatic component and simple integration testing the sources include around 50 JUnit test classes organised into various categories by

Test suites – organised by functional areas (following java package clusters)
Test class hierarchies – organised by technical requirements (no configuration needed, running with the standard configuration, running with a special test configuration)

The eSafe Open Modules source code repository (subversion) contains various log files of recent JUnit test runs in the documentation section. Note that the exceptions that are recorded in the log files do not indicate test failures. They indicate constructed error situations that have been successfully caught.

As already mentioned, the Open Modules are provided together with a DemoPSC and a Demo eSafe package. These demo portals shall help the partners to understand the modules’ usage and help testing the own implemented SPOCS functionality using the one of the demo portals as a communication partner simulation.

3.3Studying and testing the integration with the demo portals

As discussed previously, the Open Modules are provided together with a demoPSC and a demo eSafe package. These demo portals shall help the partners to understand the modules’ usage and help testing the own implemented SPOCS functionality using the one of the demo portals as a communication partner simulation.

3.3.1Components of the PSCDemo Portal

The Demo PSC consists of the following artifacts:

The PSC Demo Portal (esafedocx-dpspocs-psc.war) hosting
The eSafe Open Module for PSCs (esafedocx-mdspocs-psc.jar)
The eSafe Open Module Core (esafedocx-omcore-jee.jar)
TSL libraries (WP3)
OCD libraries (WP2)
Other 3rd party libraries

The listed modules and libraries libraries (maybe with the exception of the 3rd party JSF libraries that are used for implementing the demo portal’s UI) would also be hosted in a “real” PSC.

3.3.2Components of the eSafeDemo Portal

The Demo eSafe consists of the following artifacts:

The eSafe Demo Portal (esafedocx-dpspocs-esafe.war) hosting
The eSafe Open Module for eSafes (esafedocx-mdspocs-esafe.jar)
The eSafe Open Module Core (esafedocx-omcore-jee.jar)
TSL libraries (WP3)
OCD libraries (WP2)
Other 3rd party libraries

The listed modules and libraries libraries (maybe with the exception of the 3rd party JSF libraries that are used for implementing the demo portal’s UI) would also be hosted in a “real” eSafe.

3.3.3Starting the demo portals and testing the configuration

Once your Eclipse IDE and your application server environment have been configured and all the projects have successfully been compiled the demo portals can be deployed and started. Using a local Eclipse development environment you should be able to enter the demo portals by browsing the URLs

PSC:

eSafe:

or an similar URL using the respective HTTP or HTTPS configured port.

Note: the hostname localhost.demosystem.eu is only needed when using the configuration files and certificates that have been included in the sources. This hostname requires an entry in the local hosts file pointing to your workstation IP address or to 127.0.0.1

The demo portals’ look and feel has been inspired by the official SPOCS web site. The PSC Demo Portal home page looks like this.

Figure 2:Demo Portal Home page

For not getting confused when the user is redirected to the eSafe Demo Portal during the demo application scenario the upper right corner shows the portal identifier.

The section “About Demo” provides some of the configuration information and gives also access to the system’s WSDL files.

Figure 3: One of the Demo Portal’s About pages

3.3.4Scenario test with the demo portals

The section “Demo” allows running a simple scenario including browsing eSafes of a given country, redirection to a specific eSafe, document selection and transfer of a set prepared documents and randomly created files.

Figure 4: Starting the demo scenario

Here you see the user has already been redirected to the eSafe and the selected documents are being transferred to the PSC.

Figure 5: Transferring documents from the demo eSafe to the demo PSC

While running the test the Eclipse console dumps all the log messages as configured in the module settings. Additionally the web page shows all the events that are reported by the Open Module through the SPI.

Finally, the demo ends with a page where you can inspect the transferred documents.

Figure 6: The document transfer has finished

Here you see the received document transfer package (an OCD container) and status parameter on the data transfer as well as the container integrity verification result (OK or an error code describing the highest error condition of all detected errors) and a more detailed verification report(XML document).

Note: Due to a bug in the OCD module (version 3.6.2) the container verification reports an error code if using signature certificates that are not explicitly marked for signing purposes (key usage digital signature). The implemented workaround filters out the error condition but keeps the error code in the detailed verification report (XML document).

3.3.5Stress test with the demo portals

The section “Stress Test Demo” allows running a multithreaded scenario with a random number of threads. In this case the demo eSafe always returns a fix set of documents.

Figure 7: Ready to run the stress test

While running the test the Eclipse console dumps all the log messages as configured in the module settings. Additionally, the web page shows all the events that are reported by the Open Module through the SPI. Note that the created load and the continuous refresh of the test status page may lead to log messages reporting that some Java Server Faces Events cannot be executed in time. This is due to the current simplicity of the stress test implementation.

Figure 8: Stress test result

4Testing the eSafe Open Modules addons

4.1Testing the PSC Client Web Services

For testing the PSC Client Web services the following artifacts have to built and deployed:

The PSC Module Container (esafedocx-mcspocs-addws-psc.war) hosting
The PSC Client Web services addon (esafedocx-mdspocs-addws-psc.jar)
The eSafe Open Module for PSCs (esafedocx-mdspocs-psc.jar)
The eSafe Open Module Core (esafedocx-omcore-jee.jar)
Any eSafe running the eSafe Open Module for eSafes (e.g. the eSafe Demo Portal)

Then basically, any application capable of reading and interpreting the PSC Module Container Client WSDL files can be used for scenario testing. You find a link to the concrete WSDL file by opening the PSC Module Container’s “About/Portal Integration” page.

Figure 9: The PSC Module Container’s About/Portal integration page

Using a local Eclipse development environment you should be able to enter the PSC Module Container by browsing the URL

PSC:

or an similar URL using the respective HTTP or HTTPS configured port.

In the SVN repository ESafeDocx_Mdcont_SPOCS_AddWS_PSC_JEE/src/test/soapui you also find a file with some simple soapUI scripts for

Testing the eSafe lookup
Doing a scenario test with the PSC Module Container and the eSafe Demo Portal
Doing a scenario test with the PSC Module Container and a .NET test application communicating via the eSafe Module Container (using the eSafe Client Web Services)

Figure 10: Testing the PSC Module Container with soapUi

Note: soapUI can be run standalone or integrated in Eclipse. We recommend to run the standalone version for easier editing and a better load separation.

4.2Testing the eSafe Client Web Services

For testing the eSafe Client Web services the following artifacts have to built and deployed:

The eSafe Module Container (esafedocx-mcspocs-addws-esafe.war) hosting
The eSafe Client Web services addon (esafedocx-mdspocs-addws-esafe.jar)
The eSafe Open Module for eSafes (esafedocx-mdspocs-esafe.jar)
The eSafe Open Module Core (esafedocx-omcore-jee.jar)
Any PSC running the eSafe Open Module for PSC (e.g. the PSC Demo Portal) or a PSC communicating via the PSC Module Container’s Client Web services (see above).

Then basically, any application capable of reading and interpreting the eSafe Module Container Client WSDL files can be used for scenario testing. You find a link to the concrete WSDL file by opening the eSafe Module Container’s “About/Portal Integration” page.

Figure 11: The eSafe Module Container’s About/Portal integration page

Using a local Eclipse development environment you should be able to enter the PSC Module Container by browsing the URL

eSafe:

or an similar URL using the respective HTTP or HTTPS configured port.

In the SVN repository ESafeDocx_Mdcont_SPOCS_AddWS_eSafe_CL-NETyou also find a .NET-based test application simulating a .NET-based eSafe portal as well as detailed test instructions.

Figure 12:The .NET eSafe portal simulation instruction page

5Test documentation

The eSafe Open Modules documentation tree in the SVN repository also contains a folder (currently WP_Documentation/Test) with a set of recorded tests that were run in preparation of the release. The folder’s structure and the contents may change from release to release. However, at the very moment the following items are included:

Group / Description
00-09 / Build protocol, building the whole software inside the Eclipse environment
11-20 / JUnit test protocol, testing the core libraries inside the Eclipse environment
21-30 / Stress test protocol, using the PSC demo portal’s stress test feature
31-40 / Testing the PSC’s and eSafe’s Client Web services addon
41-50 / Build protocol, building all demo portals and module containers with Maven, starting with an empty local repository, downloading the Open Modules and prerequisite elements from the SPOCS and 3rd party Maven repositories

Table 1: Test protocols