Example: Calling a SOAP Web Service
This example shows you how to query a Web time service using a constant as an input. The Web service itself was implemented using MapForce. This is for demonstration purposes—you can implement the Web service with any other technology that supports a compatible protocol.
The mapping shown below is part of the TimeService.mfp mapping project, available in the <Documents>\Altova\MapForce2023\MapForceExamples\TimeService folder. The TimeService2.mfp project file available in the <Documents>\Altova\MapForce2023\MapForceExamples\TimeserviceWsdl2 folder supports WSDL 2.0.
To view how the Web service is implemented:
|1.||Select File | Open and select the TimeService.mfp file in the <Documents>\Altova\MapForce2023\MapForceExamples\Timeservice folder. The files associated with the project are loaded in the Project window.|
|2.||Double-click the getCityTime.mfd entry in the project window.|
The getCityTime.mfd mapping accepts a city name as input and returns the current time in the output. If the city is not "Boston", a WSDL fault is returned. The mapping takes the input data from the getCityTimeRequest.xml file available in the <Documents>\Altova\MapForce2023\MapForceExamples\TimeService directory. If you double-click the getCityTimeSoapIn component, you can see that this file is set as data source.
For the scope of this example, we will now assume that this particular Web service project has already been compiled and deployed to an actual Web server which you are going to call in the following steps of this example. A demo online service is available for that purpose at http://nanonull.com/TimeService/TimeService.asmx. For examples of how to create such Web services with MapForce, see Example: Generating SOAP Web Services (C#) and Example: Generating SOAP Web Services (Java).
To add the Web service to the mapping:
1.Select File | New, click the Mapping icon and confirm with OK.
2.Select the menu option Insert | Web service function... or click the toolbar button.
3.Click Browse to select the WSDL definition file; select TimeService.wsdl from the TimeService directory, then click the Open button.
4.When prompted to choose a Web service endpoint, click TimeServiceSoap.
5.When prompted to choose a Web service operation, click getCityTime.
6.Leave the WSDL Call Settings unchanged, and click OK. For more information, see Web Service Call Settings.
The getCityTime Web service function is inserted as a single component. Note that it actually represents all eight components that make up the getCityTime.mfd file as saved in the WSDL project.
The left section of the component defines the data input (SoapIn), while the right side defines the data output (SoapOut), which may also include a fault section, if one has been defined in the .wsdl file.
To call the Web service:
1.Insert the component that is to supply the input data, e.g. a constant, text, or schema component. For the scope of this example, insert a constant component, and enter "Boston" as the input string.
2.Connect the constant to the n0:city item.
3.Insert a simple output component (on the Function menu, click Insert Output).
4.Connect the n0:getCityTimeResult to the output component.
5.Right-click the "getCityTime" component on the mapping, and select Properties. The Web Service Call Settings dialog box opens. Enter http://nanonull.com/TimeService/TimeService.asmx in the URL box (this is a demo online Web service created with MapForce, see Implementing SOAP Web Services).
6.Click the Output tab. As illustrated below, the current time in Boston is displayed in the Output pane.
|Note:||The input value of the Web service function takes precedence over the data source of the original mapping. For example, the constant "Boston" takes precedence over the getCityTimeRequest.xml data source file in the original mapping.|
To map Web service faults:
1.Select Insert | Exception, or click the Exception toolbar button .
2.Map the Fault: item to the throw item of the exception component.
3.Map the n0:errorText item to the error-text item of the exception component.