Office 2010 Mobile Service Guidelines (Part 2 of 3)

Summary:  Learn how to build and host Web services for Microsoft Office 2010 Mobile Service (OMS). This article provides guidelines and recommendations for Web page development for OMS. Note that Office Mobile Service in Office 2010 is the updated version of the Outlook Mobile Service in the 2007 Microsoft Office system. (12 printed pages)

Applies to: Excel 2010 | Office 2007 | Office 2010 | Office Mobile | Open XML | Outlook 2010 | Outlook Mobile | PowerPoint 2010 | SharePoint Foundation 2010 | SharePoint Server 2010 | VBA | Word 2010

In this article
Introduction to Web Services for OMS
Service-Side Development Recommendations
Web Pages
Message Traffic Logging
Conclusion
Additional Resources

Published:  April 2010

Provided by:  Effon Khoo, Microsoft Corporation | Ken Wang, Microsoft Corporation | Dongdong Guo, Microsoft Corporation | Zhigang Zhuang, Microsoft Corporation | Qingzhong Cai, Microsoft Corporation

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 2010 Mobile Service (OMS) is the messaging component developed for Microsoft Outlook 2010 and Microsoft SharePoint 2010. With OMS, users can seamlessly integrate the mobile capabilities of Outlook with their mobile devices, as well as receive text message alerts from a SharePoint site.

The OMS client, which is built into Outlook and SharePoint, sends text or 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 Office 2010 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 Office 2010 Mobile Service Guidelines (Part 3 of 3).

Service-Side Development Recommendations

Office 2010 Mobile Service Guidelines (Part 1 of 3) discusses 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, Visual Studio 2005, Visual Studio 2008, or Visual Studio 2010.

• Microsoft Windows Server 2003 or Windows Server 2008.

• Microsoft SQL Server 2000, SQL Server 2005, or SQL Server 2008.

For best results, you should create the OMS Web service by using Visual Studio, and host it on Windows Server 2003 or later with Internet Information Services (IIS) 6.0 or later. 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. 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 5,000 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 or SharePoint for the Web service.

Multiple Web Service URLs

For service providers that 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 or SharePoint. 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 2010 or SharePoint 2010, so they might need to check their Microsoft 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

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

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 Office 2010 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), the user should 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 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

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 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 page

Adding Accounts in Outlook

With OMS, users can configure accounts in Outlook 2010 for their Web service by just clicking a button. To make this work, service providers can add a link that contains 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:https://211.136.85.91/omsv3/xmsservice.asmx?UserID=13910021012

The URL consists of the following:

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

• Server ("211.136.85.91")

• Path ("omsv3/xmsservice.asmx")

• Query ("UserID=12910021012")

According to RFC 1738, "Uniform Resource Locators," 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 has to start with "https".

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 outgoing messages. With this table, you can break down which messages are authored as text messages and which are generated as e-mail messages. 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

Table 2. Predefined message types

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

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

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

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

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 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 phones 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 Office 2010 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 Office 2010 Mobile Service Guidelines (Part 1 of 3).

Conclusion

This article examines other issues, such as message traffic logging, that you should consider when developing or hosting an OMS Web service. The article also provides some guidelines for developing a Web site to manage the sign-up and configuration processes for OMS Web service providers. Office 2010 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:

• Web Services

• The XML Files: A Quick Guide to XML Schema - Part 1

• The XML Files: A Quick Guide to XML Schema - Part 2

• RFC 2045—Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies

• Outlook Developer Center

• Office 2010 Mobile Service Guidelines (Part 1 of 3)

• Office 2010 Mobile Service Guidelines (Part 3 of 3)