Documentation

Connecting to Web Services

You can send messages to a web service using the eiConsole by configuring an HTTP-enabled Transport. Responses can be received and handled as transactions by configuring that Transport to use a Response Listener. Because this makes use of a request / response (asynchronous) approach, we’ll construct our interface using two Routes: one to generate and send the request, and one to accept and handle the response.

First, create two Routes in the Route File Management dialog by clicking the Add Route button.

Clicking this button will raise a dialog asking you to name the Route. Name the first Route Web Service Request and the second Web Service Response.

Your Route File Management dialog should now list both of these routes in the Route Overview table.

We’ll begin by configuring the Web Service Request Route. Double click to open it. The main eiConsole route overview grid will appear.

For this example, we’ll assume that we’re picking up a document from a directory and sending it directly to the service without any additional transformation. This is generally suitable for a service expecting raw data (string, XML, or otherwise).

We’ll want to configure the Listener and the Source’s associated Format. Select the Listener stage. The Listener Configuration panel appears. Then choose Directory / File from the dropdown of available Listener Type modules.

We’ll assume a relatively simple configuration here. Browse to a newly created folder using the Ellipsis button.

Here we selected the c:\WebService\in folder. Create this folder if it doesn’t exist.

The Polling Directory is now set to the c:\WebService\in folder.

We now need to configure our Transport, which will communicate with a SOAP-based web service over HTTP. Select the Transport stage. The Transport Configuration panel will open, then select HTTP Post from the Transport Type dropdown menu. (Note the variety of transports that you have to choose from.)

At this point, we’ll need to step away from the eiConsole and take a look at the actual service we’d like to connect to. Most SOAP services are accessed by sending a SOAP header-wrapped document (most typically XML or a string) to the service URL along with a SOAPAction header specifying the SOAP operation to invoke, or, if the WSDL describing the service does not define action names, by specifying the “method” property in the service URL.

For our example, we’ll take a look at using the SOAPAction header. First, enter the URL of your web service into a browser with “?wsdl” appended to the end. You should get a WSDL file back, which might look something like the example below.

Within the WSDL, the service should provide definitions for each available operation within an “operation” tag. This example uses an operation called “GetSunSetRiseTime”.

After you have selected SOAP Web Service, write down the name of the operation you want to invoke. We’ll use this later as the “SOAPAction” header. Your service may also provide a “soapAction” attribute to specify instead of the operation name.

We’ll now provide the base service URL for our Transport’s configuration. Type the URL into the Target URL. In our example, the URL is http://www.webservicex.net/sunsetriseservice.asmx.

You can configure the SOAPAction header underneath the Advanced tab by adding a row to the HTTP Headers table. New rows can be added by clicking the + sign. In our example, the SOAPAction header is “http://www.webserviceX.NET/GetSunSetRiseTime”.

Remember that this value will need to match the operation name from earlier.

At this point, this particular Route will pick up a file from the directory specified by our Listener and send it to the provided URL to invoke the named SOAP action. The eiConsole / eiPlatform will automatically consume the response provided by the service, deferring to the HTTP response code to determine Transport success or failure.
However, we want to pass the response to our response Route created earlier. The Response Listener configuration item under the Advanced tab allows us to do this by specifying the name of a Listener of type Programmable (Trigger). Since we have not yet configured the response Route, we will come back to configure this later.

Go to the File Menu and Save Current Route, then click File Management to return to the Route File Management dialog.

You can notice the Web Service Request icon became blue – the Web Service Request route is fully configured now. Select the Web Service Response route and double click to open.

We’ll be dropping our response off to the local filesystem without any changes or transformations, so leave the Source and Target Transform Formats as are – Relay (System Format).

Select the Listener stage, and from the module dropdown, select the type called Programmable (Trigger).

This particular Listener type requires only one form of configuration: its name. We’ll set the Listener’s name to Web Service Response Listener.

Next we’ll need to set and configure the Transport type. Select the Transport stage, then select the Directory / File entry from the dropdown.

For our example, we’ll just configure the Transport to drop the response to a file named sunRiseSetResponse.xml by entering C:\WebService\out in the Target directory field. Enter sunRiseSetResponse in the Target file name field and xml in the Target file extension field.

Now, we need to connect the HTTP Post Transport in our request route to the Programmable Listener in our response route. Go to the File Menu and click Save Current Route.

Re-open the Web Service Request Route and go to the Response tab of the HTTP Post Transport. Click the ellipsis button and select the programmable listener from the Web Service Response route.

Both the request and response Routes are now configured. However, we’ll be unable to test them together using the normal eiConsole testing mode, since that mode does not support multi-Route tests. To run our test, we’ll want to launch the emulator. Open the eiPlatform Emulator by selecting Local eiPlatform Emulator from the Route menu:

Once the eiPlatform Emulator is open, just click Start Emulator. This will begin running a localized instance of the eiPlatform, which will output its log content to the logging panel in the emulator dialog.

You should be able to read through the log messages and ascertain if each particular Route was read correctly and started up. Testing the service is then a matter of dropping a file into the specified input directory (WebService\in as we set in our tutorial) and then watching both the emulator log and the output directory (WebService\out for our example).

For the web service in this example, you can test the routes by creating an xml file in C:\WebService\in with the following contents:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetSunSetRiseTime xmlns="http://www.webserviceX.NET/">
<L>
<Latitude>49.371056</Latitude>
<Longitude>-0.879504</Longitude>
<Day>6</Day>
<Month>6</Month>
<Year>1944</Year>
</L>
</GetSunSetRiseTime>
</soap:Body>
</soap:Envelope>


The response file created in C:\WebService\out should then contain the following:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<GetSunSetRiseTimeResponse xmlns="http://www.webserviceX.NET/">
<GetSunSetRiseTimeResult>
<Latitude>49.3710556</Latitude>
<Longitude>-0.879504</Longitude>
<SunSetTime>16.775671</SunSetTime>
<SunRiseTime>6.81081438</SunRiseTime>
<TimeZone>0</TimeZone>
<Day>6</Day>
<Month>6</Month>
<Year>1944</Year>
</GetSunSetRiseTimeResult>
</GetSunSetRiseTimeResponse>
</soap:Body>
</soap:Envelope>

This concludes the Connecting to Web Service Tutorial.