European Commission s17

EUROPEAN COMMISSION HEALTH AND CONSUMERS DIRECTORATE-GENERAL

General Affairs Information systems

European Commission XTB Webservice HowTo An introductory guide to the XTB system

Date: 14/06/2012 Version: 1.1 Authors: Francesco AMELIO Revised by: Approved by: Public: Reference Number:

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. 1. INTRODUCTION...... 3 1.1. Architecture...... 3 1.2. Before you start...... 3 1.3. Contents of the distribution...... 4 2. TESTING XTB VIA SOAPUI...... 4 2.1. Executing the Test Suite...... 6

Commission européenne/Europese Commissie, 1049 Bruxelles/Brussel, BELGIQUE/BELGIË - Tel. +32 22991111 1. INTRODUCTION

XTB is the chosen acronym for "XMLGate TRACES Businesses", meaning the webservice made available to Member States to allow the management of organizations registered in the TRACES system.

The aim of this document is to explain a couple of tools that can help in the development of a customized client application. Such a client application would implement the "glue" between the national database (or national IT system controlling the database) and the XTB service. Exactly how a client would be implemented depends on what underlying technology is used (Java, .Net, Spring…). Therefore, the detailed information on how to program the web services client is not provided here.

1.1. Architecture

The following diagram describes the flow that a SOAP message will follow during the execution of a XTB method. The member state should develop his own client application to invoke the Traces Metadata Webservice (XTB) and get the Traces Database updated accordingly.

Member State User Member State

Member State Internet European Commission

Soap Message SSL

Traces Metadata Webservice Traces Database

1.2. Before you start

The starting point for consuming the web service will always be the WSDL file XTB- xmlgate2.wsdl together with the XSD xtb-services.xsd (in the folder xsd)

The WSDL is part of the XTB documentation bundle that you can find on the Circa Website at the URL:

 https://circabc.europa.eu/w/browse/31671c3b-4800-4177-a869-de44d09d0954 3 In order to execute the tests, you will also need to request a password at the address: [email protected]. The helpdesk will provide you with the credentials needed to execute the tests.

1.3. Contents of the distribution

The bundle contains a set of files that can be used to reproduce the XTB-service testing tools, and some other important reference data.

 XTB_data_dictionary.doc

 XTB_Submit.xml: XML skeleton used to create, delete and update businesses in one submit. NOTE: please modify this file before using it as test data. You will have to type your Username and Password as well to fill all the businesses data out. The Password needs to be Base64 encoded.

 XTB_ReadBusiness.xml: XML skeleton used to read a business.

 XTB_SearchBusiness.xml: XML skeleton used to search for businesses.

 XTB_DeleteBusiness.xml: XML skeleton used to delete a business.

 XTB_CreateBusiness.xml: XML skeleton used to create a business.

 XTB-SoapUI-Test-soapui-project.xml: SoapUI project with a Test Suite

 XTB-SoapUI-Test-soapui-project.properties: SoapUI test configuration property file

2. TESTING XTB VIA SOAPUI

The simplest way to test the service is to use SoapUI, a free tool that allows you to make WebService call using raw xml text. In this way all the operations can be tested and debugged easily by the developers.

We recommend using the version 3.5.1 since the tests and the sample test case project is developed on this version of SoapUI. In the bundle is also provided the project file (XTB-SoapUI-Test-soapui-project.xml) that can be imported in SoapUI from the menu File  Import Project.

You should then have a project like shown in the following picture:

4 Clicking on the project name and then on "Custom properties" a properties list will appear. The parameters can be loaded from a property file (a sample property file - XTB-SoapUI-Test-soapui-project.properties - is provided in the bundle) or alternatively the properties can be filled in manually:

 endpoint: by default provided as the acceptance environment

 username: the username as provided by the Traces Support (SANCO- [email protected])

5  password_base_64: the username as provided by the Traces Support, encoded in Base64 format

 new_business.city_name: name of the city of the business

 new_business.city_postal_code: postal code of the city of the business

 new_business.authority_code: business authority Code (must exist in traces)

 new_business_approval_num: approval number of the business to create

 new_business_approval_num2: a second approval number of the business to create (different)

 new_business.city_country_code – country ISO code (i.e. ES for Spain, FR for France etc.)

2.1. Executing the Test Suite

Once the project properties are configured the test suite is ready to be executed. Double click on the TestSuite and then on Play button on top. The tests will be run in sequence. Any problem will be reported in red.