SOAP Samples

SOAP in the real world

By Kevin M Schreiner

February 13, 2010

This article covers four examples, demonstrating two web services. The first, a Non-Microsoft based WSDL, and the second a Microsoft base WSDL. The Non-Microsoft based example interacts with: "http://ec.europa.eu/taxation_customs/vies/api/checkVatPort?wsdl", demonstrating a quick way to poll the service for the desired interaction. Once the correct structure is identfied for using the service, the demonstration continues, reaching the limitation of the INPUT Action, and the best approach for the interaction is identified as an XML Query. The Second Sample will teach the developer the best way to interact with a standard SOAP service using an XML Query.

The third and fourth samples provide interaction with a Microsoft based Web Service, complete with developer WSDL instruction. The two samples will again cover the Input Action and XML Query, providing both XML Query to DataSet directly as well as XML Query to manual Row/Column mapping.

SOAP with Non-Microsoft based WSDL

  1. Using a free online tool for retrieving the SOAP Request and Response Body in XML format: http://www.soapclient.com/soaptest.html
    Enter the URL of our SOAP resource: http://ec.europa.eu/taxation_customs/vies/api/checkVatPort?wsdl

  2. Click Retrieve and examing the capabilities identified by the result. Our INPUT action will require the BODY of the Envelope expected from interaction with the service. Enter the parameters for the VAT service request, provided in this screenshot, change the "Show" to Request and the "Format" to XML.
  3. Click Invoke, and review the XML result. This is the BODY of the envelope which will need to be sent. In the case of the checkVatService call:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="urn:ec.europa.eu:taxud:vies:services:checkVat" xmlns:intf="urn:ec.europa.eu:taxud:vies:services:checkVat" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns1="urn:ec.europa.eu:taxud:vies:services:checkVat:types" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
        <SOAP-ENV:Body>
            <mns1:checkVat xmlns:mns1="urn:ec.europa.eu:taxud:vies:services:checkVat">
                <countryCode>GB</countryCode>
                <vatNumber>802311782</vatNumber>
            </mns1:checkVat>
        </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

  4. Set the URL of the Input Action to "http://ec.europa.eu/taxation_customs/vies/api/checkVatPort"
  5. Set the Authentication to None, as none are required for this service.
  6. Leave  the Content Type and Headers blank.
  7. Enter the provided content as the Body of the Input Action as seen in Step #3.
  8. Set the Method to SOAP
  9. Assign the Soap Action to the name of the executing command in Double Quotes (these are REQUIRED). In this case, "checkVat".
  10. Next, Test the service, use the following settings. These will skip further processing of the result, instead assigning an Action Variable with the name "TEST" the entire result of the request.
    1. Soap Result Tag - leave blank.
    2. Response Format - Text
    3. Variable Type - Action
    4. Name - TEST
  11. To test this configuration, add a Detail Template (No Query) to the Action block, with the content "[FORMAT,TEST,Action,{ENCODEHTML}]". This will format the TEST action variable, HTML encoding the value so that it appears visually in the result, otherwise the source would need to be reviewed because XML syntax would be stripped out. The final action block will appear like this:
  12. Save/Publish and then review the result of the test, the TEST action is rendered directly into the output, and should contain a body similar to this:

    <?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <soapenv:Body>
            <checkVatResponse xmlns="urn:ec.europa.eu:taxud:vies:services:checkVat">
                <countryCode xmlns="">GB</countryCode>
                <vatNumber xmlns="">802311782</vatNumber>
                <requestDate xmlns="">2010-02-13</requestDate>
                <valid xsi:type="xsd:boolean" xmlns="">true</valid>
                <name xmlns="">NAKLAB LIMITED</name>
                <address xmlns="">FLAT 50
                    ARGUS LOFTS
                    ROBERT STREET
                    BRIGHTON
                    EAST SUSSEX
                    BN1 4AY
                </address>
            </checkVatResponse>
        </soapenv:Body>
    </soapenv:Envelope>
  13. Next, we will more than likely need to digest this XML result a bit further, obtaining the elements separatly. The Inpu Action facilitates this capability, however you will find in the next sample that the XML Query is Far superior in the ability to control the retrieved elements.
  14. Examining the Response, we experience a limitation due to the assignment of an XML namespace to the returned object. Therefore, any further processing of this result would require extended capability not provided by the Input Action. Meanwhile, the Query Action supports further breakdown of this response because it supports the ability to define expected Namespaces. Additionally the Query supports the ability to break the exposed structure into multiple Rows and Columns.
  15. Using the information we have already garnered from the previous steps, and a further understanding of the anticipated result - Delete the existing actions and instead add a Query Template and a Detail Template.
  16. Edit the Query Template, and click the Query Tab within the Editor. Select XML from the tab group, inserting the entire XML block structure into the provided Query Editor.


  17. Begin by setting the PATH node to the following:
    <PATH>http://ec.europa.eu/taxation_customs/vies/api/checkVatPort</PATH>
  18. Next, eliminate the section following: "<!---USE ONE OF THE FOLLOWING: VALUE,POST,GET,PUT,DELETE,SOAP-->" until "<!-- -->". We will not need the VALUE,POST,GET,PUT or DELETE. Leave the SOAP tag followed by the rest of the XML intact. The content should now look something like this:
    <XML>
        <PATH>http://ec.europa.eu/taxation_customs/vies/api/checkVatPort</PATH>
        <SOAP>
            <CONTENTTYPE></CONTENTTYPE>
            <ACTION></ACTION>
            <HEADERS></HEADERS>
            <BODY></BODY>
        </SOAP>
        <AUTHENTICATION>
  19. Next, fill in the required SOAP values, just as we had provided in the previous steps. In this case CONTENTTYPE should be set to text/xml. The ACTION must be set to "checkVat", and the HEADERS tag can be deleted. Finally, set the body to the content exactly as it appears in step #3. No escaping is required here, as the XML query uses an XML-like structure, but uses a rapid parsing logic which doesn't operate the way standard XML readers execute.

    <XML>
        <PATH>http://ec.europa.eu/taxation_customs/vies/api/checkVatPort</PATH>
        <SOAP>
            <CONTENTTYPE>text/xml</CONTENTTYPE>
            <ACTION>"checkVat"</ACTION>
            <BODY>
                <?xml version="1.0" encoding="UTF-8" standalone="no"?>
                <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="urn:ec.europa.eu:taxud:vies:services:checkVat" xmlns:intf="urn:ec.europa.eu:taxud:vies:services:checkVat" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns1="urn:ec.europa.eu:taxud:vies:services:checkVat:types" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
                    <SOAP-ENV:Body>
                        <mns1:checkVat xmlns:mns1="urn:ec.europa.eu:taxud:vies:services:checkVat">
                            <countryCode>GB</countryCode>
                            <vatNumber>802311782</vatNumber>
                        </mns1:checkVat>
                    </SOAP-ENV:Body>
                </SOAP-ENV:Envelope>
            </BODY>
        </SOAP>
        <AUTHENTICATION>


  20. Next, eliminate the AUTHENTICATION section. This would provide the ability to use standard Authentication mechanisms against the service, which for this service are not required.
  21. Additionally, eliminate the TRANSFORM and ROWS elements. TRANSFORM will not be necessary in this sample, and ROWS will be added below the next section as it is logically out of order in this location.
  22. The response that is expected from the service (review Step #9) contains a specific definition of Namespaces (nodes appearing with xmlns:???? within the XML). Each of the namespaces will require definition for the XML Reader to properly locate and parse the incoming XML. The Prefix of each namespace is the region that appears after the colon and before the equal sign. The URI of the Namespace appears within the quotes. In our sample this identifies the following:

    <NAMESPACE>
        <PREFIX>soapenv</PREFIX>
        <URI>http://schemas.xmlsoap.org/soap/envelope/</URI>
    </NAMESPACE>
    <NAMESPACE>
        <PREFIX>xsd</PREFIX>
        <URI>http://www.w3.org/2001/XMLSchema</URI>
    </NAMESPACE>
    <NAMESPACE>
        <PREFIX>xsi</PREFIX>
        <URI>http://www.w3.org/2001/XMLSchema-instance</URI>
    </NAMESPACE>


  23. Additionally, the "checkVatResponse" node also requires a DEFAULT namespace as it identifies xmlns="....". The XML Query Requires a default namespace, as indicated in the inline instructions. Therefore one additional Namespace is required, any prefix is allowed here, and will be needed for the ROWS XPATH. For this demonstration we will use "def" as the prefix, and the URI can be "urn:ec.europa.eu:taxud:vies:services:checkVat", taken from Step #9. The end result of the NAMESPACES tag should be as follows:
    <NAMESPACES>
        <NAMESPACE>
            <PREFIX>soapenv</PREFIX>
            <URI>http://schemas.xmlsoap.org/soap/envelope/</URI>
        </NAMESPACE>
        <NAMESPACE>
            <PREFIX>xsd</PREFIX>
            <URI>http://www.w3.org/2001/XMLSchema</URI>
        </NAMESPACE>
        <NAMESPACE>
            <PREFIX>xsi</PREFIX>
            <URI>http://www.w3.org/2001/XMLSchema-instance</URI>
        </NAMESPACE>
        <NAMESPACE>
            <PREFIX>def</PREFIX>
            <URI>urn:ec.europa.eu:taxud:vies:services:checkVat</URI>
        </NAMESPACE>
    </NAMESPACES>
  24. Next, identify the ROW XPATH. This is the XPATH which is executed against the result to identify the Row or Rows of Data which are contained within the document. In this case, there will only be one row, and the XPATH will look like the following (consuming "def" as we identified in the previous step):
    <ROWS>/soapenv:Envelope/soapenv:Body/def:checkVatResponse</ROWS>
  25. Finally, the COLUMNS must be defined, providing the Name of the column as it will appear in the Query result, and the XPATH used to pull the value of that Column from the ROW. In this example we are retaining the Name out of preference:
    <COLUMNS>      
        <COLUMN>
            <NAME>countryCode</NAME>
            <XPATH>countryCode</XPATH>
        </COLUMN>
        <COLUMN>
            <NAME>VatNumber</NAME>
            <XPATH>vatNumber</XPATH>
        </COLUMN>
        <COLUMN>
            <NAME>requestDate</NAME>
            <XPATH>requestDate</XPATH>
        </COLUMN>
        <COLUMN>
            <NAME>valid</NAME>
            <XPATH>valid</XPATH>
        </COLUMN>
        <COLUMN>
            <NAME>name</NAME>
            <XPATH>name</XPATH>
        </COLUMN>
        <COLUMN>
            <NAME>address</NAME>
            <XPATH>address</XPATH>
        </COLUMN>
    </COLUMNS>
  26. The final XML Query logic should appear like this:
    <XML>
        <PATH>http://ec.europa.eu/taxation_customs/vies/api/checkVatPort</PATH>
        <SOAP>
            <CONTENTTYPE>text/xml</CONTENTTYPE>
            <ACTION>"checkVat"</ACTION>
            <BODY>
                <?xml version="1.0" encoding="UTF-8" standalone="no"?>
                <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:apachesoap="http://xml.apache.org/xml-soap" xmlns:impl="urn:ec.europa.eu:taxud:vies:services:checkVat" xmlns:intf="urn:ec.europa.eu:taxud:vies:services:checkVat" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns1="urn:ec.europa.eu:taxud:vies:services:checkVat:types" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:wsdlsoap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
                    <SOAP-ENV:Body>
                        <mns1:checkVat xmlns:mns1="urn:ec.europa.eu:taxud:vies:services:checkVat">
                            <countryCode>GB</countryCode>
                            <vatNumber>802311782</vatNumber>
                        </mns1:checkVat>
                    </SOAP-ENV:Body>
                </SOAP-ENV:Envelope>
            </BODY>
        </SOAP>
        <NAMESPACES>
            <NAMESPACE>
                <PREFIX>soapenv</PREFIX>
                <URI>http://schemas.xmlsoap.org/soap/envelope/</URI>
            </NAMESPACE>
            <NAMESPACE>
                <PREFIX>xsd</PREFIX>
                <URI>http://www.w3.org/2001/XMLSchema</URI>
            </NAMESPACE>
            <NAMESPACE>
                <PREFIX>xsi</PREFIX>
                <URI>http://www.w3.org/2001/XMLSchema-instance</URI>
            </NAMESPACE>
            <NAMESPACE>
                <PREFIX>def</PREFIX>
                <URI>urn:ec.europa.eu:taxud:vies:services:checkVat</URI>
            </NAMESPACE>
        </NAMESPACES>
        <ROWS>/soapenv:Envelope/soapenv:Body/def:checkVatResponse</ROWS>
        <COLUMNS>      
            <COLUMN>
                <NAME>countryCode</NAME>
                <XPATH>countryCode</XPATH>
            </COLUMN>
            <COLUMN>
                <NAME>VatNumber</NAME>
                <XPATH>vatNumber</XPATH>
            </COLUMN>
            <COLUMN>
                <NAME>requestDate</NAME>
                <XPATH>requestDate</XPATH>
            </COLUMN>
            <COLUMN>
                <NAME>valid</NAME>
                <XPATH>valid</XPATH>
            </COLUMN>
            <COLUMN>
                <NAME>name</NAME>
                <XPATH>name</XPATH>
            </COLUMN>
            <COLUMN>
                <NAME>address</NAME>
                <XPATH>address</XPATH>
            </COLUMN>
        </COLUMNS>
    </XML>
  27. Next, add a Detail action and open the Editor. The detail action will consume the results from the XML Query against the SOAP service. To test the result of he service, use a Detail value similar to the following:
    <table>
        <tr>
            <td>CountryCode</td>
            <td>[CountryCode]</td>
        </tr>
        <tr>
            <td>VatNumber</td>
            <td>[VatNumber]</td>
        </tr>
        <tr>
            <td>RequestDate</td>
            <td>[RequestDate]</td>
        </tr>
        <tr>
            <td>Valid</td>
            <td>[Valid]</td>
        </tr>
        <tr>
            <td>Name</td>
            <td>[Name]</td>
        </tr>
        <tr>
            <td>Address</td>
            <td>[Address]</td>
        </tr>
    </table>
  28. This is how the resulting action block should appear:

This wraps up the example. As was demonstrated the INPUT action works, and depending on the source itself the capabilities are limited by the resulting XML block. With that limitation, the XML Query structure by far exceeds the capability of the Input action, allowing the developer to not only retrieve the block into a more malleable fashion, but bind to it as a standard Query result like any other query within OWS.

« Prev Page |1|2|Next »
Average ( Ratings):
 
Want to help out?
 
 

New York, NY • Baltimore, MD • Vienna, VA • St. Louis, MO • Seattle, WA • info@openwebstudio.com

Bookmark & Share Bookmark and Share