Outlook 2007 Mobile Service Guidelines (Part 2 of 3)

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary:   Learn how to build and host Web services for Outlook 2007 Mobile Service (OMS). This article continues the introduction to OMS by providing guidelines and recommendations for Web page development for the service. (10 printed pages)

Paul Shen, Microsoft Corporation

Bing He, Microsoft Corporation

Yong Zhang, Microsoft Corporation

Judy Zhang, Microsoft Corporation

Published February 2007

Updated December 2007

Applies to:   Microsoft Office Outlook 2007

Contents

  • Introduction to Web Services for OMS

  • Service-Side Development Recommendations

  • Web Pages

  • Message Traffic Logging

  • Conclusion

  • Additional Resources

Introduction to Web Services for OMS

Microsoft Office Outlook 2007 Mobile Service (OMS) is the new messaging and Personal Information Manager (PIM) component developed for Microsoft Office Outlook 2007. OMS is designed to make Outlook the best tool for mobile messaging and notification. With OMS, users can seamlessly integrate the mobile capabilities of Outlook with their mobile devices.

The OMS client, which is built into Outlook, sends text and multimedia messages to a Web service that is created and hosted by partners who are either carriers or mobile message content service providers. The Web service then delivers the message to a text message or multimedia message service center of carriers.

This is the second of a three-part series of articles that introduce OMS and provide guidelines for working with the service. For code examples and information about the message flow between OMS Web service providers and clients, see Outlook 2007 Mobile Service Guidelines (Part 1 of 3). For information about the XML schema for data that is passed between OMS Web providers and OMS clients, see Outlook 2007 Mobile Service Guidelines (Part 3 of 3).

Service-Side Development Recommendations

In Outlook 2007 Mobile Service Guidelines (Part 1 of 3), we discuss the communication protocols between the OMS Web service and the OMS client. Next, we will examine other issues to consider when developing or hosting an OMS Web service, and provide examples of Web pages that could be used to sign up users for that service.

Basic System Requirements

OMS Web service development does not require a complex system. You can use preexisting Microsoft technology to create a typical Web service. The basic system requirements are as follows:

  • Microsoft Visual Studio .NET 2003 or Microsoft Visual Studio 2005

  • Microsoft Windows Server 2003

  • Microsoft SQL Server 2000 or Microsoft SQL Server 2005

We recommend that you create the OMS Web service by using Visual Studio, and host it on Windows Server 2003 with Internet Information Services 6 (IIS). SQL Server is recommended for server-side transaction logging.

Performance and Capacity Considerations

Before full service operation is considered, it is very important that you rigorously test performance and capacity so that suitable hardware and Internet/intranet bandwidth can be allocated. Our experience has shown that performance testing is a good way to help service providers understand the capacity of the Web service and identify bugs that could be otherwise overlooked. Performance testing should measure the response time of a user’s requests, and should be divided into normal, peak, and stress testing.

The purpose of normal testing is to measure changes in the response time curve over a continual time period (for example, 12 hours). Peak testing measures changes in response at peak times (for example, business hours). Stress testing tests service stability and changes in response time when there is a high volume of requests during a very short period of time. Performance testing can be conducted by simultaneously running the same applet or script on numerous client computers that send text or multimedia message requests to the Web service.

It is not possible to create the true real-world environment needed for stress testing, which might consist of several thousand client computers simultaneously sending requests. Therefore, mathematical simulations are employed to determine how many client computers are needed for simulating a real-world scenario. For example, to simulate a real-world situation of 5000 users, each sending a text message every 30 minutes and expecting a three-second service response time, you might need to deploy nine client testing computers and send text messages simultaneously and repeatedly.

Web Pages

Web pages are developed by the OMS Web service providers and are displayed on the service provider's Web site. The URL for the sign-up page for the service provider should be defined in the signUpPage element of the serviceInfo XML string. The goals of these pages are to guide the user through the subscription process, to manage the user’s personal information and configuration, and to set up an account in Outlook for the Web service.

Multiple Web Service URLs

For service providers who aggregate services from multiple carriers, it is possible to design and host multiple OMS Web services so that individual carriers can have specific service parameters, such as limits on Short Message Service (SMS) message length or Multimedia Messaging Service (MMS) message size.

Accordingly, the sign-up Web pages must be designed to accommodate this requirement. Users are guided to different service URLs based on their carriers when they add an account to Outlook 2007 automatically or manually. After users sign up for a service, they are also guided to the corresponding service URL if they want to reconfigure their accounts.

Home Page

OMS Web service providers should create a home page that is the default page that a user opens. On this page, users should be able to obtain information about the Web service and client features. New users should be able to register with the OMS service, and subscribed users should be able to log on to check and update their personal information—such as passwords—and configure their reply options.

The home page should contain the following:

  • OMS introductions: Informally introduce OMS features to let users know more about OMS.

  • System requirements: To use OMS, users must install Outlook 2007, so they might need to check their Office version before sign-up.

  • Troubleshooting information.

  • Registration and logon entry.

  • A hyperlink or button for new users to sign up for the OMS service, and a message, such as "Click Sign-up to subscribe to the OMS service."

Provide existing users with some sort of logon area where they can log on to their OMS accounts by entering a User ID, or mobile phone number, and password. If a user forgets his or her password, the Web page should offer a way to retrieve it. When users log on successfully, they should be able to view and modify their user profiles, reply settings, and so on. Figure 1 is an example of an OMS home page.

Figure 1. OMS home page

OMS menu bar

Registration Page

Create a Web page called the "Registration Page" that gives users a step-by-step guide to registering for the OMS Web service. A user would enter this site by clicking Sign-Up on the home page. To register for the service, a user would complete the fields shown in Figure 2. The User ID should be a unique identification string defined by the user and can be the same as the mobile phone number. This field is optional depending on the different needs of service providers.

Figure 2. Registration page

Registration page

Configuration Settings Page

Create a "Configuration Settings" page that lets users modify their Reply and Notification settings.

The incoming message that is described in the "Packaging Incoming Mobile Messages" section in Outlook 2007 Mobile Service Guidelines (Part 1 of 3) is delivered by the OMS service according to predefined reply options. The Reply option allows two optional destinations: Reply to mobile phone or Reply to mailbox.

If a user selects the Reply to mailbox option (see Figure 3), we recommend that the user add the SMTP address (given by the service provider) to the Outlook Safe Senders List. This ensures that replies to mobile messages sent from the OMS client are not treated as junk e-mail messages. In addition, the Web service should send a Welcome e-mail message to users that select this Reply option that provides a list of key OMS features and includes instructions for activating the mailbox and using OMS.

By default, the Notification option is turned off. Users who select this option can enter the maximum number of messages per day that they want forwarded to their mobile device. These can be either OMS rule-based messages or OMS reminders. By default, the maximum number is 30. The service provider can count these messages by using the sourceType element in xmsData. Every day, for each specific user, the service provider counts the total number of sent messages with either sourceType="ruleBased" or sourceType="reminder". If this number is greater than the maximum number defined on the Configuration Settings page, the service provider should return an error code to the OMS client. The error would have a code attribute of other and might have the following text in the content element: "You have reached the predefined limit of Notification and Reminders messages you can receive today."

Figure 3. Configuration Settings page

Configuration Settings page

User Info Page

The "User Info" page helps users easily view their personal information. It contains registration information, configuration information, and service information. Figure 4 shows an example of a User Info page.

Figure 4. User Info Web page

User Info page

Change Password Page

The "Change Password" page lets users manage their personal information, such as password and mobile phone number. Figure 5 shows an example of a Change Password page.

Figure 5. Change Password Web page

Change Password page

Adding Accounts in Outlook

With OMS, users can configure accounts in Outlook 2007 for their Web service by just clicking a button. To make this work, service providers can add a link containing the required protocol or add a line in their code to return a protocol URL with the user’s information. When the user clicks this link, or applies any specific action to trigger the code, OMS displays a message that asks whether the user wants to add this account to OMS. If the user clicks Yes, the OMS account manager opens, and the user’s registration information is added automatically. The following URL is an example:

oms:http://211.136.85.91/omsv3/xmsservice.asmx?UserID=13910021012

The URL consists of the following:

  • Scheme ("oms:http://")

  • Server ("211.136.85.91")

  • Path ("omsv3/xmsservice.asmx")

  • Query ("UserID=12910021012")

According to RFC1738 (Unified Resource Locator), only the "server" and "path" portions can be case insensitive; other components are case sensitive. The URL scheme for "oms" is required and should be lowercase. The URL of the OMS Web service can be either http or https, but it is https if not otherwise specified.

The "query" component of the URL (all the text that follows the question mark) contains zero or more parameters separated by the ampersand symbol (&). Each parameter should be defined as "name=value". When the protocol URL does not contain the query component, it is treated as an empty account for the given service provider, without any parameters specified.

Insert an Add as an Outlook account link or button on the User Info page that starts the OMS account creation process, as shown in Figure 6.

Figure 6. Add as an Outlook account dialog box

Publishing the Web Service

The Web service developed for OMS can be published on the Office Marketplace at Microsoft Office Online. For more information, see Become an Office Marketplace provider.

Message Traffic Logging

The goals of message traffic logging are to gain a better understanding of OMS users and to determine and track the most frequent errors encountered by users. This information is valuable for improving the service.

To design the database described in this section, you must create the following tables:

  • userInformation

  • messageType

  • errorCodes

  • outgoingLog

  • outgoingErrorLog

  • receivingLog

The userInformation table records general information about each user, including properties such as userId (a unique, untraceable ID that is used to anonymously differentiate users), subscribed services such as text message service, subscribed time, expired time, drop-off time, and reply settings.

The messageType table defines the message types that need to be tracked in out-going messages. With this table, you can break down which messages are authored as text messages and which are generated as e-mail. The definition for the fields used in the messageType table is listed in Table 1. The predefined message types that should appear as part of the data in the messageType table are shown in Table 2.

Table 1. MessageType table definition

Field

Type

typeCode

digit

typeName

string

Table 2. Predefined message types

typeCode

typeName

100

Text message sent from e-mail inspector.

101

Text message sent from OMS inspector.

102

Text message sent from OMS inspector on scheduled time.

103

Reminder forwarded as text message.

104

Text message forwarded because of rule-based notification.

105

Calendar summary sent as text message.

200

MMS message sent from E-mail inspector.

201

MMS message sent from OMS inspector.

202

MMS message sent from OMS inspector on scheduled time.

203

Forwarded reminder sent as MMS message.

204

Forwarded rule-based notification sent as an MMS message.

205

Calendar summary sent as MMS message.

The definition of the errorCodes table is shown in Table 3. The errorCodes table should include the error codes used by the OMS Web service.

Table 3. ErrorCodes table definition

Field

Type

typeCode

Digit

typeName

String

The outgoingLog table logs all messages that are sent out by the OMS Web service, as shown in Table 4.

Table 4. OutgoingLog table definition

Field

Type

Description

messageID

Digit

Identity ID.

userID

String

Unique, untraceable ID that is used to anonymously differentiate users.

sendTime

dateTime

Date and time the message was sent.

messageType

Digit

Foreign key to the [MessageType].typeCode field.

splitNo

digit

Number of a long message that was split into multiple messages.

DBMix

Digit

0- English, 1- Mixed language.

recipientNo

Digit

Number of recipients.

slideModeFlag

Digit

With an MMS message, indicates whether it used slide mode: 0-Slide mode, 1- others.

contentType

String

The MIME (Multipurpose Internet Mail Extensions) content type contained in this message, such as "text/plain".

successFlag

Digit

0-Successful, 1-Partially successful, 2-Failure.

The outgoingErrorLog table logs all messages that are sent out without being fully successful, as shown in Table 5. It logs all related errors and can represent multiple errors for multiple records.

Table 5. OutgoingErrorLog table definition

Fields

Type

Description

ID

digit

Identity ID.

messageID

digit

ID of the message. This ID should match the ID recorded for this message on the outgoingLog table.

errorCode

string

Foreign key of [errorCodes].[typeCode] field.

The receivingLog table logs all messages that are received. It records several types of information, as shown in Table 6.

Table 6. ReceivingLog table definition

Fields

Type

Description

messageID

digit

Identity ID.

userID

string

Unique, untraceable ID that is used to anonymously differentiate users.

receiveTime

dateTime

Date and time reply was received.

replyTime

digit

Reply options defined by users: 0=Reply as E-mail, 1=Reply to Mobile, 2=Both.

messageType

string

"SMS," "MMS," or "Others".

contentType

string

MIME content type contained in this reply message, such as "plain/text".

successFlag

digit

The error code that occurred ("typeCode" field of the errorCodes table), or "0" to indicate success.

Creating the tables and using them as described will provide useful information about the performance of the OMS Web service.

The overall architecture of OMS is a client service framework based on Web service technology. The OMS client, which is built into Outlook, encodes a mobile message as a SOAP message and sends it to the OMS Web service, where it is then encoded and delivered to the carrier’s mobile message gateway. The message is then delivered to intended users’ mobile phone through the carrier’s mobile wireless networks. The OMS Web service is created and hosted by a service provider that is either a mobile telecom operator or aggregator (Internet content provider, Internet service provider, or any party that can provide a mobile messaging service). The OMS Web service specification and communication protocols between the OMS client and Web service are described in the "Communication Protocols" section in Outlook 2007 Mobile Service Guidelines (Part 1 of 3).

Messages flow back and forth between Outlook and the receiver’s mobile phone via the OMS Web service and the carrier’s infrastructure. Replies from the receiver’s mobile phone can go to the Outlook Inbox, the sender’s mobile device, or both, based on the user's preferences. To deliver replies to a user’s Inbox in Outlook, the service provider packages them into SMTP e-mail messages according to the specification defined by Microsoft. For more information, see the "Packaging Incoming Mobile Messages" section in Outlook 2007 Mobile Service Guidelines (Part 1 of 3).

Conclusion

In this article, we examined other issues that you should consider when developing or hosting an OMS Web service—such as message traffic logging—and provided some guidelines for developing a Web site to manage the sign-up and configuration processes for OMS Web service providers. Outlook 2007 Mobile Service Guidelines (Part 3 of 3) presents the XML schema for data that is passed between OMS Web providers and OMS clients and provides the WSDL definition for an OMS Web service.

Additional Resources

For more information, see the following resources: