9.7 Using Web Services in Word

Word uses the same facilities as Excel and Access, though it's a bit tougher to see how web services fit with Word. Unlike spreadsheets or databases, word processors rarely have discrete fields for entering particular data, and users don't typically expect calculations to happen (except perhaps for spell-checking) as they work on a document. Still, if you're reading this section you may have a critical use case in mind, so it's worth exploring how to integrate web services with Word.

One new feature of Word, the Research Pane, makes heavy use of web services. Unfortunately, it does so by requiring people who want to provide information to the Research Pane to create web services that meet the pane's expectations. Creating web services is far beyond the scope of this book, but a tutorial on creating services for the Research Pane with Visual Studio.NET is available at http://www.devx.com/codemag/Article/18214?trk=DXRSS_XML.

To demonstrate, the example uses a form letter, combining some regular text with text form fields entered from Word's Forms Toolbar. (The Insert Fields menu option only lets you enter fields with calculated values, so the Forms Toolbar is definitely the way to go.) The form letter looks like Figure 9-23; hopefully your own form letter will be slightly more normal.

Figure 9-23. Adding the USZip service to the Word document

Making this into a SOAP web service-consuming document requires using the Microsoft Office Web Services Toolkit. Just as in Excel and Access, go to Tools Macros Visual Basic Editor (or Alt-F11). Once in the Visual Basic Editor, go to Tools Web Services References . . . . As shown in Figure 9-24, enter the web service URL http://webservicex.net/uszip.asmx?WSDL, and click Add.

Figure 9-24. Entering code for field activity

Unlike Access or Excel, you'll need to add the code in the Visual Basic Editor directly, in the Project for this document Project (Conspiracy) in this case in "Microsoft Word Objects," "This Document," as shown in Figure 9-25.

The actual code is that in Example 9-7, which again resembles Examples 9-5 and 9-2.

Example 9-7. Code for putting information retrieved from a web service into Word forms

Sub zipCodePlacer( )       Dim zip As String      zip = ActiveDocument.Fields(5).Result.Text      Dim zipResolver As clsws_USZip   Set zipResolver = New clsws_USZip        Dim returnedNodes As MSXML2.IXMLDOMNodeList        'Send the web service the text value of the ZIPCode field   Set returnedNodes = zipResolver.wsm_GetInfoByZIP(zip)      ActiveDocument.Fields(3).Result.Text = _       returnedNodes.Item(0).SelectSingleNode("//CITY").Text   ActiveDocument.Fields(3).Update      ActiveDocument.Fields(4).Result.Text = _       returnedNodes.Item(0).SelectSingleNode("//STATE").Text   ActiveDocument.Fields(4).Update End Sub

This time the integration is with Word's form fields, accessible by number through the ActiveDocument.Fields( ) collection. The zip argument comes from field number 5 (Word counts fields from 1, not zero), and the results go into fields 3 and 4. This code still needs to be connected to the field for the Zip Code. To do that, right-click on the field and select Properties. From the Run Macro on Exit drop-down box, select zipCodePlacer, as shown in Figure 9-25.

Figure 9-25. Connecting the field to the code

(If you want, you can also uncheck "Fill-in enabled" on the properties for the city and state fields to take them out of the tab order for the document.) Once you've done this, there's one last step: protecting the document. Go to Tools Protect Document (or select Protect Document in the Task Pane). You'll see the Protect Document pane, as shown in Figure 9-26.

Figure 9-26. The document protection pane

Check the checkbox under "Editing restrictions," select "Filling in forms," and then click "Yes, Start Enforcing Protection." Click OK in the confirmation dialog box (you don't need to enter a password), and the document will be ready to use. Filling in the first few fields does nothing unusual; it's not until you enter the Zip Code field that anything will happen. Figure 9-27 shows a document just before tabbing out of the Zip Code field, and Figure 9-28 shows the document afterwards, when the web service call has filled in the city and state fields.

Figure 9-27. The document before the Zip Code web service is called

Figure 9-28. The document after the SOAP-based Zip Code web service is called, with city and state information filled in

Figure 9-29. The document after the REST-based Zip Code web service is called, with city and state information filled in

This should spare the conspirator a small amount of typing, provided of course that their computer is on a network and the web service is operating. You can also do the same thing with the REST version of the service. The only change is in the code, shown in Example 9-8.

Figure 9-29 shows the result of entering a Zip Code in the document using the REST-based code. As usual, it's very much like its SOAP-based alternative.

Example 9-8. REST version of code for updating Word forms with retrieved information

Sub zipCodePlacer( )     Dim zip As String zip = ActiveDocument.Fields(5).Result.Text      Dim query As String      'assemble query string query = "http://webservicex.net/uszip.asmx/GetInfoByZIP?USZip=" + _    zip      'define XML and HTTP components Dim zipResult As New MSXML2.DOMDocument Dim zipService As New MSXML2.XMLHTTP      'create HTTP request to query URL - make sure to have 'that last "False" there for synchronous operation zipService.Open "GET", query, False      'send HTTP request zipService.send      'parse result zipResult.LoadXml (zipService.responseText)      ActiveDocument.Fields(3).Result.Text = _    zipResult.SelectSingleNode("//CITY").Text ActiveDocument.Fields(3).Update   ActiveDocument.Fields(4).Result.Text = _    zipResult.SelectSingleNode("//STATE").Text ActiveDocument.Fields(4).Update      End Sub

This just scratches the surface of what you can do with web services of various kinds in Office, but hopefully it's a start on which you can build your own projects.