Using the Office XP Web Services Toolkit 2.0 in Microsoft Word 2002

  • Article

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

 

John Lim
Microsoft Corporation

July 2002

Applies to:
     Microsoft® Office XP Web Services Toolkit 2.0

     Microsoft Word 2002

Summary: This article describes using the Microsoft Office XP Web Services Toolkit 2.0 to integrate an XML Web service with Microsoft Word 2002. The sample discussed in this article uses the Zip Code Resolver XML Web service to correct valid United States Postal Service (USPS) addresses contained in a mail merge address block of a Word document. If the address is found to be incomplete or inaccurate, the data source is updated with the address returned from the XML Web service.

Download Setup.exe.

Contents

Introduction
Running the Solution
Creating a mail merge document in Word
Adding Code to access the Web service
Conclusion

Introduction

You can use the Microsoft Office XP Web Services Toolkit 2.0 to quickly and easily implement XML Web services in a client application. The toolkit can be used to search for and then add an appropriate Web service to enhance the functionality of your Microsoft Word solution.

The toolkit automatically generates a proxy object and associated classes for a selected XML Web service, which allows you to invoke the methods exposed by the Web service. This version of the toolkit also includes the SOAP 3.0 DLL which assists you in using both simple and complex data types to interact with the XML Web service. The Zip Code Resolver XML Web service demonstrates using complex data types as it returns a complex SOAP data type in the form of a structure.

The sample associated with this article includes two files. The CheckAddress.doc file is a Word document that uses merged data to create an address block for an envelope. The data is contained in the CheckAddress.mdb file which was created by Word through the Mail Merge Wizard. The mail merge feature of Word is used to quickly create a letter, envelope, e-mail, or labels for mass distribution. Since the data is contained in a separate source file, you can create a single document with multiple recipients by creating data fields within the document.

This sample ensures that that the addressing information contained in the mail merged fields is accurate by sending the address of the selected recipient to the Zip Code Resolver XML Web service. If the address is found to be valid, the XML Web service returns the official USPS address to Word. The sample then checks if the returned address matches the address contained in the address block of the document. If there is a discrepancy between the address, the CheckAddress.mdb file is updated through ActiveX® Data Objects (ADO) to the corrected USPS address.

Running the Sample

To run the sample application, you must have the following installed on your computer:

  • The Microsoft Office XP Web Services Toolkit 2.0.
  • The CheckAddress.doc and CheckAddress.mdb files in the same directory on your computer.

After installing the above files, open the CheckAddress.doc file using Microsoft Word. When you run the sample for the first time, a dialog box will be displayed stating that Word cannot find the data source. Click the Find Data Source button and browse to the CheckAddress.mdb file which should be in the same directory as the CheckAddress.doc file. An envelope will be displayed with a command button under the recipient's address. Notice that the address does not contain a Zip Code and that "AV" is used instead of the correct term "AVE" in the first address line.

Click the CHECK ADDRESS button to send the address to ZIP Code Resolver XML Web service. After a few seconds, a message box should be displayed stating that the address was found to contain errors and/or not complete and that the database has been updated with the correct address. After clicking OK on the message box, the address on the envelope will display the correct USPS address returned by the Web service.

To check the next address, click the forward button on the Mail Merge toolbar and click the CHECK ADDRESS button again.

**Note   **If the Mail Merge toolbar is not displayed, on the View menu, point to Toolbars, and then click Mail Merge.

There are four recipients associated with a mail merge data source in this document. The first two recipients contain incorrect and incomplete addresses, which will be updated with the correct addresses after clicking the CHECK ADDRESS button. The third recipient contains an address that matches the address returned by the Web service. Finally, the fourth recipient has an address that is found to be invalid by the Web service.

After you click CHECK ADDRESS for the first two recipients, the address will now be correct in the CheckAddress.mdb data source file. For testing purposes, you can change the addressing information to once again contain incomplete or incorrect addresses by editing the CheckAddress.mdb file in Microsoft Access or through the Edit recipient list command in the Mail Merge Wizard of Word.

Creating a Mail Merge Document in Word

The CheckAddress.doc file was initially created with the Mail Merge Wizard in Word. The wizard allows you choose the document type, select recipients from an existing list or a new list, specify the recipient information to add to the letter, and then display or edit the merged document.

The following steps describe how the CheckAddress.doc file was created.

  1. In a new Word document, on the Tools menu, point to Letters and Mailings, and then click Mail Merge Wizard.
  2. In the first step of the wizard, select Envelope as the document type. Click Next.
  3. In the second step of the wizard, click Envelope options and select Size 10 for the Envelope size. Click OK to return to the Mail Merge Wizard. Click Next to proceed to step 3 of the wizard.
  4. Click Type a new list and then click Create to display the New Address List dialog box.
  5. Type the address information for your recipients. To add recipients to your list, click New Entry. Click Close to save your address list.
  6. The Mail Merge Recipients dialog box should be displayed which allows you to sort and specify the recipients for the mail merge. All the entries you created in your list will be selected by default. Click OK to continue in the Mail Merge Wizard.
  7. Select the area on the envelope which will contain the recipients address. Then, in the fourth step of the wizard, select Address block to display the Insert Address Block dialog box. When you have selected how the address will be displayed on the envelope, click OK.
  8. In the fifth step of the wizard, you can preview the envelope and edit the recipient list if you need to change your address list. Click Next to proceed to the sixth and final step of the wizard.
  9. In the last step of the wizard you can print or edit individual envelopes. At this point, you can choose to close the wizard.

Adding Code to Access the XML Web Service

The Microsoft Office XP Web Services Toolkit 2.0 allows you to easily locate and add an XML Web service to your Word client. To add the Zip Code Resolver XML Web Service, open the Office Visual Basic® Editor from your mail merge document (ALT+F11). Set a reference to the Microsoft Soap Type Library v3 from the References dialog box (Tools menu). Then, on the Tools menu, click Web Service References. In the Web Service References Tool 2.0 dialog box, select Web service and type the following URL: http://webservices.eraserver.net/zipcoderesolver/zipcoderesolver.asmx?wsdl.

When you add an XML Web service using the toolkit, the following files are automatically added as class modules in the Visual Basic project:

  • clsof_Factory_ZipCodeResolver Contains code that maps the structure in the struct_USPSAddress file with the methods in the Component Object Model (COM) object on the Web server.
  • struct_USPSAddress Contains the USPSADDRESS structure with street, city, state, shortzip, and fullzip elements.
  • clsws_ZipCodeResolver Contains code that encapsulates the Zip Code Resolver XML Web service methods.

The Zip Code Resolver XML Web service exposes numerous methods to interact with the service. The sample associated with this article uses the wsm_CorrectedAddressXml method which is declared in the clsws_ZipCodeResolver class module. This method accepts four strings which represent a US postal address with an access code and returns a USPSADDRESS structure which contains the resolved USPS address.

The CheckAddress.doc sample uses the MailMerge object in Word to access the data contained in the address block of the document. The GetAddressFromWebService procedure contained in the ThisDocument object of the CheckAddress VB project is called when the user clicks the command button on the envelope.

The first section of the procedure assigns the str_address, str_city, and str_state variables to values ascertained from the MailMergeDataSource object. These values, along with the access code are then sent to the XML Web service by calling the wsm_CorrectedAddressXml method.

Public Sub GetAddressFromWebService()
    Dim objResolver As clsws_ZipCodeResolver
    Dim objNewAddr As struct_USPSAddress
    Dim str_accessCode As String
    Dim str_address As String
    Dim str_city As String
    Dim str_state As String
    Dim str_zip As String
    Const TEST_ACCESS_CODE = "9999"
    
    ' Set the input strings.
    str_accessCode = TEST_ACCESS_CODE
    
    
    str_address = ActiveDocument.MailMerge.DataSource.DataFields(5).Value
    str_city = ActiveDocument.MailMerge.DataSource.DataFields(7).Value
    str_state = ActiveDocument.MailMerge.DataSource.DataFields(8).Value
    str_zip = ActiveDocument.MailMerge.DataSource.DataFields(9).Value
    
    Set objResolver = New clsws_ZipCodeResolver
    Set objNewAddr = New struct_USPSAddress
    
    ' This is the actual call to the web service which will return a corrected
    ' address and zip code if the address is valid.
    Set objNewAddr = objResolver.wsm_CorrectedAddressXml(str_accessCode, str_address, str_city, str_state)
        
    ' The city field returned by the web service contains an extra carriage return,
    ' the next statement removes it for formatting purposes.
    If InStr(1, objNewAddr.City, Chr(10)) Then _
        objNewAddr.City = Right(objNewAddr.City, Len(objNewAddr.City) - _
        (InStr(1, objNewAddr.City, Chr(10)) + 2))

The next part of the procedure compares the values in the MailMergeDataSource object with the values returned from the call to the XML Web service. If the address information sent to the XML Web service is different than the address returned, then the UpdateRecordset procedure is called to update the data source with the correct USPS address.

    If (objNewAddr.City = " - Unable to retur") Then
        MsgBox ("The address could not be resolved by the Web Service.")
    
    ElseIf ((str_address <> objNewAddr.Street) _
        Or (str_city <> objNewAddr.City) _
        Or (str_state <> objNewAddr.State) _
        Or (str_zip <> objNewAddr.ShortZIP)) Then
            UpdateRecordset MailMerge.DataSource.Name, _
            "SELECT * FROM Office_Address_List WHERE [Address Line 1] = " & Chr(39) & _
            str_address & Chr(39), _
            "Address Line 1", objNewAddr.Street, "City", objNewAddr.City, _
            "State", objNewAddr.State, "Zip Code", objNewAddr.ShortZIP
            MsgBox ("The address was found to contain errors and/or not complete." & vbCrLf & _
            "The database has been updated with address information returned from the Web Service.")
            ActiveDocument.Fields.Update
            
    Else
        MsgBox ("The address matched the address returned by the Web Service.")
    End If

End Sub

The UpdateRecordset procedure creates a new ADO connection and opens a new Recordset object. It updates the fields for the record that corresponds to the address data displayed in the mail merge fields and closes the connection.

Sub UpdateRecordset(strDBPath As String, _
                    strSQL As String, _
                    strUpdateAddress As String, _
                    strUpdateAddressValue As String, _
                    strUpdateCity As String, _
                    strUpdateCityValue As String, _
                    strUpdateState As String, _
                    strUpdateStateValue As String, _
                    strUpdateZipCode As String, _
                    strUpdateZipCodeValue As String)
   
    Dim cnn As ADODB.Connection
    Dim rst As ADODB.Recordset
    
    Set cnn = New ADODB.Connection
    ' Open the connection.

    With cnn
        .Provider = "Microsoft.Jet.OLEDB.4.0"
        .Open strDBPath
    End With
    
    Set rst = New ADODB.Recordset
    With rst
        ' Open the Recordset object.
        .Open Source:=strSQL, _
              ActiveConnection:=cnn, _
              CursorType:=adOpenKeyset, _
              LockType:=adLockOptimistic
              
        ' Update the specified fields for the current record.
        .Fields(strUpdateAddress).Value = strUpdateAddressValue
        .Fields(strUpdateCity).Value = strUpdateCityValue
        .Fields(strUpdateState).Value = strUpdateStateValue
        .Fields(strUpdateZipCode).Value = strUpdateZipCodeValue
        
        ' Save the changes you made to the current record in the Recordset object.
        .Update
        
        ' Close the Recordset object.
        .Close
    End With
    
    ' Close connection and destroy object variables.
    cnn.Close
    Set rst = Nothing
    Set cnn = Nothing
End Sub

Conclusion

The Web Service References Tool 2.0 can be used to easily integrate XML Web services with Microsoft Word 2002. By utilizing the MailMerge object in Word with an XML Web service that verifies USPS addresses, you can programmatically determine whether your address is valid and complete.