imported>Jason.nicholls: 1 revision

2014-06-26T15:52:07Z

1 revision

← Older revision	Revision as of 15:52, 26 June 2014
(No difference)

imported>David.moore: /* Creating the Data Source */

2013-12-20T20:53:20Z

Creating the Data Source

New page

{{DISPLAYTITLE:Accessing SOAP Web Services}}
[[Category:AppBoard 2.5]]
This document refers to using the XML XSLT Web data adapter to retrieve XML data from supported SOAP web services and make it available in AppBoard.

=== SOAP request overview ===

Prior to configuring the AppBoard Data Adapter, you will need to fully construct the necessary SOAP request envelope that is submitted in the POST body of the HTTP request. This envelope is itself an XML document that conforms to the SOAP XML message format. A simple example follows:

<code>[xml,N]
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
<soap:Header>
</soap:Header>
<soap:Body>
<m:GetStockPrice xmlns:m="http://www.example.org/stock">
<m:StockName>IBM</m:StockName>
</m:GetStockPrice>
</soap:Body>
</soap:Envelope>
</code>

=== SOAP URL and POST body creation ===

The SOAP messages supported by a service are outlined in another XML file, the WSDL (Web Service Definition Language). This can usually be retrieved from the web service directly by adding ?wsdl to the web service URL. For example, a typical SOAP URL would look like http://wowws.comp.com/wowws/query, so http://wowws.comp.com/wowws/query?wsdl would return the definition file.

Unless you are very familiar with SOAP web services, the suggested approach is to use a tool like soapUI (http://www.soapui.org/, select Download Free) or Eclipse to construct the SOAP envelope.

=== Using soapUI ===

After installing soapUI and determining the URL for the web service in question, follow this procedure to constuct the SOAP envelope:

# Select '''File''' => '''New soapUI Project'''
# Enter desired '''Project Name'''
# Enter WSDL URL by "Initial WSDL/WADL" (e.g. http://wowws/comp.com/query?wsdl) and click '''OK'''
# You should see a new entry in the '''Projects''' tree. Select expand the new project and the '''querySoapBinding''' nodes to see a list of method calls supported.
# Double-click '''Request 1''' under the desired method, and you will see an XML body like the one that follows. Edit the parameters as needed, and this is the POST body to use for the XMLWebServiceAdapter Data Source configuration.
<code>[xml,N]
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ext="http://external.wowws.plugin.wow.criticalsoftware.com/">
<soapenv:Header/>
<soapenv:Body>
<ext:queryDetails>

<query>

<applicationId>?</applicationId>

<filter>?</filter>
<login>?</login>
<name>?</name>
</query>
</ext:queryDetails>
</soapenv:Body>
</soapenv:Envelope>
</code>

==== Handling WS security with template ====

If the web service in question requires web service authentication (distinct from Basic Authentication), you will need to either copy a template for the authentication or capture it from the HTTP log inside soapUI. A template for version 1.0 is as follows (replace '''USERNAME''' and '''PASSWORD''' with appropriate values):

<code>[xml,N]
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-10"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>USERNAME</wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"
>PASSWORD</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
</code>

==== Handling WS security with '''soapUI''' ====

To use '''soapUI''', you need to select '''Aut''' at the bottom of the request editor, enter '''Username''' and '''Password''', then run the request using the green arrow at the top of the editor. You can then select '''http log''' at the bottom of soapUI's window and look for the full request body in the debug statements (unfortunately, soapUI does not inject the authentication data into the main editor window).

== Developing the XSLT ==

For instructions on creating the XSLT necessary to parse the SOAP response into AppBoard data, see the [[appboard/2.5/builder/data_sources/web_service/xml-xslt-tutorial|XML XSLT Tutorial]].

== Creating the Data Source ==

# Add a new '''Data Source''' in '''AppBoard'''. Select '''Web Service''' for type and then '''XML XSLT Web'''. Enter a name for the source and click '''Add Data Source'''.

#: 
# Enter the URL to the SOAP web service (e.g. http://wowws.comp.com/vineportalws-dev/query), the path to the stylesheet (e.g. ${application.home}/stylesheets/sample/soap-wowws.xsl), and paste the SOAP envelope into the '''httpPostBody''' field (click ... button first):
#: [[File:File-AB-createSoapDS2.png|600px]]
#: 
# Verify the data types for the data collection(s) and continue configuring the data source and data collection(s) as per other adapters:
#: [[File:File-AB-createSoapDS3.png|600px]]

Appboard/2.5/builder/data sources/web service/xml-xslt-soap - Revision history

imported>Jason.nicholls: 1 revision

imported>David.moore: /* Creating the Data Source */