1. Practical part: Creation of WSDL file of X-Road dataservice
Module 5
Practical part: Creation of WSDL file of X-Road dataservice
Name
Date

2. Tools:
For creating a WSDL of the X-Road dataservice and dataservice server and the client we use the following software in the development machine:
Java (JDK 7)
Apache Tomcat 7.0
Apache CXF (ver )
Eclipse Mars (Eclipse IDE for Java EE Developers)
SoapUI

3. Creation of WSDL of X-Road dataservice
For generating the Java code of X-Road dataservice based on WSDL, we use an Apache CXF component, which must be first set up in the Eclipse IDE environment, by taking the following steps:
Set up Eclipse CXF Runtime:
Activate Eclipse and select in the menu:
Window -> Preferences -> Web Services -> CXF 2.x Preferences->Add
Enter: ‘CXF Home’– Name of Apache CXF folder
Select: ‘Finish’, ‘OK’

4. 2. Create a new Eclipse project
Select in the menu: File -> New ->Other -> Dynamic Web Project

5. Select: Next >
Enter project data:
Project name: <person_register> (name of your project)
Dynamic web module version: select 2.5, (not default 3.0)
Configuration: CFX Web Services Project v2.5
Select: ‘Finish’

6. Open: ‘project Properties’ -> Targeted Runtimes -> New
Tomcat Installation directory: select the Tomcat 7 folder from the file system with ‘Browse’ dialogue

7. Creation of WSDL file
For creating a WSDL of the X-Road dataservice, you can:
Take some available WSDL file as basis (for this purpose, sample files of the training environment include the file person_register.wsdl) and edit it according to the needs of your service.
Create a new WSDL file with Eclipse IDE tools

8. Creation of a new WSDL with Eclipse wizard:
In order to obtain a WSDL description of X-Road dataservice, we create the frame of a new WSDL file with one minimal service by using the Eclipse wizard for creating the WSDL file. As a result we get an example of a WSDL file, which can be edited as necessary.
For creating a new WSDL in the Eclipse environment, execute the following steps:
Select: File -> New ->Other -> WSDL File
Select: Next >

9. Enter data of WSDL file:
File name: persons_register.wsdl (WSDL file name of database)
Select: Next >

10. Enter the data:
Target namespace: Enter namespace of your dataservice, e.g.:
SOAP Binding options: select ‘document literal’
Select: Finish
Now we have generated the minimum WSDL file, including one WSDL operation ‘NewOperation’ corresponding to the X-Road dataservice.

11. Editing the generated WSDL
Then, we will start editing the generated WSDL example to bring it into conformity with our X-Road dataservice
There are two alternatives in Eclipse WSDL editor for editing WSDL:
Edit the WSDL source code directly or work with XML in a text editor and use Eclipse WSDL validator during editing for validating the correctness of XML/WSDL.
Edit WSDL in graphic editor, where WSDL/XML source code is generated automatically.

12. Adaptation of WSDL example with graphic editor
Open WSDL for editing the file; graphic editor view is opened by default.
Rename dataservice (or WSDL operation):
Select an operation in the editor and change the name of the operation in the properties window based on the description of your dataservice (see the red highlight in the figure).
!note that the names of input/output elements are also changed automatically based on the operation name

13. Bringing the structure of dataservice into conformity with the description of the service
Now, bring the input/output of the dataservice into conformity with the description of the service.
Open the inline schema computer editing programme (hereinafter the editor). Proceed as follows: on WSDL ‘Design’ view, click on the blue arrow at input (see the figure, indicated with a red arrow)

14. In the inline schema  editor view
first open the schema index view by clicking on the relevant icon in the upper left corner
! see the figure, indicated with a red arrow

15. Change the operation input and output in WSDL as required (i. e
Change the operation input and output in WSDL as required (i.e. according to the description of your dataservice).
Add data types needed for describing the input and output of dataservice – WSDL complex types.
Data types can be added in the ‘Types’ section by selecting ‘Add Complex type’.

16. In order to change the structure of some complex type
click on the name of the relevant complex type
a detailed view of the type description will open:

17. Add descriptions of X-Road headers
In order to add X-Road header fields, it is easier to use XML source code editor, therefore we switch WSDL editor to the source code view (‘source’).
Add the definition of X-Road namespace: xmlns:xrd= road.eu/xsd/xroad.xsd to the attributes of the label wsdl:definitions in WSDL.

18. Add a message (message) to WSDL, where X-Road header fields are defined.
It’s location is in WSDL after the label </wsdl:types
Add XML:
<wsdl:message name="xrdheader">
<wsdl:part name="client" element="xrd:client" />
<wsdl:part name="service" element="xrd:service" />
<wsdl:part name="userId" element="xrd:userId" />
<wsdl:part name="id" element="xrd:id" />
<wsdl:part name="protocolVersion" element="xrd:protocolVersion" />
</wsdl:message>

19. Add descriptions of X-Road header in WSDL under elements binding/operation/input and binding/operation/output:
<wsdl:input>
<soap:body use="literal"/>
<soap:header message="tns:xrdheader" part="client" use="literal"/>
<soap:header message="tns:xrdheader" part="service" use="literal"/>
<soap:header message="tns:xrdheader" part="userId" use="literal"/>
<soap:header message="tns:xrdheader" part="id" use="literal"/>
<soap:header message="tns:xrdheader" part="protocolVersion" use="literal"/>
</wsdl:input>
Add the version number of X-Road service in WSDL under elements binding/operation:
<xrd:version>v1</xrd:version>
Add a human-readable description of the dataservice to the element portType/operation/documentation/xrd:title in WSDL:
<xsd:element name="phone" type="xsd:string" maxOccurs="unbounded" minOccurs="0">
<xsd:annotation>
<xsd:appinfo>
<xrd:title xml:lang="et">Telefon</xrd:title>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>

20. Add a human-readable description of the dataservice to the element portType/operation/documentation/xrd:title in WSDL
<wsdl:portType name="persons_register">
<wsdl:operation name="personList">
<wsdl:documentation>
<xrd:title xml:lang="et"></xrd:title>
</wsdl:documentation>
Now, WSDL of X-Road dataservice is completed, all obligatory X-Road elements have been added

21. Thank You! First name Surname firstname.surname@amet.ee
The training materials for developers of X-Road interfaces have been compiled with funding from the structural funds support scheme “Raising Public Awareness about the Information Society” of the European Regional Development Fund.