Edge Documentation

Introduction

The AppBoard XML Web Service Adapter supports data retrieval from HTTP web services that require a single request to retrieve data. XML data returned from the REST service is transformed to the AppBoard internal data structure using XSLT. Hierarchical relationships between XML data elements can be represented within AppBoard through associations within the AppBoard data model. For complete details of XSLT creation, see XMLWebServiceAdapter.

Using the XML Web Service Adapter

The following is an overview of how to use the XML Web Service 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:

[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>

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:

1. Select File => New soapUI Project
2. Enter desired Project Name
3. Enter WSDL URL by "Initial WSDL/WADL" (e.g. http://wowws/comp.com/query?wsdl) and click OK
4. 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.
5. 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.

[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>

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):

[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>

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 XMLWebServiceAdapter.

Creating the Data Source

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

   
   

   
   

2. 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):

   
   

   
   

3. Verify the data types for the data collection(s) and continue configuring the data source and data collection(s) as per other adapters: