Using Web Storage System Forms

Take advantage of the forms registry

In "Customizing OWA 2000," March 2001, InstantDoc ID 19714, I introduced Microsoft Web Storage System (WSS) Forms as a mechanism for changing the default Outlook Web Access (OWA) processing. Now let's look at the various WSS Forms technologies that you can use to override default processing and how to use one of those technologies.

The WSS Technologies
The WSS is an ideal platform for developing Web-based collaborative applications because the WSS has a URL-addressable store and supports several data-access methods, including ActiveX Data Objects (ADO) and HTTP-DAV (aka WWW Distributed Authoring and Versioning—WebDAV). Four key technologies generally fall under the WSS Forms name. These technologies can help you develop collaborative applications:

The Forms Registry
Every item and folder in the WSS is URL addressable. This addressability, in conjunction with the forms registry, lets you take a datacentric approach to your applications and build UIs that adapt to the operating environment. Consider an application that needs to display data in the user's chosen language. A formcentric approach to building this multilingual application involves invoking an ASP-based form that passes query strings to the URL. The query strings identify the language to use and the key needed to retrieve the data (e.g., http://ardbeg/myapp/myform.asp?language=english &user=laahs&folder=Inbox&subject =welcome.eml). With a datacentric approach, the multilingual application needs only to reference the data as a URL and the WSS automatically uses the relevant form to render the data. For example, if you associate myform .asp with the URL http://ardbeg/exchange/laahs/inbox/welcome.eml in the forms registry, whenever a user specifies that URL, the WSS automatically uses the English-version form to render the data. (I explain shortly how this feat is possible.)

The forms registry enables adaptive forms, which means that the same data accessed through one URL can be rendered in different ways according to the current operating environment. For example, in multiplatform applications, you can use the same piece of data to invoke different HTML and ASP forms for different types of browsers, much like you'd invoke different forms for each language that a multilingual application supports. Adaptive forms are especially useful when you want to support the Pocket PC as one of your clients because you need to provide less information and functionality to comply with the Pocket PC's small form factor.

In short, the forms registry decides which form to use to display data. Thus, you don't have to write a lot of conditional statements in your code, which makes your code clean.

Form Registrations
In "Customizing OWA 2000," I explained how Exchange 2000, Microsoft IIS, and an Internet Server API (ISAPI) DLL work together to provide OWA clients the same functionality as Outlook clients. I also explained how to use the DAV:defaultdocument property to override the default OWA folder processing. Form registrations provide much more flexibility than the DAV:defaultdocument property because you can use them to override not only default folder processing but also default item processing.

Registrations bind HTML and ASP forms to the data in the WSS. Registrations are actual items in the forms registry. Registrations contain properties that help determine the HTML or ASP form to return to the client's browser. When IIS receives an HTTP request, the ISAPI DLL tries to identify the registration item by matching the data in the request (and the conditions under which the data is being accessed) against the properties of the various registrations in the forms registry. In addition, the ISAPI DLL looks at the HTTP request's host headers to determine the browser's type, language, and so on, which is why you can create multiplatform and multilingual applications. If the ISAPI DLL finds a match, the WSS renders the HTML or ASP form associated with the matched registration item to the client. If the ISAPI DLL doesn't find a match, default OWA rendering occurs.

To understand how form registrations work, you need to understand the concept of content classes. Every item in the WSS has a particular content class, which the DAV:contentclass property specifies. A content class defines an item's purpose and properties. For example, if an item has a content class of urn:content-classes:message, the item is a mail message that has many properties, including the urn:schemas:httpmail:from property (which contains the data for the message's From field) and urn:schemas:mailheader:to property (which contains the data for the message's To field).

Registrations are items that have the content class of urn:schemas-microsoft-com:office:forms#registration. Table 1 lists the registration properties that determine whether to render a custom form to the client. Table 2 lists the registration properties that determine which custom form to use (assuming that a custom form is being used). Note that all the properties in the tables exist in the urn:schemas-microsoft-com:office:forms namespace; for the sake of brevity, I omitted the namespace from the property names.

The definitions for all the content classes and their associated properties in the WSS are collectively called the schema, which is published through hidden items in the WSS. The best way to view the schema is through Web Storage System Explorer, which is part of the WSS software development kit (SDK). You can download the WSS SDK from http://msdn.microsoft.com/downloads/default.asp?url=/code/sample.asp?url=/msdn-files/027/ 001/654/msdncompositedoc.xml.

Creating and Searching for Registrations
Because registrations are items of a particular content class, you can create them with tools such as ADO, HTTP-DAV, and the Web Storage System Form Registration Wizard. After you create a registration, you can refine its settings through its properties. The location in which you store the new registration depends on the items for which you want the registration to apply. You can choose to have a registration apply to one item, all items of a particular content class within a folder, or all items of a particular content class within a public or private store.

When a browser requests an item in the WSS, the ISAPI DLL uses an algorithm to search the forms registry for a matching registration. The algorithm checks a schema property called urn: schemas-microsoft-com:exch-data: schema-collection-ref, or schema-collection-ref (SCR) for short, to see whether it has a value. The SCR property value specifies the path to the folder in which to look for registrations. From an application viewpoint, the most common practice is to place the registrations, HTML forms, ASP forms, graphic files, and other resources in a separate folder.

If the requested item's SCR property has a value (i.e., contains a folder path), the algorithm searches the specified folder for the registration. If the SCR property doesn't have a value, the algorithm reads the SCR property of the item's parent folder (i.e., the folder in which the requested item resides). If the parent folder's SCR property doesn't have a value, the algorithm searches the SCR property of the store's global schema folder. If the global schema folder's SCR property doesn't have a value, the algorithm checks the urn: schemas-microsoft-com:exch-data: baseschema property. This multivalued property defines a list of folders to use when searching for schema items.

You can set the SCR property for any item in the WSS. Setting this property on an individual item means that the form registration applies to only that item. If you want a registration to apply to all items in a folder, you can set that folder's SCR property. If you want a registration to apply to all items in a store, you can set that store's global schema folder's SCR property.

A SharePoint Portal Server system can provide a good example of how to effectively use form registrations. In Web Storage System Explorer, you can browse the /system/schema folder of any workspace to see examples of many different form registrations.

An Example
Let's look at an example of how to use the forms registry to prohibit a particular user from creating new messages through OWA. When a user clicks New in OWA, the application issues a request URL that specifies the user's Drafts folder and the new command parameter. For example, for a user named Kevin, the URL might look like http://kevin/exchange/administrator/drafts/?cmd=new. Thus, your goal is to create a form registration that binds a custom form to this URL.

First, you need to decide where to place the registration and custom form. For this example, let's place them in the http://kevin/exchange/administrator/drafts/resources folder. Because you want to invoke the form only for the Drafts folder, you must set the Drafts folder's SCR property to the resources folder's path. You can use Web Storage System Explorer to set this property, as Figure 1 shows.

Next, you need to create the registration. The easiest way is to use the Web Storage System Form Registration Wizard, which you access through Web Storage System Explorer. The MSDN article "Web Storage System Forms: The Forms Registry" (http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnmes2k/html/ wssformsreg_v4.asp) provides step-by-step instructions about how to use the wizard. Figure 2 shows the completed form registration.

Finally, you need to create the custom form in the resources folder. You want the custom form to display a simple message that states, We are sorry but your account has been blocked from using the New button. Apologies for any inconvenience. Figure 3 shows what happens when Kevin clicks New in OWA.

Create Adaptive Forms
As the example demonstrates, you can use the forms registry to easily create Web-based collaborative applications that take advantage of WSS's core capabilities. In particular, you can create adaptive forms that respond to datacentric URLs and override default OWA functionality.