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 documentationIntegrating 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): / Atos IT Solutions and Services GmbH (DE)
Partner(s) contributing :
Abstract: This document offers a simple cookbook for integration activities.
History
Version / Date / Modification reason / Modified by1.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
Table of contents
History 2
Table of contents 2
List of figures 4
List of Tables 4
List of Abbreviations 4
1 Overview on the procedure for integration 5
1.1 Integrate the delivered modules/libraries 5
1.2 Extend and enable SPOCS functionality 5
1.3 Initiate entry in TSL for the component 5
2 Sources of documentation 7
2.1 Design documents 7
2.2 JavaDoc 8
2.3 Source usage and system environment 8
3 Testing the eSafe Open Modules 9
3.1 So far preferred test environments 9
3.2 JUnit Tests 9
3.3 Studying and testing the integration with the demo portals 9
3.3.1 Components of the PSC Demo Portal 9
3.3.2 Components of the eSafe Demo Portal 10
3.3.3 Starting the demo portals and testing the configuration 10
3.3.4 Scenario test with the demo portals 13
3.3.5 Stress test with the demo portals 16
4 Testing the eSafe Open Modules addons 18
4.1 Testing the PSC Client Web Services 18
4.2 Testing the eSafe Client Web Services 20
5 Test documentation 22
List of figures
Figure 1: A typical Sparx Enterprise Architect UML diagram 7
Figure 2: Demo Portal Home page 11
Figure 3: One of the Demo Portal’s About pages 12
Figure 4: Starting the demo scenario 13
Figure 5: Transferring documents from the demo eSafe to the demo PSC 14
Figure 6: The document transfer has finished 15
Figure 7: Ready to run the stress test 16
Figure 8: Stress test result 17
Figure 9: The PSC Module Container’s About/Portal integration page 18
Figure 10: Testing the PSC Module Container with soapUi 19
Figure 11: The eSafe Module Container’s About/Portal integration page 20
Figure 12: The .NET eSafe portal simulation instruction page 21
List of Tables
Table 1: Test protocols 22
List of Abbreviations
Abbreviation Explanation
SPOCS Simple Procedures Online for Cross-border Service
1 Overview on the procedure for integration
1.1 Integrate the delivered modules/libraries
1. 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)
2. Register the portal’s UI entry points (URL templates) relevant to the
eSafe document exchange protocol in the Open Modules‘ configuration files
3. Include the module in the application startup procedure
4. Configure the server environment like SSL and firewall settings
1.2 Extend and enable SPOCS functionality
5. Implement the SPOCS-specific UIs
6. Use the module‘s API (e.g. session object) for accessing the module‘s functionality
7. 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)
8. Publish the Open Module‘s web services (e.g. registering in
the portal’s web.xml)
1.3 Initiate entry in TSL for the component
9. Each role (PSC, eSafe) needs to be included in the TSL
10. 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)
2 Sources of documentation
The documentation provided to help the portals’ developers can be found in the Subversion repository folder SPWP3s_Documentation.
2.1 Design 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 (http://www.sparxsystems.com/bin/EALite.exe). See http://www.sparxsystems.eu/enterprisearchitect/ea-pricing-purchasing/: < 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.2 JavaDoc
The public API (Application Programming Interface) and SPI (Service Provider Interface) is attached as JavaDoc.
2.3 Source 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.
3 Testing the eSafe Open Modules
3.1 So 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.2 JUnit 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 Demo PSC 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 Studying and testing the integration with the demo portals
As discussed previously, the Open Modules are provided together with a demo PSC 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.1 Components of the PSC Demo Portal
The Demo PSC consists of the following artifacts:
· The PSC Demo Portal (esafedocx-dpspocs-psc.war) hosting
o The eSafe Open Module for PSCs (esafedocx-mdspocs-psc.jar)
o The eSafe Open Module Core (esafedocx-omcore-jee.jar)
o TSL libraries (WP3)
o OCD libraries (WP2)
o 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.2 Components of the eSafe Demo Portal
The Demo eSafe consists of the following artifacts:
· The eSafe Demo Portal (esafedocx-dpspocs-esafe.war) hosting
o The eSafe Open Module for eSafes (esafedocx-mdspocs-esafe.jar)
o The eSafe Open Module Core (esafedocx-omcore-jee.jar)
o TSL libraries (WP3)
o OCD libraries (WP2)
o 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.3 Starting 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: https://localhost.demosystem.eu:8081/ESafeDocx_Demo_Portal_SPOCS_PSC_JEE
eSafe: https://localhost.demosystem.eu:8081/ESafeDocx_Demo_Portal_SPOCS_eSafe_JEE
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.4 Scenario 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.5 Stress 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
4 Testing the eSafe Open Modules addons
4.1 Testing 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
o The PSC Client Web services addon (esafedocx-mdspocs-addws-psc.jar)
o The eSafe Open Module for PSCs (esafedocx-mdspocs-psc.jar)
o 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.