Web Storage System Forms

As shown in the beginning of this chapter, OWA provides a neat extensibility model in the form of querystring parameters added to the URL, yet one of the key requirements for customizing OWA is the ability to replace the default forms that it displays for items contained in the information store with custom forms. Imagine that you create an ASP application that stores information in Exchange Server, and suppose that you want to provide your users with a customized interface to access your application's content. In this scenario, you would most likely want to replace the default OWA forms with your application's forms. That's why Exchange Server supports WSS Forms and a WSS Forms Registry.

WSS Forms Architecture

Before we write code that uses WSS Forms, let's look at the architecture of WSS Forms so you will understand why you have to do certain things to get WSS Forms Registry going.

First and foremost, you must understand that WSS Forms and the WSS Forms Registry are implemented as Internet Server Application Program Interface (ISAPI) extensions. WSS Forms live in a DLL called exwform.dll, which is at http://server/exchweb/bin/exwform.dll . When you create a form registration that leverages the WSS Forms Renderer, which is part of that DLL, the WSS Forms Registry DLL calls exwform.dll to render your data. For the WSS Forms Registry, you will find that this DLL lives in an ISAPI extension called davex.dll. If you look at the configuration in the Internet Information Services (IIS) Manager under any Exchange virtual directory, you will see davex.dll in the list of ISAPI DLLs. To see the configuration, create a new application name for your virtual directory in IIS by clicking the Create button and then click the Configuration button. Davex.dll is registered to parse every HTTP request coming into a virtual directory that points at an Exchange datasource. This is so the DLL can look in the WSS Forms Registry to see whether the data that the user or application is requesting has a form registered to display the data. This is also how the WSS Forms Registry can detect the type of browser and language that is requesting the data. All of these headers are passed by the browser to IIS, which passes that data to the ISAPI davex.dll.

If you use the WSS Forms Renderer and the data requested has a WSS Form associated with it, the renderer will use the EXOLEDB provider to read the HTML form specified in the form registration's FormURL property. (This is why WSS Forms must live inside the Exchange database.) It will then parse that form for any special markup that specifies data binding, as you'll see shortly. The renderer will then request the required databound properties against the data item specified in the form registration's DataURL property. The values it retrieves will be formatted according to the formats you specified in your form, and any necessary time zone conversions will be performed. The renderer will then combine the data and the HTML form and return the new combined form to the client that made the request. The renderer does all the heavy lifting for you. It actively goes out and combines your marked up HTML form with the data from Exchange.

Creating a WSS Form

Because WSS Forms can be ASP forms or simply HTML forms, you don't need a custom tool to create them. Instead, you can simply use common HTML development tools such as Microsoft FrontPage, Microsoft Visual Studio .NET, or Microsoft Visual Notepad.

When you create WSS Forms, you have two choices for rendering (that is, emitting HTML data to the browser). You can simply use an ASP file and generate all the code and HTML yourself without getting any help from Exchange Server, or you can use HTML forms and the WSS Forms Renderer. The first approach requires you to program with Collaboration Data Objects (CDO), ActiveX Data Objects (ADO), or ServerXMLHTTP and WebDAV. The latter does not require you to write any code.

Using ASP Forms

The Training application uses the first approach of creating a WSS Form because of the flexibility that ASP provides. When a user chooses OWA as the interface to the Events Calendar page and opens an item from the calendar, Exchange Server checks the WSS Forms Registry and determines that an ASP page is registered for the calendar. Instead of displaying the default calendar form, Exchange Server hands over execution of the application to the ASP application and passes it some parameters within the URL. As part of the URL, Exchange Server passes the DataURL parameter. The DataURL parameter is the full path to the item that the user requested from Exchange Server. By using the value in this DataURL parameter, you can open the item via CDO, ADO or ServerXMLHTTP if you are programming an XML-based server-to-server solution and perform the necessary operations for your application. The following code is taken from eventwsform.asp, which is the ASP file called in the Training application, and Figure 20-4 shows the resulting Web page as displayed in the user's browser:

 'Figure out display from a querystring variable set rec = Server.CreateObject("ADODB.Record")      strFullURL = request.QueryString("DataURL") set oConnection = Server.CreateObject("ADODB.Connection") oConnection.ConnectionString = strFullURL oConnection.Provider = "ExOledb.Datasource" oConnection.Open rec.Open strFullURL,oConnection      Response.Write "<B>Course Details:</B><BR><BR>"      'Open the connection set iAppt = Server.CreateObject("CDO.Appointment")      Dim strhref      'Load the appointment into CDO 'Response.Write strhref strhref = rec.Fields("DAV:href") iAppt.DataSource.Open strhref, oConnection, 1 . . . . 

Figure 20-4: An example of an ASP-based WSS Form.

Using HTML Forms

Creating an HTML form that supports data binding is easy with Exchange Server and WSS Forms. By using some special HTML markup, you can turn ordinary HTML elements into data-bound elements. The markup you'll need to implement consists of two attributes to set. First you must set the name attribute of the HTML element as the schema name that you want to bind to the element ”for example, urn:schemas:httpmail:subject . The second attribute you need to set on the HTML element is named class . You must always set this attribute to a value of field to tell the WSS Forms Renderer that this is a data-bound field. The following HTML sets a text box to suddenly be data-bound to a WSS field named myprop :

 My Prop: <input type="text" name="urn:schemas:myschema:myprop" class="field"> 

You also receive the DataURL parameter as you would in an ASP WSS Form. Using DataURL , you can set the action of your form to post the data back to the URL from which the data was retrieved. The following code permits a user submitting a form to have that form post back to Exchange Server and then redirect the Web page to the application's default page:

 <form class="form" method="post"     actionspec="%DataURL%?Cmd=SaveItem&Redir=%DataURL%/../"> 

That's it. As you can see, creating a WSS data-bound HTML form is pretty simple.

Registering a WSS Form

Now that you've created a WSS Form, you need to tell Exchange Server what to do with it. For example, you might want your form to replace another form. Or you might want your form to process commands sent to a specific server. To tell Exchange Server how to use your form, you must add a form registration to your application. A form registration is just another item in the Exchange Server database; however, it contains some special properties, which we'll examine momentarily. Normally, you will want to save your form registrations in the schema folder for your applications, which is typically the same place you store your custom content classes and properties.

The following code shows how to register a form using ADO and results in a form like that in Figure 20-5. This particular registration displays the custom form whenever a user browses to the folder over HTTP, either by typing a URL in Internet Explorer or by browsing through the folders of OWA and selecting a folder.

Figure 20-5: A form registration item for a WSS Form

 Set oRec = CreateObject("ADODB.Record") oRec.Open "default.reg", oCon, 3, 0      oRec.Fields("DAV:contentclass") = _     "urn:schemas-microsoft-com:office:forms#registration" oRec.Fields("urn:schemas-microsoft-com:office:forms#contentclass") = _     "urn:content-classes:folder" oRec.Fields("urn:schemas-microsoft-com:office:forms#request")= "GET" oRec.Fields("urn:schemas-microsoft-com:office:forms#cmd") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#formurl") = "default.htm" oRec.Fields("urn:schemas-microsoft-com:office:forms#executeurl") = _     "/exchweb/bin/exwform.dll" oRec.Fields("urn:schemas-microsoft-com:office:forms#executeparameters") = "" oRec.Fields("urn:schemas-microsoft-com:office:forms#contentstate") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#platform") = "WINNT" oRec.Fields("urn:schemas-microsoft-com:office:forms#browser") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#majorver") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#minorver") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#version") = "" oRec.Fields("urn:schemas-microsoft-com:office:forms#messagestate") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#language") = "*" oRec.Fields.Update      oRec.Close 

The code simply creates a new item in Exchange Server (see Figure 20-5). It sets the content class of the item to urn:schemas-microsoft-com:office:forms#registration , which tells Exchange Server that the item is a form registration object. Then the code sets some properties that tell Exchange Server which commands and requests the form should handle, what languages the form should be used for, and which type the form is. You can have multiple form registrations in a single folder that target similar types of requests but display different forms based on the criteria you set, such as browser, language, or content state. Table 20-2 describes these properties in more detail. Be aware that, when appropriate, properties can support wildcards that allow all values.

Table 20-2: Form Registration Properties

Property	Description
urn:schemas-microsoft-com:office:forms#browser	Indicates the type of browser. This property is useful if you want different forms for different browsers. For example, you can detect a cell phone microbrowser that is making a request and return an appropriate version of the form for that type of browser.
urn:schemas-microsoft-com:office:forms#cmd	Corresponds to a URL querystring Cmd parameter, such as Myurl/?Cmd=Contents . You can also set this property to custom commands that you implement and register. For example, you can have a parameter named NewEvent , which you register for when the URL contains Myurl/?Cmd=NewEvent .
urn:schemas-microsoft-com:office:forms#contentclass	Specifies the content class the form is registered for. You can specify a built-in content class or a custom one.
urn:schemas:microsoft-com:office:forms#contentstate	Checks the form against the urn:schemas:microsoft-com:office:forms#contentstate property. You can set this property to any value you want. For example, you can set contentstate to approved and have a form display the item differently depending on whether the contentstate property is approved or not approved .
urn:schemas-microsoft-com:office:forms#executeparameters	Specifies the parameters to pass to the form rendering engine.
urn:schemas-microsoft-com:office:forms#executeurl	Specifies the URL from which to execute the form. If you're using the built-in renderer, this URL will be /exchweb/bin/exwform.dll . If you're using ASP, you'll want to use the URL of your ASP page as this value because ASP applications don't need the help of exwform.dll for processing.
urn:schemas-microsoft-com:office:forms#formurl	Specifies the URL to the form that should be used to render the data.
urn:schemas-microsoft-com:office:forms#language	Specifies the language of the browser client for which the form should be rendered. This property can be any language code that is valid for HTTP headers.
urn:schemas-microsoft-com:office:forms#majorver	The browser major version.
urn:schemas-microsoft-com:office:forms#messagestate	The message state (such as read or submitted ).
urn:schemas-microsoft-com:office:forms#minorver	The browser minor version.
urn:schemas-microsoft-com:office:forms#platform	Specifies the platform of the browser, such as WINNT or UNIX.
urn:schemas-microsoft-com:office:forms#request	Specifies whether the form is the default for a GET or POST request.

Since WSS Forms build on Web technologies, you can send custom querystring parameters to the form. These parameters allow you to specify custom commands or pass custom variables to your WSS Form.

I already showed an example of registering a form by using the built-in WSS Forms Renderer, so I'll also show an example of a registration that uses an ASP page. This code is taken from the setup program for the Training application. Notice that the FormURL and ExecuteURL parameters differ from the version that we used to register a form based on the WSS Forms Renderer (exwform.dll).

 'Create the registration in the schema folder Set oRec = CreateObject("ADODB.Record") oRec.Open strPath & "schema/webstoreform.reg", oConnection, 3, 0      oRec.Fields("DAV:contentclass") = _     "urn:schemas-microsoft-com:office:forms#registration" oRec.Fields("urn:schemas-microsoft-com:office:forms#contentclass") = _     "urn:content-classes:appointment" oRec.Fields("urn:schemas-microsoft-com:office:forms#request") = "GET" oRec.Fields("urn:schemas-microsoft-com:office:forms#cmd") = "*"      'Put full URL to Web Store forms oRec.Fields("urn:schemas-microsoft-com:office:forms#formurl") = _     strHTTPURL & "/eventwsform.asp" oRec.Fields("urn:schemas-microsoft-com:office:forms#executeurl") = _     strHTTPURL & "/eventwsform.asp" oRec.Fields("urn:schemas-microsoft-com:office:forms#executeparameters") = "" oRec.Fields("urn:schemas-microsoft-com:office:forms#contentstate") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#platform") = "WINNT" oRec.Fields("urn:schemas-microsoft-com:office:forms#browser") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#majorver") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#minorver") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#version") = "" oRec.Fields("urn:schemas-microsoft-com:office:forms#messagestate") = "*" oRec.Fields("urn:schemas-microsoft-com:office:forms#language") = "*"      oRec.Fields.Update oRec.Close 

Another way to register a new form for a folder is by using the DAV:defaultdocument property. This property takes a string that specifies the Web page to open when the user browses to the folder by using OWA. Instead of displaying the contents of the folder when this property is set, OWA displays the custom form. You can easily set this property by using ADO or WebDAV.

Registering WSS Forms Globally

You might want to register a WSS Form globally so that no matter which folder the user is in, the WSS Form appears. For example, you might want to globally replace the standard OWA compose form. When you work with global forms, the forms are registered per store, not per server, so if you have multiple databases on a single server, you must perform multiple registrations. If you run into permissions problems, make sure the system mailbox on your Exchange server has permissions to the folder where you are attempting to place your global form registration. The following code shows how to register WSS Forms globally in Exchange:

 'NOTE: Search for ToDo and when appropriate modify 'the line of code below the ToDo comment      'remember EXOLEDB is covered in Chapter 17 Set igetSG = CreateObject("Exoledb.StoreGuidFromUrl.1")      'Get the guid for the registration process: 'ToDo: Replace Anystoreitem with a proper Exchange URL. Any store item in the ' store will get you the store url. It might be something like: "user1/inbox" Guid = igetSG.StoreGuidFromUrl("http://<servername>/exchange/Anystoreitem")      'ToDo: Uncomment the lines below if registering the form in the Private Store 'regURL = "http://<servername>/exchange/SystemMailbox" & Guid      'ToDO: Uncomment the line below if registering the form in a Non-MAPI TLH 'regURL = "http://<servername>/vroot"      'ToDO: Uncomment the line below if registering the form in a MAPI TLH 'regURL = "http://<servername>/exadmin/admin/domain.com/public%20folders"      If Trim(regURL) = "" Then     Exit Sub End If      'Fill the Default Schema folder with form registrations      Set oCon = CreateObject("ADODB.Connection") oCon.ConnectionString = regURL +  "/##SchemaURI##/microsoft/exchangeV1" oCon.Provider = "ExOledb.Datasource"      oCon.Open      '---------------------------------------------------- 'Register the default page for the folder Set oRec = CreateObject("ADODB.Record")      oRec.Open "CustomFormReg.reg", oCon, 3, 0      oRec.Fields("DAV:contentclass") = _     "urn:schemas-microsoft-com:office:forms#registration"      'ToDo: Change content class to the desired content class oRec.Fields("urn:schemas-microsoft-com:office:forms#contentclass") = _     "urn:content-classes:message" oRec.Fields("urn:schemas-microsoft-com:office:forms#cmd") = "open"      'ToDo: Change to appropriate url form oRec.Fields("urn:schemas-microsoft-com:office:forms#formurl") = _     "http://<servername>/public/pf/form.asp"      'ToDo: Change to appropriate url for your form oRec.Fields("urn:schemas-microsoft-com:office:forms#executeurl") = _     "http://servername/public/pf/form.asp"      oRec.Fields.Update oRec.Close      'Further instructions MsgBox "Copy Form.ASP into the folder that is referenced when setting the " _      & "urn:schemas-microsoft-com:office:forms#formurl. " _      & "Enable script execution on the directory."