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.

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.

Release Notes - XCA Initiating Gateway Simulator - Version 0.2-SR1

Sub-task

• [XCAINIT-21] - Javadoc

Bug

• [XCAINIT-7] - Message table: filtering does not work properly
• [XCAINIT-25] - XDS.b Doc Consumer: when selecting SUT Doc Repository, all fields are selected but the "execute" button is not shown
• [XCAINIT-28] - Timestamp of received message and received message content are not displayed

Improvement

• [XCAINIT-14] - Review response parsing to match the new model
• [XCAINIT-26] - Update parameters according new specifications

New Feature

• [XCAINIT-27] - epSOS Affinity Domain requires use of TRC assertion

Task

• [XCAINIT-16] - Application release
• [XCAINIT-17] - Write user manual on Drupal

Release Notes - XCA Initiating Gateway Simulator - Version 0.2-GA

Bug

• [XCAINIT-15] - Adding a configuration from the simulator page does not render the AffinityDomain selection box
• [XCAINIT-23] - User shouldn't be able to create an empty configuration.

Improvement

• [XCAINIT-24] - add a "message preview" button to show the message before sending it

New Feature

• [XCAINIT-13] - we need a XDS-b Document Consumer simulator
• [XCAINIT-22] - Add a user module

Release Notes - XCA Initiating Gateway Simulator - Version 0.1-SR1

Bugs

• [XCAINIT-18] - Execute button must not be visible until the MessageType is not selected
• [XCAINIT-20] - Selecting a new transaction does not empty the parameters list

Improvements

• [XCAINIT-19] - Add a page which gathers the list of affinity domains, transactions and message types supported by the simulator

Release Notes - XCA Initiating Gateway Simulator - Version 0.1-GA

Bugs

• [XCAINIT-8] - Crash when playing Find+Get Documents with no document found for given patient
• [XCAINIT-10] - Assertion is not supported by Tiani's responding gateway

Improvements

• [XCAINIT-11] - returnType for FindDocuments in epSOS context must be LeafClass
• [XCAINIT-12] - enable the user to customize the request

Release Notes - XCA Initiating Gateway Simulator - Version 0.1-RC6

Bugs

• [XCAINIT-6] - Transaction failed when trying to send a message
• [XCAINIT-9] - Tiani's responding gateway returns a ValidationException: Signature did not validate against the credential's key

Improvements

• [XCAINIT-3] - Add internationalization for GUI
• [XCAINIT-4] - Add footer to the template
• [XCAINIT-5] - Create a page which gathers Messages from test Instances and Messages from GUI

Click here to access the XCA Initiating Gateway Simulator .

New! The functionalities offered by this XCA Initiating Gateway simulator are getting more numerous and consequently the name of this simulator is going to change in the next weeks. As part of this improvement, the simulator now also works as a XDS.b Document Consumer

Introduction

As an initiator, the XCA initiating gateway simulator is aimed to send messages to a responder. So, if your system is ready to listen and accessible from the Internet, you will be able to send some messages to it.

By now, this simulator can act as two different actors:

• Initiating Gateway for XCA (Cross-Community Access)
• Document Consumer for XDS.b (Cross-Enterprise Document Sharing b)

The table below gathers the supported affinity domains, transactions and SUT actors.

What is this simulator able to do ?

This simulator has been developed with the purpose of helping the developers of responders, such as XCA Responding Gateway, XDS.b Document Repository and XDS.b Document Registry, with receiving messages and sending the responses to the Initiator (Initiating Gateway or Document Consumer). We have tried to manage most of the cases, that means that, all (or almost) message types defined in the technical framework of the various supported affinity domains and transactions are offered. For each message type, we have tried to distinguish the required parameters from the optional ones, in order to help you with building the request. Formatting of each field is not checked, so that you can test the robustness of your system by feeding it some with exotic values.

The exhaustive list of affinity domains, transactions and message types supported by the simulator can be found in the section "Informations" of the XCA Initiating Gateway Simulator. If you notice an error please refer it to us by adding a new bug in our issue tracker.

For each response it receives, the simulator tries to extract the relevant informations and displays them at the bottom of the page. Relevant informations which can be used as parameters for future requests are stored in memory (until the next response) and are use to pre-fill the field you will choose for the next request (if available). This functionnality used to be available but some recent changes in the architecture of the simulator have forced us to remove it for a while. As the response is available for display at the bottom of the page, you can copy and paste the informations you need for the next request.

Adding a system as a receiver

To communicate with your system under test, the simulator needs your system's endpoint configuration. Two ways to configure the simulator with your system properties:

• Simulator --> Configurations --> The tab corresponding to your SUT actor then then hit "Create a Configuration"

or

• Simulator --> "The simulator you need" then hit "New Configuration"

In both cases give:

• A name to your configuration (you can choose to create several configurations for the same system, for instance you may have an unsecured and a secured URL). This name must be unique, you will be asked to retry if the name is already used,
• The name of your system,
• The full URL to join your system,
• The Home Community Id your system is expecting to receive (optional),
• The Unique Id of the Repository your system is linked to (optional).

You need to record your configuration only once, then you will be able to select it in the drop-down list or to change it by going back to the Configurations page.

Sending a message to your system

Make sure your system is ready for receiving messages and no firewall prevents your system from receiving messages from the simulator.

1. Go to Simulator --> "The actor you need" and select your configuration in the drop-down list.
2. You will be then asked to select the Affinity Domain (IHE or epSOS); selecting the affinity domain give you access to one or several transactions the simulator is able to emulate. Select one of them.
3. Then, a list of message types is offered to you. Select one of them.
4. For each type of message, required and/or optional parameters are defined according the technical framework of the selected affinity Domain. The list of required parameters will be displayed first (if not empty). For each fields you fill, hit the OK button to confirm the addition of the value.
5. If you want to add some optional parameters: hit "Add optional parameter" and select the parameter name you need in the drop down list. Finally hit "Add" to extend the list of parameters.1

6. Once you have set all the parameters you need, select the return type. This value will be used for @returnType attribute of AdhocQueryRequest/ResponseOption tag.

7. Finally, you can choose to use XUA or not. If so, an SAML assertion will be added in the SOAP header of the request. 

8. To send the message to your system, only hit the "Execute" button.

If only one affinity domain, and/or transaction and/or message type is available for testing your system under test, those fields will be automatically filled in.

Management of parameters  

• If a field supports multiple values, a "plus" ()  icon will appear below the last value of the parameter.
• If a field supports multiple values and the AND/OR semantic, you will be asked to choose between these two options. By now, only the syntax value1 AND value 2 AND value3 AND ... is supported. You will not be allowed to mixed AND and OR for the same field.
• To remove a single value or an entire field (except required ones) hit the "minus" () icon.

Retrieving sent and received messages

Messages sent and received by the simulator, either from the GUI or from Gazelle, are gathered in a single page. You will find them clicking on "Messages" link in the topbar menu.

Get informations about Test Instances played from Gazelle

Each time an orchestrated test instance involving the XCA Initiating Gateway Simulator is started, the informations about the test participants are sent to the simulator. Those informations are available for viewing in the "Test Instances" section of the simulator (link in the topbar menu).