How to construct and make X-Road SOAP requests?
By: Rait Kapp
Tags: Soapui, X Road, Debugging

How to set up test X-Road service locally

To make this how-to more practical and testable we will set up local X-Road test security server so you can try everything out at first hand. You can however skip this part if you already have a real security server and a specific service in mind to debug.

Nordic Institute of Interoperability Solutions has developed X-Road security server for testing. This server behaves like real security server. It fakes X-road network and generates responses by itself. This server implements only one service testService witch returns the response with requested size filled with random characters.

Run the test server in local machine:

$ docker run --rm -p 8080:8080 petkivim/x-road-test-service:v0.0.3

Test the server by pointing browser to http://localhost:8080/. On Windows use docker-machine ip command to get Docker host’s IP address and replace the localhost with IP address.

If you see Apache Tomcat page then the Docker container is up and running.

How to construct X-Road SOAP request from WSDL

All X-Road services must be described using WSDL. WSDL is human and machine readable format which describes what services server exposes and their input and output format.

You can think of X-Road service provider as a class and all services like methods in that class. Then the WSDL is the description of class showing what methods it has and what are the input and output parameters.

You can ask WSDL from security server or you can take it from public catalog.

Because we are using test server witch is not registered in public catalog we have to ask WSDL from security server. Open in browser http://localhost:8080/test-service-0.0.3/Endpoint?wsdl. If the content looks like gibberish do not worry. Luckily there are plenty of free tools like Soap UI or WSDL Analyzer that will help us. Just save the WSDL down to your disk so you can use it later.

We will use Soap UI because it also has built in HTTP request tool. Install Soap UI and open it. Select File -> New SOAP Project and in opened modal window put a name (1), select previously downloaded WSDL (2) and make sure the Create Requests checkbox is marked (3).

Press OK and expand the tree on left side and double click on sample request under testService (3). Now you should see the service SOAP request (4).

You can actually make a X-road request. In address bar (5) you have to enter your Security Server URL. In current sample we have http://localhost:8080/test-service-0.0.3/Endpoint.

Press the Run button (6) and see what happens. You will see the response of request on right side (7). Currently it will return a “good error”. Good error because the response is in SOAP format. This means that connection to Security Server works — one problem less.

The problem is that we have not filled the parameters in request on left side.

If you are new to X-Road then the amount of information needed to make a request seems overwhelming. Actually, it is not hopeless. Lets cover them step by step. X-Road SOAP request contains two parts: header (8) and body (9).

In header there are meta-data (10–12) about request. It states who is the client (12) who is making a request, what is the service (11) client is requesting and some more data (10). The content of body (9) is the actual X-road service request (13). This all is described by the X-Road Message protocol.

Let’s split down the header and start with service (11):

xRoadInstance — Anyone can set up its own X-Road network and all have to give it a unique name. For example Estonian X-Road has name EE. There is also official test X-road in Estonia with the name ee-test. The Finnish X-road has instance name FI. Current test server has named itself NIIS-TEST.

— Anyone can set up its own X-Road network and all have to give it a unique name. For example Estonian X-Road has name EE. There is also official test X-road in Estonia with the name ee-test. The Finnish X-road has instance name FI. Current test server has named itself NIIS-TEST. memberClass and memberCode — These fields have a meaning together and are identifying the X-Road member. In current context the member who is providing the service. In Estonia the memberCode is the registry code of a company. The memberClass will specify what type the member is. Most used values in Estonia are GOV for government institutions and COM for private entities. Current test server pretends it is government institution with code 0245437–2.

and — These fields have a meaning together and are identifying the X-Road member. In current context the member who is providing the service. In Estonia the memberCode is the registry code of a company. The memberClass will specify what type the member is. Most used values in Estonia are GOV for government institutions and COM for private entities. Current test server pretends it is government institution with code 0245437–2. subsystemCode — Every member can have several subsystems. Even if it has only one it must have a name. Current test security server exposes subsystem named TestService.

— Every member can have several subsystems. Even if it has only one it must have a name. Current test security server exposes subsystem named TestService. serviceCode — one subsystem can have several service. Here you have to tell which service you want to query. In current tutorial it is testService.

— one subsystem can have several service. Here you have to tell which service you want to query. In current tutorial it is testService. serviceVersion — every service must be versioned. Current test service has version v1

By the way, if you know the service parameters then you can construct a unique service id as one string.

{xRoadInstance}/{memberClass}/{memberCode}/{subsystemCode}/{servicecode}/{serviceVerson}

This service id format is gaining popularity. It is easier to express and is used in X-road Catalog and in the REST version of X-Road.

The client (12) is also the X-Road member like service provider so the field meaning is exactly the same as described previously. Just the serviceCode and serviceVersion are dropped. In current sample the client’s xRoadInstance is still NIIS-TEST, memberClass=GOV, memberClass=123456–7 and subsystemCode=TestClient.

Besides service and client there are some extra fields (10):

protocolVersion — shows the version of X-Road Message Protocol specification according witch this SOAP envelope is built. Must be 4.

issue — client can add some back reference to the request. Optional. We will remove it in sample.

id — unique id of the request. Mandatory. Specification suggest to use UUID. You can use any random string in test server. If you really need unique UUID in production or test X-Road then Online UUID generator will help.

userId — natural person code who is making the request. Optional except if service provider requires it explicitly. It has format {countryCode}{personCode} where countryCode is two letter country coude. For example, if I am an Estonian with person code 00000000000 then I have to put into userId tag value EE00000000000. We will remove it in our test.

After filling missing data our test request looks like this:



<soapenv:Header>

<xro:protocolVersion>4</xro:protocolVersion>

<xro:id>67322f5c-8c74-4b12-bbcb-073618f30b1b</xro:id>

<xro:service iden:objectType="SERVICE">

<iden:xRoadInstance>NIIS-TEST</iden:xRoadInstance>

<iden:memberClass>GOV</iden:memberClass>

<iden:memberCode>0245437-2</iden:memberCode>

<iden:subsystemCode>TestService</iden:subsystemCode>

<iden:serviceCode>testService</iden:serviceCode>

<iden:serviceVersion>v1</iden:serviceVersion>

</xro:service>

<xro:client iden:objectType="SUBSYSTEM">

<iden:xRoadInstance>NIIS-TEST</iden:xRoadInstance>

<iden:memberClass>GOV</iden:memberClass>

<iden:memberCode>123456-7</iden:memberCode>

<iden:subsystemCode>TestClient</iden:subsystemCode>

</xro:client>

</soapenv:Header>

<soapenv:Body>

<prod:testService>

<request>

<responseBodySize>5</responseBodySize>

<responseAttachmentSize>0</responseAttachmentSize>

</request>

</prod:testService>

</soapenv:Body>

</soapenv:Envelope> http://schemas.xmlsoap.org/soap/envelope/ " xmlns:xro=" http://x-road.eu/xsd/xroad.xsd " xmlns:iden=" http://x-road.eu/xsd/identifiers " xmlns:prod=" http://test.x-road.fi/producer "> 4 67322f5c-8c74-4b12-bbcb-073618f30b1b NIIS-TEST GOV 0245437-2 TestService testService v1 NIIS-TEST GOV 123456-7 TestClient 5 0

Make sure you also filled properly attributes <xro:service iden:objectType=”SERVICE”> and <xro:client iden:objectType=”SUBSYSTEM”>.

Now hit the Run and you will receive the response:



<SOAP-ENV:Header>

<xrd:client id:objectType="SUBSYSTEM">

<id:xRoadInstance>NIIS-TEST</id:xRoadInstance>

<id:memberClass>GOV</id:memberClass>

<id:memberCode>123456-7</id:memberCode>

<id:subsystemCode>TestClient</id:subsystemCode>

</xrd:client>

<xrd:service id:objectType="SERVICE">

<id:xRoadInstance>NIIS-TEST</id:xRoadInstance>

<id:memberClass>GOV</id:memberClass>

<id:memberCode>0245437-2</id:memberCode>

<id:subsystemCode>TestService</id:subsystemCode>

<id:serviceCode>testService</id:serviceCode>

<id:serviceVersion>v1</id:serviceVersion>

</xrd:service>

<xrd:id>67322f5c-8c74-4b12-bbcb-073618f30b1b</xrd:id>

<xrd:protocolVersion>?</xrd:protocolVersion>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

<ts1:testServiceResponse xmlns:ts1="

<ts1:request>

<ts1:responseBodySize>5</ts1:responseBodySize>

<ts1:responseAttachmentSize>0</ts1:responseAttachmentSize>

</ts1:request>

<ts1:response>

<ts1:data>3i6qw</ts1:data>

<ts1:processingTime>1</ts1:processingTime>

</ts1:response>

</ts1:testServiceResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope> http://schemas.xmlsoap.org/soap/envelope/ " xmlns:id=" http://x-road.eu/xsd/identifiers " xmlns:xrd=" http://x-road.eu/xsd/xroad.xsd "> NIIS-TEST GOV 123456-7 TestClient NIIS-TEST GOV 0245437-2 TestService testService v1 67322f5c-8c74-4b12-bbcb-073618f30b1b ? http://test.x-road.fi/producer "> 5 0 3i6qw 1

The service is simple and returns as much characters as asked in request’s responseBodySize tag. We asked 5 and receive 5.

We did not asked an attachment but if you assign other value to 0 you will get multipart SOAP. It is more complex and we do not cover it here but if you ever need to develop it then this test server is handy tool to use for learning.

One tip when making multipart requests, SOAP UI will extract the SOAP response and hide the attachments. You can see the row HTTP request when you select Raw tab:

You can also look the request’s raw HTTP request message. This might be useful if you want to make request with curl for demonstration purposes.

Debugging

For debugging the X-Road request it is important to understand how the X-Road works.

If you run the request in SoapUI the application will connect to client’s security server and hands over the request (actually makes HTTP POST request). Client’s security security server will look the SOAP envelope header and figures out (using central server that we do not cover here) what is the service provider’s security server address and passes message to it. The service provider’s security server will pass request to the end service. Then the response will be relayed back the same way through security servers to Soap UI.

If you receive an error then it is confusing to figure it out where the error happened. In such case read the error message carefully and think in what server the message might makes sense.

The rule of thumb that works for me:

If error response is not SOAP — you did not reached the client’s security server at all. Check the security server URL.

If error response is SOAP Fault then it is the response of ether client’s or providers security server.

Service providers usually document how they report errors in normal SOAP response's body.

In any case, if you are contacting with others then it might be helpful to add the raw part of the request and response from SoapUI. This can give more information to administrators what might be wrong.

Summary

This tutorial demonstrated how construct SOAP request from WSDL and how to send it to security server. Feel free to leave any comment if you have a question or want to share your experience. I am especially interested in error handling.

If you are developer and interested digging deeper into X-Road I suggest to read the Training materials for developers of X-Road interfaces.