Section 6.2.  SOAP Web services

Prev don't be afraid of buying books Next

6.2. SOAP Web services

In this section, we will see how the letter document utilizes a Web service that, given a U.S. ZIP code, returns the city and state. To do this, we will make use of a separate toolkit provided by Microsoft for dealing with the SOAP interface.

6.2.1 The ZIP code Web service

First, let's take a look at the Web service we will be using for this example. This Web service has several operations related to United States ZIP codes. The one we are going to use is called GetInfoByZIP. Given a ZIP code, this operation returns the city, state, area code and time zone.

The WSDL description of this Web service can be found at: http://www.webservicex.net/uszip.asmx?WSDL

Within the WSDL document, we can see the operation we want. It is shown in Example 6-8.

Example 6-8. WSDL description of a Web service operation
 <operation name="GetInfoByZIP">   <documentation>Get State Code, City, Area Code, Time Zone, Zip Code by Zip Code</documentation>   <input message="s0:GetInfoByZIPSoapIn" />   <output message="s0:GetInfoByZIPSoapOut" /> </operation> 

The operation definition references the input and output messages that are shown in Example 6-9.

Example 6-9. Web service input and output messages
 <message name="GetInfoByZIPSoapIn">   <part name="parameters" element="s0:GetInfoByZIP" /> </message> <message name="GetInfoByZIPSoapOut">   <part name="parameters" element="s0:GetInfoByZIPResponse" /> </message> 

The input and output messages, in turn, refer to the types of element that are sent to and returned from the Web service. An excerpt from the schema definition that declares them is shown in Example 6-10.

Example 6-10. Declarations of message element types
 <s:element name="GetInfoByZIP">   <s:complexType>     <s:sequence>       <s:element minOccurs="0" maxOccurs="1"                  name="USZip" type="s:string" />     </s:sequence>   </s:complexType> </s:element> <s:element name="GetInfoByZIPResponse">   <s:complexType>     <s:sequence>       <s:element minOccurs="0" maxOccurs="1"                  name="GetInfoByZIPResult">         <s:complexType mixed="true">           <s:sequence>             <s:any />           </s:sequence>         </s:complexType>       </s:element>     </s:sequence>   </s:complexType> </s:element> 

According to the schema for the input message, the operation expects to receive a GetInfoByZIP element, which in turn contains a USZip element that contains a string: the ZIP code.

The structure of the output message is unknown, since the schema for the output message does not constrain the content of the GetInfoByZIPResult element. However, by running a test we find that the output looks like Example 6-11.

Example 6-11. XML document returned by ZIP code Web service
 <ws:GetInfoByZIPResponse xmlns:ws="http://www.webserviceX.NET">   <ws:GetInfoByZIPResult>     <NewDataSet>       <Table>         <CITY>Traverse City</CITY>         <STATE>MI</STATE>         <ZIP>49684</ZIP>         <AREA_CODE>616</AREA_CODE>         <TIME_ZONE>E</TIME_ZONE>       </Table>     </NewDataSet>   </ws:GetInfoByZIPResult> </ws:GetInfoByZIPResponse> 

Both the input and output messages are contained in SOAP wrappers when transmitted. Parsing and generating SOAP is best left to specialized software, which is available for the Office products.

6.2.2 The Office Web Services Toolkit

To simplify the use of SOAP Web services with Office, Microsoft provides a separate, downloadable toolkit. The Office Web Services Toolkit frees the developer from generating and parsing SOAP messages, and even from constructing the XML fragments that contain the data sent to and received from the Web service.

For each service, the toolkit generates a class (or classes) that has a method for each of the service's operations. Application code can then be written to access these simplified classes.

At the time of writing, the current version of the toolkit is called Office XP Web Services Toolkit 2.0. It can be downloaded from http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnxpwst/html/odc_wstoolkitoverview.asp.[2]

[2] Although the name of the toolkit implies that it is only for Office XP, it also works with Office 2003 and its name may be changed to reflect this fact.

The toolkit contains documentation and examples, and a tool called the Web Services Reference Tool that is integrated with the Visual Basic Editor.[3]

[3] Installation of the toolkit is in two parts. You must first install the toolkit itself, from the downloaded compressed file. The Web Services Reference Tool is then installed separately from the setup.exe executable file in the directory where you installed the toolkit.

6.2.3 Using the Web Services Reference Tool

The Web Services Reference Tool allows you to generate classes that you can use to access a particular Web service. You can search for a Web service based on keywords, or specify a Web service by its URL.

To launch the Web Services Reference Tool, first open the document from which you will be calling the Web service. To use our form letter example:

1. Open the document letter.xml.

2. On the Tools menu, point to Macro, then click Visual Basic Editor. This will open the Visual Basic Editor.

3. Launch the Web Services Reference Tool by clicking Web Services References on the Tools menu. This brings up the main dialog shown in Figure 6-2.

Figure 6-2. The Web Services Reference Tool




4. In our case, we already know the particular Web service we want to use, so we can go directly to it. Click Web Service URL on the left side of the dialog.

5. Type the Web service location http://www.webservicex.net/uszip.asmx?WSDL into the URL box and click Search.

6. This will bring up the name of the Web service and its operations on the right side of the dialog, as shown in Figure 6-3.

Figure 6-3. The Web Services Reference Tool showing available services and operations




7. Select the USZip service by checking the box next to it and click Add. This will generate the necessary class in the Visual Basic Editor.

6.2.4 Working with the generated Web service class

The generated class named clsws_USZip represents the Web service. It has a method called wsm_GetInfoByZIP, which corresponds to the GetInfoByZIP operation of the Web service. You can write a GetCityState method that calls the wsm_GetInfoByZIP method, as shown in Example 6-12.

Example 6-12. GetCityState method
 Sub GetCityState() Const xmlnsLetter =   "xmlns:let='http://xmlinoffice.com/letter'" Dim objResolver As clsws_USZip Set objResolver = New clsws_USZip Dim returnedNodes As MSXML2.IXMLDOMNodeList Dim str_city As String Dim str_state As String Dim city_node As XMLNode Dim state_node As XMLNode Dim zip_node As XMLNode Set city_node =   ActiveDocument.SelectSingleNode("//let:city", xmlnsLetter) Set state_node =   ActiveDocument.SelectSingleNode("//let:state", xmlnsLetter) Set zip_node =   ActiveDocument.SelectSingleNode("//let:zip", xmlnsLetter) Set returnedNodes = objResolver.wsm_GetInfoByZIP(zip_node.Text) str_city = returnedNodes.Item(0).SelectSingleNode("//CITY").Text str_state = returnedNodes.Item(0).SelectSingleNode("//STATE").Text city_node.Text = str_city state_node.Text = str_state End Sub 

  • Lines 3 through 12 define all the constants and variables used.

  • Lines 14 through 19 locate the city, state and ZIP nodes in our letter document, which are relevant to the Web service.

  • Line 21 calls the wsm_GetInfoByZIP method, passing it the ZIP code. Rather than returning the whole SOAP message that contains the document shown in Example 6-11, the method extracts the relevant returned data, namely the NewDataSet element. This is represented as a variable called returnedNodes, which is a list of nodes of type IXMLDOMNodeList.

  • Lines 23 and 24 assign the values of the CITY and STATE elements to two string variables.

  • Lines 25 and 26 then assign these string values to the appropriate nodes in our letter document.

Warning

The Office Web Services toolkit is very useful for simple examples like this one. It has a number of limitations that prevent it from working without modifications on all Web services. For example, it can't handle element-type names that are also Visual Basic reserved words, and it doesn't support extensions in the XML Schema types defined in the WSDL. However, it can generate a starting point, which you can tweak for your Web service.




6.2.5 Responding to two variations of an event

In 6.1.3, "Responding to an event", on page 121 we saw how external data could be updated automatically when a corresponding field in the document was changed. The technique works the same way when the external data is provided by a Web service.

In fact, you can use the same code as we did in Example 6-15. The only difference is that you would replace:

Example 6-13. Test for change in customer
 ElseIf OldXMLNode.BaseName = "customer" Then     GetAddress 

with:

Example 6-14. Test for change in zip
 ElseIf OldXMLNode.BaseName = "zip" Then     GetCityState 

If you wanted automatic updates for both situations, you could use both tests at once, as shown in Example 6-15.

Example 6-15. Responding to two kinds of XMLSelectionChange event
 Dim WithEvents oApp As Word.Application Private Sub Document_Open()     Set oApp = Application End Sub Private Sub oApp_XMLSelectionChange   (ByVal Sel As Word.Selection,    ByVal OldXMLNode As Word.XMLNode,    ByVal NewXMLNode As Word.XMLNode,    Reason As Long)     If OldXMLNode Is Nothing Then         'do nothing     ElseIf OldXMLNode.baseName = "customer" Then         GetAddress     ElseIf OldXMLNode.BaseName = "zip" Then         GetCityState     End If End Sub 

After saving this project and closing and reopening the letter.xml document, you will find that every time you change the ZIP code, the city and state will automatically be updated. Similarly, every time you change the customer its address will be updated.

Amazon


XML in Office 2003. Information Sharing with Desktop XML
XML in Office 2003: Information Sharing with Desktop XML
ISBN: 013142193X
EAN: 2147483647
Year: 2003
Pages: 176

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net