Walkthrough: Calling XML Web Services from Outlook 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.

 

Uma Subramanian
Microsoft Corporation

July 2002

Applies to:
    Microsoft® Outlook® 2002
    Microsoft Office XP

Summary: Learn how to use the Web Service References Tool 2.0 and the Outlook 2002 object model elements to automate Outlook. The sample discussed in this article references and uses an XML Web service to send replies to messages automatically. (6 printed pages)

Contents

Introduction
Requirements
Locating an XML Web Service and Adding an XML Web Service Reference
Accessing the XML Web Service
Testing

Introduction

You can greatly enhance the functionality of Microsoft® Outlook® by using XML Web services. Connecting Outlook to XML Web services is as simple as making calls to XML Web service methods, which are processed on a server that then returns the results of the method call. Basically, to access an XML Web service from Outlook, you locate, reference and use the functionality contained within that XML Web service in your client application.

The Web Service References Tool 2.0 simplifies the process of locating and accessing XML Web services by using the notion of XML Web service references. Adding an XML Web service reference to a client application results in the generation of a proxy class that serves as a local representation of the XML Web service with which the client can interact. In other words, you can use the Web Service References Tool 2.0 to locate an XML Web service for your application to access, download the service description to the local machine and then generate a proxy class for the chosen XML Web service. The generated proxy class locally represents the exposed functionality of an XML Web service. The proxy class defines methods that represent the actual methods exposed by an XML Web service. When the client application creates an instance of the proxy class, it is capable of calling the XML Web service methods as if the XML Web service was a locally available component.

This walkthrough demonstrates how simple it is to create an XML Web service client in Outlook. The sample is designed in such a way that when a request for airport weather summary is received through e-mail, Outlook calls the AirportWeather XML Web service to retrieve the weather summary of the requested airport and sends a reply to the sender with the airport weather information.

Requirements

The development computer must have the Web Service References Tool 2.0 and Microsoft Office XP installed.

Locating an XML Web Service and Adding an XML Web Service Reference

After the Web Service References Tool 2.0 is installed on the development computer, open the Visual Basic® Editor in Microsoft Outlook. Set a reference to the Microsoft Soap Type Library v3.0 from the References dialog box (Tools menu). Then, on the Tools menu, click Web Service References.

Now perform the following steps to locate the AirportWeather Web service and add a reference to it:

  1. Type Airport Weather in the Keywords field in the Web Service Search area and click Search. Alternately, you can also provide a URL to the WSDL in the Web Service URL section and click Search. The Web Service References tool sends the search criteria to the UDDI server and displays the results in the Search Results list.
  2. To add the AirportWeather Web service to your current project, click the AirportWeather checkbox and click Add. The Web Service References tool downloads the service description to the local machine and then generates a proxy class for the chosen XML Web service. If you look at the Project Explorer in Visual Basic Editor, you will find that new class modules have been created and added to your project.

Accessing the XML Web Service

Now you can write code to create the application you want to develop. You can access the XML Web service by creating an instance of the proxy class and calling the appropriate XML Web service method.

The sample discussed in this article checks every incoming message to see if it is a request for airport weather summary, and if it is, then it calls theGetSummaryWeb service method to retrieve the weather summary for the requested airport and sends a reply with the weather summary to the sender. Let's look at the code in detail.

Private Sub Application_NewMail()
    Dim requestsFolder As MAPIFolder
    Dim appNameSpace As NameSpace
    Dim requestMailItem As MailItem
    Dim replyMailItem As MailItem

    On Error GoTo ErrorHandler

    Set appNameSpace = Application.GetNamespace("MAPI")
    Set requestsFolder = appNameSpace.GetDefaultFolder(olFolderInbox)

    If requestsFolder Is Nothing Then Exit Sub
    DoEvents

        Set requestMailItem = requestsFolder.Items.Item(1)
        If requestMailItem Is Nothing Then Exit Sub
        DoEvents
        If Mid(requestMailItem.Subject, 1, 32) = "Send Airport Weather
          Summary for" Then
            Dim ExampleVar As New clsws_AirportWeather
            Dim Result As New struct_WeatherSummary
            Set Result = 
              ExampleVar.wsm_getSummary(Mid(requestMailItem.Subject, 34,
              4))
            Set replyMailItem = requestMailItem.Reply
            replyMailItem.Body = "Location: " + Result.location + " Temp:
              " + Result.temp + " Visibility: " + Result.visibility + "
              Humdity: " + Result.humidity + " Pressure: " +
              Result.pressure + " Sky: " + Result.sky + " Wind: " +
              Result.wind
            replyMailItem.Send
        End If
    Exit Sub
ErrorHandler:
    Select Case Err
        Case Else
            MsgBox Err.Number & " " & Err.Description, vbOKOnly +
              vbExclamation, "Error"
    End Select
End Sub

The NewMail event occurs when one or more new messages are received in the Inbox. Outlook calls the Application_NewMail event procedure every time the NewMail event occurs. Note that the code for the event procedure should be placed in a class module and in this sample, the code is placed in the default ThisOutlookSession class module.

The first few Dim statements declare the necessary variables and the On Error statement enables an error-handling routine and specifies the location of the routine within the procedure.

    Dim requestsFolder As MAPIFolder
    Dim appNameSpace As NameSpace
    Dim requestMailItem As MailItem
    Dim replyMailItem As MailItem

    On Error GoTo ErrorHandler

The following statements obtain the Namespace object and a MAPIFolder object that represents the Inbox folder for the user who is currently logged in. The If statement is used to tell the system to exit the procedure if the Inbox is empty. DoEvents yields execution so that the operating system can process other events.

    Set appNameSpace = Application.GetNamespace("MAPI")
    Set requestsFolder = appNameSpace.GetDefaultFolder(olFolderInbox)

    If requestsFolder Is Nothing Then Exit Sub

    DoEvents

Now let's look at the crucial part of the code.

    Set requestMailItem = requestsFolder.Items.Item(1)
    If requestMailItem Is Nothing Then Exit Sub
        DoEvents
        If Mid(requestMailItem.Subject, 1, 32) = "Send Airport Weather 
          Summary for" Then
            Dim ExampleVar As New clsws_AirportWeather
            Dim Result As New struct_WeatherSummary
            Set Result = 
              ExampleVar.wsm_getSummary(Mid(requestMailItem.Subject, 34, 
              4))
            Set replyMailItem = requestMailItem.Reply
            replyMailItem.Body = "Location: " + Result.location + " Temp: 
              " + Result.temp + " Visibility: " + Result.visibility + " 
                Humdity: " + Result.humidity + " Pressure: " + 
                Result.pressure + " Sky: " + Result.sky + " Wind: " + 
                Result.wind
            replyMailItem.Send
        End If
    Exit Sub

The first Set statement sets therequestMailItemwith the first message in the Inbox. The following If statement is used to tell the system to exit the procedure if therequestMailItemis set to Nothing. The next If statement checks if the subject of the message starts with 'Send Airport Weather Summary for' and if it does, then it does the following:

  1. Creates an instance of the proxy class. In this case, it creates an instance of theclsws_AirportWeatherclass.

  2. Creates an instance of the complex type returned by the XML Web service. The complex typestruct_WeatherSummaryin this sample has the following definition:

    Public location As String
Public wind As String
Public sky As String
Public temp As String
Public humidity As String
Public pressure As String
Public visibility As String

  3. Calls thegetSummaryXML Web service method with the airport code obtained from the subject of the message.

  4. Creates a reply using the Reply method of the MailItem object.

  5. Fills the body of the reply with the contents of theResultcomplex type and sends the reply using the Send method of the MailItem object.

Testing

You can now test the code to make sure it works correctly.

To Test the Code

  1. First, make sure that the code is placed in the ThisOutlookSession class module. Then, create an e-mail message using any e-mail client with the subject Send Airport Weather Summary for EGLL. Note that EGLL stands for the London Heathrow airport and you can replace it with HECA for Cairo airport, KJFK for New York JFK, KLAX for Los Angeles Intl., EIDW for Dublin airport, Ireland, VHHH for Hong Kong Intl., EHAM for Amsterdam airport, YSSY for Sydney Intl., and RJTT for Tokyo Intl., to name a few.
  2. Send it to your Outlook user account.
  3. The moment Outlook receives this message, it will execute the NewMail event procedure and throw a security warning informing you that an application is trying to send an e-mail message on your behalf. Click Yes to allow Outlook to automatically send the reply.
  4. Check the e-mail client using which you sent the airport weather summary request. You should receive a reply from your Outlook account with the weather information of the airport that you requested.