Working with SOAP Services

Introduction

Many web services still use the SOAP interface, which requires you to post an XML request to the service. FME can interact with SOAP services with the following combination of transformers:

• XMLTemplater - to create the XML request.

• HTTPCaller - to POST the request to the service.

• XMLFragmenter - to break the response into separate features (if needed) and flatten the response information into feature attributes.

Step-By-Step Instructions

Part 1: Prototyping SOAP Calls

Sometimes the SOAP API documentation will show you sample XML for each of the requests, but often these are specified only in a WSDL file. FME cannot interpret these files, so we recommend using the free utility SoapUI (www.soapui.org). SoapUI will create sample requests for all the operations specified in the WSDL file and can be used to test requests before copying them into your workspace.

1. Download a SOAP Utility

In this example, we will be using the SoapUI utility program, which is a free open source download. You can use whichever API utility you like as long as it can create SOAP projects.

2. Create a New SOAP Project

Once you have downloaded and installed SoapUI, open the program and then go to File > New SOAP Project.

In the New SOAP Project dialog, enter CountryInfoService as the Project Name and for the Initial WSDL paste in the following URL:

http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL

Ensure that Create Requests: Create sample requests for all operations is enabled and then click OK.

3. View Requests

After clicking OK to set up the project, you will see the available requests in the Project navigator window.

In this case, we have lots of requests, but we are only interested in one. Scroll down until you find FullCountryInfo and click the plus sign to expand it. Double-click on Request 1 to create a request template.

4. Create Request

After double-clicking, a Request 1 window will appear. In that window, find the ? between the sCountryISOCode and then enter any ISO code you desire. A list of ISO codes can be found here.

In this example, we are using CAN for Canada. Once you’ve entered your ISO code, click the green play button in the top corner of the Request 1 window to submit the request.

The response returned will list all of the tags within the FullCountryInfo request for the specified ISO code.

You can switch to the Raw view to see what the response will look like when submitted by FME.

In this case, the response is several nested XML tags containing information about the country. We will use FME to extract the individual tags into separate attributes.

Now that we have generated and tested the request in SoapUI, we are ready to copy it to our FME workspace.

Part 2: Working with SOAP in FME

1. Create a Blank Workspace and Add a User Parameter

Start FME Workbench and create a new blank workspace. In the Navigator window, right-click on Published Parameters and choose Create User Parameter.

Enter the following parameters into the Add/Edit User Parameter dialog:

Type: Text

Name: CountryISO

Prompt: Enter 3 digit country ISO code:

Default Value: Leave blank

Published: Checked

Optional: Unchecked

2. Add a Creator and an XMLTemplater Transformer

Add a Creator transformer to the canvas, which will create the request feature. Then add an XMLTemplater transformer, which will specify the request.

Open the XMLTemplater parameters and click the ellipsis button next to Template. Copy the Request XML from the SoapUI into the ROOT Template Expression dialog.

Note: There is a known issue that may prevent direct copy and paste from SoapUI into FME. To get around this, paste from SoapUI into an external text editor, then re-copy it and paste it into FME.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:web="http://www.oorsprong.org/websamples.countryinfo">
   <soapenv:Header/>
   <soapenv:Body>
      <web:FullCountryInfo>
         <web:sCountryISOCode>?</web:sCountryISOCode>
      </web:FullCountryInfo>
   </soapenv:Body>
</soapenv:Envelope>

Next, highlight the ? ISO value (or CAN) inside the web:sCountryISOCode tag, then click on the Published Parameters on the left side and double-click the CountryISO parameter. This will replace the ISO code with $(CountryISO). At runtime, this will be replaced by the ISO code set by the user in the published parameter.

Click OK twice to exit the dialog and the XMLTemplater parameters.

3. Make the Request in the HTTPCaller

Now that the request is created, we will use an HTTPCaller transformer to submit it to the service. Add an HTTPCaller to the canvas and connect the XMLTemplater to it. Open the HTTPCaller properties.

In the properties, set the Request URL to:

http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL

Then set the HTTP Method to POST. It is important that we set it to post, even if we aren’t supplying a parameter (like the ISO Code). This is because the Soap service needs the XML request to be sent in order for it to return a value. If you were to GET the value, only the schema will be returned.

Once you switch the HTTP Method to POST, the Body section now becomes available. Expand Body, then set the Upload Body to _result, this attribute comes from the XMLTemplater. Finally, set the Content Type to SOAP XML (application/soap+xml), this setting will ensure that the HTTPCaller treats the call as SOAP, rather than plain text.

There may be other parameters required by your specific SOAP request. To find this out, switch to the Raw section in SoapUI, and if there is a SOAPAction, this can be created in the Header section. This is not required for our URL.

4. Fragment XML and Extract Attributes

If you inspect the data and view the _response_body from the HTTPCaller, the data will still look like it did when we viewed in it SoapUI, which isn’t very helpful. To make the data more readable and split it into attributes, we will need to fragment and flatten the XML.

Add an XMLFragmenter to the canvas and connect it to the Output port on the HTTPCaller. In the parameters, change the XML Source Type to Attribute with XML Document, and then set the XML Attribute to _response_body.

Now we need to determine the Elements to Match, this can be a bit tricky and depends on how detailed you want your output data to be. If we switch back to SoapUI and look at our response, we can see that there are nested tags underneath m:FullCountryInfoResult, so this is what we will use. If we were only interested in a different tag or nest, we would choose that.

Back in the XMLFragmenter in FME, type in FullCountryInfoResult in the Elements to Match text box.

Next, click on the Options button next to Flatten Options and check Enable Flattening, click OK to close the XML Flattening Options dialog.

Finally, we need to extract the attributes we want to display. You can do this within the XMLFragmenter or by using an AttributeExposer transformer. For this example, we will stay in the XMLFragmenter.

Expand Expose Attributes and then click on the ellipsis next to Attributes to Expose. In the Enter Values for Attributes to Expose dialog, enter the following attributes (be aware of spelling and capitalization):

• sName

• sISOCode

• sCapitalCity

• sPhoneCode

• sContinentCode

• sCurrencyISOCode

These attributes can be found in the response in SoapUI. We will remove the leading s while cleaning up the attributes in the next step.

Note: If you want to expose the m:tLanguages, you will need to further fragment and flatten that section using another XMLFragmenter.

Click OK twice to close the XMLFragmenter.

5. Clean Up Attributes

We have created some additional attributes throughout this workspace that we will not need in the final output. The only attributes we are interested in keeping are the ones we exposed in the XMLFragmenter. Add an AttributeRemover transformer to the canvas and connect it to the Fragments output port on the XMLFragmenter. In the AttributeRemover parameters, click on the ellipsis for Attributes to Remove and select all the attributes that start with xml or an underscore _.

Once we have removed the attributes we don’t need, we need to remove that leading s on the ones we do want to keep. Add a BulkAttributeRenamer transformer to the canvas and connect it to the AttributeRemover. In the parameters, set the Action to Remove Prefix String and then type s in the String box.

6. Save and Run Workspace

The workspace is now complete and should look like the image below. You can add a writer if you wish or enable feature caching to view the results.

Be sure to save the workspace and enable Prompt for User Parameters, once that is enabled run the workspace. In the Translation Parameter Values prompt enter in a 3 digit ISO country code to test out the workspace.

Once the workspace has finished running, click on the feature cache on the BulkAttributeRenamer to view the result in Visual Preview.

Data Attribution

The data used in this article came from Orrspong.org. Please note that this is a live dataset that can be changed, or stop working at any time.