Tutorial6: Calling a SOAP Web Service

Tutorial 1 - A simple SOAP Web Service resource with two tables

This tutorial works with an example SOAP web service application that is included with the Ebase Xi distribution. Before continuing, the web service needs to be deployed to the application server –

this step is only necessary when using an external server, if you are using the Integrated Test Server this web service has already been deployed.

The example web service is a standard J2EE web application archive called ebaseWS.war and can be found in UfsServer/samples.

If you are running a Tomcat server, copy this file into UfsServer/tomcat/webapps and start the tomcat server. (On completing the tutorial, the web service can be un-deployed by deleting the copied file).

Check that the web service is available by browsing to http://localhost:3030/ebaseWS/ws/flights?wsdl (your host name and port number may differ) or

http://localhost:3050/ebaseWS/ws/flights?wsdl if you are using the Integrated Test Server with the default port. You should now see the WSDL file for the flights web service.

A WSDL is an XML document that defines the details of a web service, including the available operations and their XML type definitions.

Because this WSDL defines everything about the flights web service, the WSDL importer can do most of the work required to make a SOAP Web Service Resource.

Step 1.

Start with the Ebase Xi Server and Ebase Xi Designer running.

Step 2. Use the WSDL importer to set up a new SOAP Web Service Resource

If the Tutorials project doesn’t already exist, create it by right clicking in the tree panel and selecting New > Project, then link the new project to the ebaseSamples project (right click on the project name, then select Properties).
Create a new folder for the tutorial: right click on the Tutorials project and select New > Folder, name the folder Tutorial6.
Create a new empty SOAP Web Service Resource: right click on Tutorial6 folder and select New > SOAP Web Service Resource. Enter FlightsRes as the name of this new resource.

This will create a new empty SOAP Web Service resource with an empty default Web Service Adapter.

Click on the icon on the adapter toolbar which will launch the WSDL import wizard.
On the first page, type the URL of the WSDL. It will be something like http://localhost:3030/ebaseWS/ws/flights?wsdl. Click Next to load the WSDL and move to the next page.
The next page lists all available operations in the flights web service. Select the getFlights operation from the list.

The right hand panels will display examples of what the body of the inbound and outbound SOAP messages may look like. Click Next.

The WSDL import wizard can optionally create fields and tables for the basic elements of this operation. Ensure the Import all fields option is selected and click Finish.
Click the save icon on the resource toolbar at the top of the panel to save this resource. The SOAP Web Service Resource is now operational.

You can browse the left hand navigation panels to see what the import wizard has done. Most notable are the two resource tables, Flight and Passenger.

These are attached to the repeating <Flight> and <Passenger> elements of the Response XML document.

Step 3. Create a new form

a. Right click on the Tutorial6 folder in the tree panel, enter New > Form and name the form FlightsForm

b. Click the form properties icon on the form toolbar at the top of the page, select the Presentation tab, then click the … button to the right of the Presentation Template property

and select the xiDefault template from the ebaseSamples project

c. Add the FlightsRes SOAP Web Service Resource to the form: in the form editor select the Resources View (usually in the top right-hand corner), click the Add Resource icon and select the FlightsRes resource and save the form.

d. The tables can now be added to the form. In the Tables View, click the New table icon . Select FlightsRes for the Resource name and Flight for the Resource repeating field.

Click the Import columns from resource button and click the Select All button to select all resource fields. Press OK twice. Drag the table Flight onto the page.

e. The previous step is repeated for the passenger table. In the Tables View, click the New table icon . Select FlightsRes for the Resource name and Passenger for the Resource repeating field.

Click the Import columns from resource button and click the Select All button to select all resource fields. Press OK twice.

Drag the table onto the page under the Flight table.

f. A script will be needed to call the web service. Right click on the Tutorial6 folder in the Entities tree panel, and create a new script named flightsScript.

There is a choice of programming languages, so create the script in the language you prefer New > Script (Javascript) or New > Script (FPL).

Scripts are shown below for Javascript and FPL (the Ebase built-in Form Processing Language):

Javascript:

FPL:

resources.FlightsRes.call();
tables.Flight.fetchTable();
tables.Passenger.fetchTable();

call FlightsRes;
fetchtable Flight;
fetchtable Passenger;

g. The call statements will call the SOAP web service. The XML response document will be stored in the resource. Both fetchtable statements populate their respective tables.

Click the icon to save the script flightScript.

h. The script is going to be triggered using a button. In the FlightsForm, drag a Button Control from the Palette View to the top of the page above the tables.

You can change the button display text <no text set> by double clicking on the button and enter Call Flight WS.

i. Associate the script with the button by right clicking on the button, select Events and add the flightsScript script.

Step 4. Run and test the form

Click the Run icon on the form toolbar to run the form in your local browser. When the form appears in your browser, click the Call Flight WS button to call the web service and populate the tables.

The tables should be populated with flight and passenger information.

Tutorial 2 Multiple adapters and enhanced XPath

Tutorial 2 enhances the project developed in tutorial 1. A log adapter is going to be added to the resource in order to demonstrate the use of multiple adapters.

The fields and tables are also going to be enhanced, demonstrating the use of XPath and input variables.

Step 1. Add a log adapter

Return to the FlightsRes SOAP Web Service Resource. Add a log adapter by right clicking on adapters in the top left panel and selecting Add Adapter.

Enter log for the adapter name and select Log XML from the drop down list of adapter types and click OK.

The log adapter is very simple:

All that needs to be configured is the document to be logged. In Log Adapter pane, opposite of Document: select the Response document from the drop down list. Save the resource.

Step 2. Add the log adapter to the script.

To log the Response to the server log and the Designer’s execution log, an extra line must be added to the flightsScript script.

Return to the flightsScript script. At the end of the script add the line:

Javascript:	FPL:
resources.FlightsRes.call("log");	call FlightsRes 'log';

Save the script.

When the form is now run again, the response document from the resource will be written to the execution log (View > Execution log) and the server log (in the Tomcat console window, if running Tomcat).

(Note that you can also log the request and response documents just by clicking the Debug checkbox in the adapter properties.)

Step 3. Add a passenger count to the 'Flight' table

In this step, a new column is added to the Flight table. The XPath count function is used to count the number of child passenger XML elements contained in each flight XML element (i.e. how many passengers are on each flight).

Open FlightsRes SOAP Web Service Resource, select the Flight table icon in the Resource Fields panel, click the icon on the Resource Fields panel toolbar and select Add column.

Enter passengerCount as the name of the column. In the Field Properties panel on the right change the XPath expression to count(flig:passengers/flig:Passenger).

Set the Value Type of this field to integer - '{http://schemas.xmlsoap.org/soap/encoding/}integer'.

Step 4. Add the flight number to each passenger row

Select the Passenger table icon, click the icon on the Resource Fields panel toolbar and select Add column, enter flightNum as the name of the column.

Change the XPath expression to ../../flig:flightNo. This gets the value of flightNo for the parent flight XML element (i.e. passenger's flight number). Save the resource.

Step 5. Re-import the tables into the form

The easiest way to add the new resource columns to the form is to delete both tables and re-import them again.

Return to form FlightsForm and delete the tables Passenger and Flight in the Tables View by selecting them and pressing the Delete key.

Re-import the tables by performing Step 3. parts d and e from Tutorial 1.

When the form is run again, the flights table now shows a passenger count and the passenger table shows the flight number for each passenger.

Step 6. Add an XPath variable

At the moment, all passengers for all flights are displayed in the Passenger table. In this step, a variable will be added to the Passenger table's XPath to only show passengers on a particular flight.

· Return to FlightsRes SOAP Web Service Resource and double click to open.

· Select the Passenger table item in the Resource Fields panel.

Change the table's XPath to /flig:getFlightsResponse/flig:out/flig:Flight[flig:flightNo=$flightNo]/flig:passengers/flig:Passenger.

This adds the conditional expression 'flig:flightNo=$flightNo' to restrict the Flight elements. The value of flightNo is taken from the current row of the Flight table,

so if the form is re-run, only passengers from the first flight will be listed. Save the resource.

· Dynamic behaviour can be achieved by changing the flightNo form table column into a hyperlink and attaching a script to refresh the passenger table.

o Add a new script named passengerScript (right click in the Entities tree panel: Tutorials/Tutorial6 then enter New > Script) – select either Javascript or FPL.

o Type in the following depending on your programming language preference and save it:

Javascript:	FPL:
tables.Passenger.fetchTable();	fetchtable Passenger;

o Return to the FlightsForm form. In the WYSIWYG View, right mouse click on the FlightNo column in the Flight table and select the Hyperlink property or

Properties panel, Table Column Control section, tick Hyperlink properties. Add the passengerScript script to the FlightNo column’s On Click event.

· Make Flightno the first column displayed in the Flight table by dragging the columns. Set the other columns in the table to display only.

· Set all the columns in the Passenger table to be display only.

· Set the table header text <no table header set> for the Passenger table to “Passengers for flight &&Flight-flightNo”.

· Set the table header text <no table header set> for the Flight table to “Flights”.

When the form is run again, the passenger table now only shows passengers for the selected flight.

Clicking on a flight hyperlink shows the passengers for that flight.