Working With Web Services

For the Business Importer to collect data from web services, the following items are required:

• The URL of the web service
• The authentication (if any) required to connect to the web service
• The function of the web service to be called or alternatively the SOAP request
• Whether or not header information is required to call the web service
• The name of the XML element within the response that contains the data.

URL and authentication

With the XML adapter file, the URL and authentication are specified in the ConnectionString attribute of the Import element. The structure is:

ConnectionString="Login=MyLogin;Password=MyPassword;URL=http://MyServer/WebService/MyWebService.asmx"

The function call

The function call within the web service is specified in the Query attribute of the Import element. It can be specified in two ways:

• You can provide the name of the function
• You can provide the full SOAP message.

If just the name of the function is defined, a standard SOAP request is built and forwarded to the web service. For example, if the following function name is specified:

Query="GetAllPurchaseOrders"

the following SOAP request is built and transmitted:

<?xmlversion="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>
		<GetAllPurchaseOrdersxmlns=\"http://tempuri.org/" />
	</soap:Body>
</soap:Envelope>

Alternatively, if the soap request requires different syntax or parameters, the full SOAP request can be specified in the Query attribute of the Import element. The above SOAP request could be represented in the following way. Note the need to escape various characters in the mark-up as XML entities. This value has been wrapped to show similarity with the example above:

Query="<?xml version="1.0" 
	encoding="utf-8"?> 
	<soap12:Envelope 
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
		xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
		xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
		<soap12:Body>
			<GetAllPurchaseOrders xmlns="http://tempuri.org/" />
		</soap12:Body>
</soap12:Envelope>"

Supplying header information

If header information is required by the web service, use the SOAPHeaderValues attribute of the Import element to specify the header information. For example:

SOAPHeaderValues="SOAPAction=http://MyServer/WebService/GetAllPurchaseOrders"

Decoding the reply

When a response is received from the web service, it includes the full SOAP message made up of multiple XML elements. The Business Importer does not know which of these many elements contains the required data. There are three approaches to solving this dilemma:

• The SOAPElement attribute of the Import element lets you specify the name of the element containing the required data.
• If SOAPElement is not specified, the Business Importer looks for an element with a name concatenating the function name with the string Result (in the example above, this produces GetAllPurchaseOrderResult).
  Tip: This relies on the Query attribute being used for just the function name rather than the full SOAP request.
• If these approaches are unsuccessful, the Business Importer falls back to using the content of the Body XML element of the response.

If you would like to specify the SOAPElement containing the returned data but do not know its name, the Business Importer with the following command line switches:

/testdb=ImportName /log=debug

These options write the full SOAP answer to the log, where you can analyze it and identify the load-bearing element, plugging its name back into your XM adapter before the next run.