XCA Initiating Gateway Simulator - Developers' Guidelines

Click here to enter the XCA Initiating Gateway Simulator

 

The XCA Initiating Gateway Simulator has been developed to mimic the Initiating Gateway actor of the XCA (Cross Community Access) integration profile in connectathon (or pre-connectathon) tests when needed. This tool can participate as an initiator in many tests like XCA_Query_and_Retrieve thanks to its web service methods which provide to Gazelle a mean to communicate with it. A Web GUI is also available and enables the users to test their XCA responding gateway outside of a connectathon context. From this GUI, connecthaton participants can retrieve the messages sent and received during a test instance they have initiated. Note that this tool is able to send requests using TLS.

This simulator also supports the XUA (Cross Enterprise User Authentication) profile and can act as a X-Service User actor.

Transactions and Messages supported

As an Initiating Gateway for XCA, this simulator supports the ITI-38 and ITI-39 transactions. As it has been first developed for epSOS purposes, the epSOS affinity domain and more especially the epSOS-1 transaction is supported.

The exhaustive list of affinity domains, transactions and message types supported by the XCA Initiating Gateway Simulator is available in the "Informations" section of the XCA Initiating Gateway Simulator GUI.

Communication between the simulator and Gazelle

All simulators developed for interacting with Gazelle are built on the same model. The following diagram represents the different steps performed during a test instance.

Gazelle / Simulator interactions

Installation and Documentation

You can download sources of the XCAInitGatewaySimulator project from the INRIA Forge. This project required two additional modules: GSCommon-ejb and GSCommon-ui. Links to those sources are:

https://scm.gforge.inria.fr/svn/gazelle/branches/simulators/GSCommon-ejb

https://scm.gforge.inria.fr/svn/gazelle/branches/simulators/GSCommon-ui

https://scm.gforge.inria.fr/svn/gazelle/branches/simulators/XCAInitGatewaySimulator

 

This is a project built with Ant and running under JBoss 5. Once you have downloaded all the sources, you can build a development version of the project.

  1. Firstly, you have to make sure that Jboss 5, Jboss seam 2.1.0.GA and Postgresql 8 or later are installed.
  2. Copy the build-dev.properties.template file into build-dev.properties and edit this new file in order to set the different variables to match your system properties.
  3. Create the postgresql database that will host the data for the simulator and edit the file resources/XCAInitGatewaySimulator-dev-ds.xml to match your database set up. 
    {syntaxhighlighter brush: as3;fontsize: 100; first-line: 1; }createuser -P --username=gazelle --createdb createdb -E UTF8 -U gazelle xca-init-gw-simulator {/syntaxhighlighter}
  4. From the root directory of XCAInitGatewaySimulator project run the following command line:

 

{syntaxhighlighter brush: bash;fontsize: 100; first-line: 1; }ant -Dprofile=dev -Dapplication=XCAInitGatewaySimulator deploy{/syntaxhighlighter}

If your Jboss 5 server is running, the project will automatically be deployed, otherwise, start your server. During the deployment, the database (the name of which is configured in build-dev.properties file) will be populating using the resources/import-dev.sql file.

Finally, you can access the newly deployed project at http://localhost:8080/XCAInitGatewaySimulator

Javadoc relative to the XCAInitGatewaySimulator is available here.

How to write tests involving the XCA Initiating Gateway actor

When a test instance is created with the XCA Initiating Gateway Simulator as one of the test instance participants, Gazelle needs some additional information to be able to communicate with the tool. 

When you edit a test definition, for each step in which the XCA INIT_GATEWAY actor acts as the initiator of the transaction, you are expected to give the following information:

  • Transaction must be one of those supported by the simulator. See table in the "Informations" section of the simulator.
  • The message type must be one of those defined for the selected transaction. Make you sure the name is correctly written.
  • You also need to fill the contextual information. For this step, referred to the parameters required and optional for each message type. Please be careful to copy and paste properly the name of the parameter.
  • If the communications have to be secured, make sure you have checked the TLS option.
  • If the messages must be sent using XUA (a SAML assertion will be included in the SOAP header), add a contextual information with path "useXUA" and value equals to "true".

Contextual Informations

In order to send correct messages, the simulator expects some contextual informations from Gazelle. It is the responsability of the test designer to define the contextual information for each step if needed. For each test instance, the simulator stores the contextual informations so that it can retrieve them for the next steps. Informations extracted from the responding gateway response are also stored; consequently, the Patient Unique Id is enough to build all of the messages supported by the simulator; if the responding gateway provides enough informations in its responses. If XUA is used, you only need to fill the contextual informations for the first step and it will be reused for the next steps. Gazelle X Assertion Provider requires at least the Pratician ID and the Pratician Role.