Introduction

In this article, I provide a detailed description of the concept behind the MCS, one of the components of Intelligent Notification Services (INS). I also demonstrate the required MCS configuration for optimal use in the WebSphere® Everyplace Access environment and highlight the added features of MCS for the Domino® server.

Back to top

Why do you need MCS?

When Jay, a marketing/customer service executive who travels a lot is out of office he needs to get event notifications on his pervasive devices (like his cell phone) about the high priority e-mail messages received from his office, as well as about any e-mail messages that land in his mail box from valuable customers.

MCS addresses these kinds of scenarios. Take a look at how MCS fits into the INS components family; I'll explain exactly what MCS is and how it works, and talk a bit about the e-mail servers that MCS can access.

Defining MCS and its relationship to INS

The INS is a set of components that provide support for user notifications.

INS component overview

Following are the components that make up the INS:

• The Subscription Manager (SM) provides the facilities for the management of subscriptions and for matching published events with subscriptions.
• The Notification Manager (NM) sends out messages to delivery channels based on user preferences. NM comes with a number of delivery channel adapters like e-mail, Sametime, America Online (AOL), Wireless Application Protocol (WAP), Short Message Service (SMS), and so on.
• The Mail and Calendar Services (MCS) accesses and uses the data from mail files. It monitors the mail files for new e-mail messages and provides events based on these new e-mails to the SM. Calendar-related functions are yet to be added.
• The Member Services (MS) deals with user- and group-related information.
• The Preference Manager (PM) maintains the user preference information on the delivery channels and delivery rules.

Figure 1 is a visual representation of how the INS components interact. A database stores the information related to the components.

What is MCS?

MCS accesses mail files and makes use of the accessed e-mail information. Mail files are checked periodically and information about the new e-mails are retrieved; MCS uses this data to provide e-mail notifications. Information about the newly received e-mail messages is published to the Subscription Manager for matching and user notification.

In addition to direct user notifications, these messages can be used to trigger Server Initiated Action (SIA) messages that are sent to a WebSphere Everyplace Access client device and cause the device to initiate an e-mail synchronization.

MCS operates by polling the mail servers. Decreasing the polling interval enables more timely notifications, but increases the impact on both the mail servers and the MCS server.

MCS ignores any e-mails that are older than 24 hours from the current time or any e-mails that have already been mined.

End-to-end message flow

Figure 2 demonstrates the message-flow process in INS.

Let me sum up this process. In the MCS component:

• The INS database maintains the following information related to MCS:
  • The mail files that needs to be accessed
  • The frequency for accessing the mail files
  • The accessed or accessing time of the mail files
  Using the previous information, MCS decides the time to check the user's mail file.
• MCS uses the Domino Server installed with INS to securely access this mail file and to find out the arrival of a new e-mail.
• Using the following information from the e-mail, MCS creates a notification event and publishes it to SM using the "Notes Email" topic.
  • The "To" address
  • The "From" address
  • The subject of the e-mail
  • The priority of the e-mail

In the SM component:

• SM checks the event that was published to see if it matches any of the subscriptions.
• SM retrieves the trigger handler for the user's e-mail subscription, instantiates it, and handles the match.
• The trigger handler formats the message generically (without regard for the delivery channel to be used), gets the delivery channel information from the subscription, creates a notification request specifying the user's preferred delivery channel, and sends it to NM.

In the NM component:

• NM checks whether the notification is meant for a user or a group.
• Group checking is performed using MS only when the messages are meant for a group.
• NM then uses PM to look up the delivery channel details.
• NM determines the order of the delivery channels to send the notification; if there is only one delivery channel, this check is not done.
• The channel adapter de-queues the message, reformats it using a transcoder into the required format, and forwards it to the preferred gateway.

The Delivery Channel Gateway then forwards the message to the user's preferred delivery channel, say SMS or Message Center.

Format of MCS notification message

Now I'll show you what an MCS notification message format contains. Message information includes:

• Message Heading: Whether it is a normal or an urgent message from the <Portal Admin Name>.
• Message Subject: Received <Message Server Name> E-mail.

E-mail information includes the familiar:

From: Sender Name
Subject: Subject of the Email
Importance: 'Urgent' if it is a high-priority message

Figure 3 depicts the format of the high-priority and normal MCS messages received in the Message Center portlet of INS.

Which e-mail servers can be accessed from MCS?

MCS provides the e-mail content adapter for Lotus® Domino Notes and Exchange and can access the mail files on remote Domino V5 and V6, Exchange 2000, Exchange 2003, and Exchange 5.5 servers.

To access the Domino mail files to generate e-mail notifications, a Domino Server must be installed with INS. It provides the Notes RPC (remote procedure call) protocol that is used to access the remote mail files. For Windows™ platforms, a Notes client can be used instead of a Domino server.

To access the Exchange 5.5 mail files, Microsoft Outlook is required. Microsoft Outlook provides the MAPI support, which is used to access the Exchange 5.5 mail files. An RMI server and Outlook client are also required to access this. Because Outlook is only available on Windows platforms, for other platforms the RMI server and the Outlook client have to be installed on a separate Windows server.

Now let's look at how to configure MCS for WebSphere Everyplace Access.

Configuring MCS in a WebSphere Everyplace Access environment

It is relatively simple to configure MCS (as well as the other INS components) for WebSphere Everyplace Access. Look in the following path for INSinstallconfig.properties, the file that contains the configuration properties for all of the INS components.

<INS_HOME (Absolute path where INS is installed)>/config/

MCS properties to configure

Following are the required properties for configuring MCS for WebSphere Everyplace Access:

• instMCSConfig: Set this value to "true" for access to MCS.
• instMCSDomino: Set this value to "true" for access to MCS Domino.
• instNMConfig and instSMConfig: These properties need to be "true" for sending MCS notifications.

MCS Domino properties to configure

Following are the required Domino Notes properties for using MCS Domino:

• instNotesPath: Absolute path of the Lotus Domino Server.
• instNotesDataPath: Absolute path of the Lotus Domino Server's Data directory.
• instDominoUserid: The absolute path and the file name of the administrator ID file used to connect to the Domino Mail Server.
• instDominoPassword: The password associated with the administrator for Domino specified by the property instDominoUserid.
• instDominoHost: The fully qualified host name of the Domino Mail Server. This is the mail database server where user data is stored; for example, Dominoserver.in.ibm.com. Note that port numbers should not be included.
• instDominoAbbreviatedServerName: The Domino abbreviated name of the Domino Server; for example, dhandu/ins. Note that this property value is required if the first level of the name of the Domino Server host (instDominoHost) does not match the first portion of the Domino abbreviated server name. For example, if instDominoHost is specified as mailserver.company.com and the Domino abbreviated name of the Domino server is dhandu/ins, then because "mailserver" does not match "dhandu," this parameter must be specified as dhandu/ins.
• customDominoField: A custom, unique, Domino Directory (names.nsf) field.
• useCommonCredentials: When opted for, it creates a Notes e-mail account using the portal user ID. By default, it creates a Notes e-mail account after prompting the user for an ID and password.
• userExitClass: This class is used for Notes user authentication.

In a distributed/clustered WebSphere Everyplace Access environment

If INS is running in a distributed environment and MCS is being used with Lotus Domino, these properties must be set in the INSinstallconfig.properties file on the computer running the INS portlets in addition to being set on the computers running the MCS.

Now I'll show you how to customize the behavior of the MCS component.

Customizing the behavior of MCS

The <INS_HOME>/config/xml/insMcsConfig.xml file contains the configuration properties that controls logging, specifies message queue names, and specifies the parameters to control mail file access. You can set these properties to whatever values suit your needs.

Let's look at those properties:

• MiningTimeout defines the number of minutes to wait if MCS fails to access a mail file on the e-mail server. The default is MiningTimeout="60".
• EmailRunTimeInterval defines the time between e-mail polling runs in minutes. The default is EmailRunTimeInterval="15".
• Standalone defines that MCS run without the NM and the SM. This property needs to be set to "true" only for debugging the MCS. The default is Standalone="false".
• MiningEmail defines MCS to look for e-mail users to be mined. The default is MiningEmail="true".
• EmailFormSet defines the list of e-mail forms to process. The possible forms are "Memo," "Appointment," "Notice," and "Reply." (For example: EmailFormSet="Memo")

Now that I've shown you how to configure MCS for a WebSphere Everyplace Access environment and how to customize the behavior of MCS, let's look at the simple steps needed to use MCS through a WebSphere Everyplace Access portal.

Using MCS through a WebSphere Everyplace Access portal

There are only three simple steps needed to use MCS through a WebSphere Everyplace Access portal:

1. In the Administration portlet for INS, enter the INS Administrator ID and password and save the changes.
2. In the INS Lotus Notes E-mail Subscriptions portlet under My Subscriptions, select Enable Subscriptions and enter the user ID and password for the user you want to mine. For Domino users, enter the Internet address or the Notes Canonical name.
3. Select New and create a new subscription.

Added features of MCS for Domino Server

The following are features added to MCS for use in the Domino Server:

• Domino User Exit
• Common Credentials
• Custom Domino Field

I'll demonstrate what each feature is, how it is used, and how to enable them.

Domino User Exit

This feature allows the user ID and password on the INS Lotus Notes E-mail Subscriptions portlet to use a Java™ program for the password authentication. If this option is not set, the password supplied on the INS Lotus E-mail Subscriptions portlet is compared against the httpPassword stored in the Notes Address Book (NAB). After the password has been verified, the mail file and the mail server for that user ID will be retrieved.

This feature offers the ability to set the mail file and mail server in the Java program. If the User Exit does not set these values, INS obtains them by searching the NAB. If the canonical name parameter (for example, Dhandu/Bangalore/IBM) is set in the User Exit, the NAB is searched using the canonical name; otherwise, the search is conducted using the user ID supplied in the portlet.

The Domino User Exit is enabled using the userExitClass property located in both <INS_HOME>/config/INSinstallconfig.properties and <WAS_HOME - Directory location where WebSphere is installed >/lib/app/INSPortletCfg.properties.

If you are configuring the INS portlets for the first time, set the userExitClass property in INSinstallconfig.properties to a file name or Java Archive (JAR) file name and run the INS Portlets configuration process. If you have already configured the INS portlets, you should stop WebSphere Portal, set userExitClass in the INSPortletCfg.properties file located at WAS_Home/lib/app, and restart WebSphere Portal.

The source for the interface class (com/lotus/sync/domino/DominoAuthExit.java) and a simple example implementation (SampleExit.java) are in the /source directory located in the INSPortlet.war file. The INS Portlets need access to these classes.

The easiest way to give portlet code access to the user exit class is to compile the interface and implementation classes and copy these new classes to the WEB-INF/classes directory. If this directory does not yet exist, then it needs to be created.

The portlets are located in the INSPortlet.war file, which is installed under <Portal_Home>/installedApps/Intelligen_pplication_PA_1_0_xx.ear/, in which Portal_Home is the directory where WebSphere Portal has been installed and xx is a pair of random characters that is different for every installation.

Alternatively, the classes can be built into a JAR file that should be put in the WEB-INF/lib directory of the WebSphere Portal installation.

When the User Exit is enabled in the INS Lotus Notes E-mail Subscriptions portlet the password is not required. The mail file and mail server are retrieved by the Java class provided. To view the mail file and mail server, select Refresh mail file and server on the INS Lotus Notes E-mail Subscriptions portlet.

Images are extracted from the INS portlet.

Common Credentials

The Common Credentials feature uses the WebSphere Portal user ID for your Domino Account to save you from having to log in multiple times. It is enabled through the useCommonCredentials property, located in both INSinstallconfig.properties and INSPortletCfg.properties.

If you are configuring the INS portlets for the first time, set the useCommonCredentials property in INSinstallconfig.properties to "true" and run the INS Portlets configuration process. If you have already configured the Intelligent Notification Services portlets, stop WebSphere Portal, set the useCommonCredentials property in INSinstallconfig.properties to "true," set useCommonCredentials to "true" in the INSPortletCfg.properties file (located at WAS_Home/lib/app), and restart WebSphere Portal.

When Common Credentials are enabled, the INS Lotus Notes E-mail Subscriptions portlet ID field is not editable and a password is not required. The mail file and mail server will be retrieved by searching the NAB for the user ID supplied. To view the mail file and mail server, select Refresh mail file and server on the INS Lotus Notes E-mail Subscriptions portlet.

Custom Domino Field

The Custom Domino Field feature provides the ability to use a Custom Field in the NAB for configuring INS Lotus Notes E-mail Subscriptions instead of the Internet address or canonical name. To enable the Custom Domino Field, there is a customDominoField property located in both INSinstallconfig.properties and INSPortletCfg.properties.

When configuring the Custom Domino Field for the first time, set the customDominoField property in the INSinstallconfig.properties file to the name used for the field (for example, EmployeeNumber) and run the Intelligent Notification Services Portlets configuration process.

If you have already configured the INS portlets, stop WebSphere Portal, set the customDominoField property in the INSinstallconfig.properties file to the name used for the field (for example, EmployeeNumber), set the customDominoField property in the INSPortletCfg.properties file, located at WAS_Home/lib/app, and restart WebSphere Portal.

MCS looks up users in the Domino Public Address Book (names.nsf) to determine the mail file name and server. This lookup is performed using the user's Internet e-mail address or Canonical Notes name. You can also add a custom field containing a different unique ID, such as an employee number, to your address book. This custom field can then be used in the MCS lookup.

The custom field must resolve into a unique e-mail address. For example, if you opened a Notes client and created a new memo, you can enter this custom field in the "TO:" field of the e-mail and the e-mail should then be able to reach the intended recipient.

In conclusion

In this article, I've provided a start to using MCS to provide e-mail data access for WebSphere Everyplace Access.

I've endeavored to outline INS and MCS, explained the value of employing MCS, delivered an overview of the components of INS and how they work together (using a dissection of the end-to-end of the message flow), showed you the format of the notification message, and detailed the e-mail servers that MCS can access.

At this point you should understand how to configure MCS for a WebSphere Everyplace Access system (covering the best properties' settings for MCS and MCS Domino) and how to avoid a "gotcha" when deploying in a distributed/clustered WebSphere Everyplace Access environment.

You've also been given a detailed look at the properties and their values for configuring the behavior of MCS, along with a demonstration of the three simple steps to using MCS in a WebSphere Everyplace Access portal.

Finally, I've illuminated the added features of MCS as they pertain to the Domino Server: Domino User Exit (allows use of a Java program for password authentication), Common Credentials (eliminates multiple logins), and Custom Domino Field (enables creation of customization in the NAB).

Try the Mail and Calendar Services today!

Resources

Learn

• IBM Research Report: An Intelligent Notification System (IBM Research, Watson Research Center, July 2001): Explains the need for and the technology behind the INS.
  
  
• "WebSphere Everyplace Access Intelligent Notification Service Part 1: Setting up and Configuring Components" (developerWorks, November 2003): A three-part series that can help you set up, configure, and use INS.
  
  
• WebSphere Everyplace Access: Provides tons of information on the WebSphere Everyplace Access system.
  
  
• WebSphere Everyplace Access 5.1 Infocenter: Helps you get started with WebSphere Everyplace Access.
  
  
• IBM WebSphere Everyplace Access V5 Handbook for Developers and Administrators Volume IV: Advanced Topics (IBM Redbooks, March 2005): Part of a series of four volumes that can help you plan, install, administer, and develop mobile applications to run in a WebSphere Everyplace Access Version 5.0 environment.
  
  
• developerWorks Web architecture zone: Specializes in articles covering various Web-based solutions.
  
  
• developerWorks technical events and Webcasts: Stay current with the latest technology.
  
  

Get products and technologies

• IBM trial software: Build your next development project with trial software, available for download directly from developerWorks.
  
  

Discuss

• developerWorks blogs: Get involved in the developerWorks community.
  
  

About the author

Dhandapani (Dhandu) Shanmugam is a Software Engineer for the IBM Pervasive Computing Group in India Software Labs, Bangalore, India. He has worked in INS and WTP test projects, and is an active member of the WES-T/IMS test team. He can be reached at dshanmug@in.ibm.com.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Why do you need MCS?
• Defining MCS and its relationship to INS
• Configuring MCS in a WebSphere Everyplace Access environment
• Customizing the behavior of MCS
• Using MCS through a WebSphere Everyplace Access portal
• Added features of MCS for Domino Server
• In conclusion
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Java on developerWorks

Try IBM Cognos 8 Business Intelligence

Use reports, analysis, dashboards and scorecards to monitor business performance, analyze trends and measure results.

Special offers