Altova MapForce 2024 Enterprise Edition

Navigation: Transformation Components > Web Services > SOAP Web Service Projects

Create SOAP Web Service Project

This topic covers Step 1 described in SOAP Web Service Configuration and explains how to create a SOAP Web service in MapForce. All the files discussed in this topic are available in the Tutorial folder. The goal of this SOAP Web service is to retrieve Author records from an XML file, which satisfy certain search criteria.

Important points

Note the following points:

•The process of creating a Web service in MapForce does not depend on the target programming language. The differences arise only when you compile the Web service and deploy it to a web server.

•For a Web service, you can generate Java or C# code.

•In our example, we use Altova XMLSpy to generate sample SOAP requests, which allows us to preview the output. Designing Web services in MapForce is also possible without XMLSpy; however, in this case you will need a SOAP client that can generate SOAP requests from WSDL files.

Create a Web service project: Broad procedures

Creating a SOAP Web service project in MapForce involves the following steps:

1.The first step is to prepare a WSDL (Web Services Description Language) file that describes the service's structure, operations, input/output parameters, and the protocol for communication. In this example, we used Altova XMLSpy to create a WSDL file. For more information about WSDL documents, see the WSDL Specification.

2.The second step is to create a new Web service project in MapForce, which will be based on the WSDL file. In this step, we also import the WSDL file into MapForce and give our project a name. The project with its contents will appear in the Project window.

3.At the next stage, we design a getAuthor operation, which involves adding an XML file, from which Author records will be retrieved, and setting a filter, which will ensure that only the relevant data will be mapped to the response structure.

4.In the last step of the Web service configuration, we can preview the output of the Web service before actually deploying the service to the server. To be able to preview the output, we will supply a sample SOAP request, which contains a search query and which will later be sent to the server hosting the Web service.

Step 1: Prepare a WSDL file

The image below illustrates the structure of the WSDL document called getAuthor.wsdl (WSDL view of XMLSpy). One operation called getAuthor has been defined. For more information about the structure of a WSDL file, see WSDL Document Structure. For instructions on how to create a WSDL document in Altova XMLSpy, see the WSDL Tutorial section.

Note that to be able to create a MapForce service project, you must supply a valid WSDL file.

Response structure

It is important to note that we have modified the WSDL file in the Text view of XMLSpy to include the following structure in the response message:

<xsd:complexType name="Author">

<xsd:sequence>

<xsd:element name="Name" type="xsd:string"/>

<xsd:element name="Country" type="xsd:string"/>

<xsd:element name="Website" type="xsd:string"/>

<xsd:element name="Publication" maxOccurs="unbounded">

<xsd:complexType>

<xsd:sequence>

<xsd:element name="Title" type="xsd:string"/>

<xsd:element name="ISBN" type="xsd:string"/>

<xsd:element name="Publisher" type="xsd:string"/>

<xsd:element name="PrintLength" type="xsd:integer"/>

<xsd:element name="Year" type="xsd:integer"/>

<xsd:element name="Genre" type="xsd:string"/>

<xsd:element name="Price" type="xsd:integer"/>

</xsd:sequence>

<xsd:attribute name="ID" use="required"/>

</xsd:complexType>

</xsd:element>

</xsd:sequence>

<xsd:attribute name="ID" use="required"/>

</xsd:complexType>

This structure will be visible in the target Web service component (see Step 2 below), and the result of the query will be mapped to this structure.

Step 2: Create a Web service project

To create a Web service project in MapForce, follow the steps below:

1.Click New in the File menu or the toolbar button and select Web Service Project.

2.Browse for the getAuthor.wsdl file. After you select the WSDL file, MapForce automatically fills in the remaining fields (screenshot below).

3.Click OK.

4.When prompted, enter the name of the new WSDL project (getAuthor in our example) and click Save.

The Project window now displays the project that contains the WSDL file, port, operations, and a mapping associated with this service (screenshot below).

Step 3: Design a getAuthor operation

As soon as you have created your project, a new mapping called getAuthor.mfd becomes available in the Project window. Double-click this mapping to add it to the mapping area. At this stage, the mapping contains two Web service components: getAuthor (Input) and getAuthor (Output) (screenshot below).

The getAuthor (Input) component contains the Query part which will be used to query an XML file through the Web service. The getAuthor (Output) component includes the Author structure defined in the WSDL file (Response Structure above). No other components or connections exist at this stage.

Add Authors.xml

The next step is to add an XML file called Authors.xml, from which data will be retrieved. Add Authors.xml to the mapping and connect the nodes as shown in the screenshot below.

The connection between the part:Query and part:Result nodes represents the Web service call. The data in Authors.xml is passed to the Author element of the getAuthor output component.

Set a filter

The next step is to set a filter on the connection between the Author elements. To set a filter, right-click the connection between the Author elements and select Insert Filter from the context menu. We also need to add the equal function, whose result will be supplied to the Boolean parameter of the filter (screenshot below). The equal function will compare the query string with the value of the Website element of each author. If the value of the Website element of an Author record coincides with the query string, this Author record will be mapped to the target Web service component.

Preview output

Mappings created from WSDL files can be previewed in MapForce before the service is deployed to an actual Web server. To be able to preview such mappings, you must supply a sample SOAP request (in XML format) which conforms to the WSDL file. You can create a sample SOAP request for each operation with Altova XMLSpy or another SOAP client of your choice.

If you use XMLSpy, open getAuthor.wsdl and click the menu command SOAP | Create New SOAP Request. The next step is to add the SOAP request file to the mapping. Follow the steps below:

1.Double-click the header of the getAuthor (Input) component. This will open the Component Settings dialog (screenshot below).

2.If you already have a sample SOAP request file, click Browse and select the relevant file. If XMLSpy is installed alongside MapForce, you can create a sample request directly from MapForce by clicking Create. When you click Create, you will be prompted to give a new request file a name and select a folder for this file. After this, you will be redirected to XMLSpy, in which you will need to type a sample query string and save your request file.

3.Click OK in the Component Settings.

getAuthorRequest.xml

For this example, we have created a request file called getAuthorRequest.xml in XMLSpy (code listing below). This request file will be imported into the mapping, which will enable us to preview the output. The request file contains the search string Iceland. The filter will run through all the authors, and if there are authors from Iceland in Authors.xml, these authors' records will be mapped to the response structure.

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<SOAP-ENV:Body>

<Query xsi:type="xsd:string">Iceland</Query>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Preview output

To see the response message, open the Output pane. The code listing below shows an extract of the response message. Two authors from Iceland have been mapped (countries highlighted yellow below).

<?xml version="1.0" encoding="UTF-8"?>

<soap-env:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap-enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">

<soap-env:Body>

<Name>Ragnar Jonasson</Name>

<Country>Iceland</Country>

<Website>ragnarjonasson.com</Website>

</Author>

<Name>Arnaldur Indridason</Name>

<Country>Iceland</Country>

<Title>The Darkness Knows</Title>

<Publisher>Minotaur Books</Publisher>

<Genre>Crime & Mystery</Genre>

</Publication>

</Author>

</Result>

</soap-env:Body>

</soap-env:Envelope>

Next steps

You are now ready to generate code that implements the Web service (Java or C#), build the code, and deploy the service to a server. For more information, see Generate SOAP Web Service (Java)