Authors Note: Lotus Domino (a.k.a. Notes) will be running native on the AS/400 by the first quarter of this year. Domino will use AS/400 databases as native Notes databases; AS/400 directories will be utilized by Domino. Huge possibilities will exist for Web applications to exchange data with the AS/400 back-end systems. In this article, Ill show you one possible implementation of this exciting new capability. If you want a hands-on trial of the Web site Ill be describing in this article, go to URLwww.zerk.com/ customer.nsf.
What a tremendous day! The clear, azure sky allows the bright sun to warm the earth. The birds in the sky dance like the blinking lights on the bank of Lotus Notes servers in James office. James sits in his chair breathing restfully as he surveys his servers and behind them, outside the window, the glorious scenery. Suddenly, James leans forward and peers intently out the window; an ominously dark cloud is cruising toward Zerks Unlimiteds corporate headquarters. The phone rings...
An hour later, James hangs up the telephone. Apparently, the guys over at Widgets, Inc. are using Domino and the Internet to arm their traveling sales force with up-to-the- minute information from the corporate miniframe via the Web. James told his boss Jay Griffiths about the technology months ago when Widgets, Inc. began selling its products on the Internet, but it took a three-point jump in Widgets stock to convince Jay of the power of Domino.
About a month ago, James installed Domino 4.6 on one of Zerks dual-processor AS/400s and has recently decommissioned his main production Domino/Notes NT box to a second development/test server. He can just feel the power of Notes running native on the AS/400 as it sits waiting to serve thousands of people. Each day, James looks forward to the moment when he can access his new Domino server from the Notes Designer for Domino 4.6 running on his Windows 95 workstation. (Designer for Domino has replaced the now defunct Full Client version of Notes.)
In this article, I will investigate the Hypertext Transfer Protocol (HTTP) process and Web development on the Lotus Domino 4.6 server. I will show you how to first prime your server for the HTTP process by investigating the HTTP section of the Server document in your Name & Address Book (NAB) and starting the HTTP task. I will then show how a basic Notes database evolves into a working Domino application. James first stop is in the office of Catherine, the WAN guru, who will set up the Domino servers IP address and modify the firewall security.
At the heart of every Domino server is the Name & Address Book (NAB), which contains important configuration documents, including Person, Group, Connection, Server, and others. For every Lotus Notes license used, a Person document is created. These People make up Groups, which are used for security purposes and mailing lists. The Connection documents allow servers to replicate and route mail among themselves. The Server document is the primary mechanism for configuring zand customizing your Domino server.
Figure 1 shows a partially expanded Server document for the server known as Chaos. Chaos is the server James has been using to develop Notes databases that will be accessed through a Web browser (Netscape or Internet Explorer), but more on that later.
Lets focus first on the HTTP section of the Server document. For the most part, you can leave the default values in place. I highly recommend changing two values. The Allow HTTP clients to browse databases parameter defaults to Yes, but should be switched to No in most cases. Even if the databases dont allow anonymous access, its still not a great idea to let people see the titles of all the databases on the Domino server. If the value of this parameter was set on James system to Yes, a hacker who enters the URL http://www. zerk.com/customer.nsf?OpenServer will see a listing of all databases on that server. When the value is changed to No, the same URL command will yield the following text: ERROR 403: HTTP Web Server: Database Browsing Not Allowed. The default value for the Home URL field should include the home page database name. James decided to name his database CUSTOMER.NSF, so the value for Home URL is customer.nsf/?Open. I also recommend that you add a Host name value and remove the Default home page default. Web browsers use the Host name parameter to reach the Web server. You can enter either the Domino servers IP address or the machines name. James has entered the host name (www.zerk.com), but could have easily have entered the machines IP address
(126.96.36.199). If James leaves the Host name field blank, Domino will default to the host name in the machines TCP/IP stack. The Default home page field is used when you would rather use an existing HTML file than a Notes database as the home page. This HTML file would need to be placed in the HTML directory as described in the Server document. However, James is very excited about developing an entire database, so he left that field blank and put the database name in the Home URL field as referenced in Figure 1.
Once the Domino server is configured, it has to be rebooted before the changes take effect. Before James does that, he has to add the HTTP task to the ServerTasks list in the NOTES.INI file. (The AS/400 uses the NOTES.INI file just as a machine running Windows NT or OS/2 does.) Using ClientAccess/400, he will link to the root directory of the Integrated File System (IFS) and use a text editor such as WordPad to open the NOTES.INI file located there. He will simply locate the ServerTasks line, add HTTP to the end, then save and exit. When the Domino server is restarted, the HTTP task should start up.
James has already created a Notes database with a DOS name of CUSTOMER.NSF to match the Home URL entry in the Server document. To view the database through the Web, James will go to Netscape and type in the URL www.zerk.com. Figure 2 shows us the plain Notes database as shown through HTML without any tweaksyou see the database icon, title, and a listing of all the views. Lotus has provided a wealth of development tools in 4.6, which James will demonstrate.
First, lets check out Dominos database security. Databases are regulated with seven levels of access, ranging from No Access to Manager. You assign people or groups
to a particular level of security, depending on their role in the database. As you can see in Figure 3, there is an entry in the Access Control List (ACL) titled Anonymous. Web users will access this database with the security level of Anonymous, in this case, this means as an Editor without delete capabilities. In the absence of the Anonymous entry, Web users will access this database as dictated by the -Default- entry. However, it is great to be able to distinguish between Web users and Notes clients in the ACL. James has set this databases -Default- entry to Reader so that Notes clients can only read documents from the database and can not modify or delete them. He also wants the marketing department personnel (represented by the Notes group named Zerk.Marketing) to have Author access so they can act upon any requests by creating response documents. And, of course, James is in the Zerk.Admin group, which has Manager access. Manager access allows James to work on the design of the database, change the ACL, delete the database, and perform other manager-specific tasks.
If James wanted a more granular security scheme, he could implement individual login accounts on the Domino server. One of the possibilities would be to set Anonymous in the ACL to No Access. This would force anyone accessing the server from a Web browser to go through a login procedure. In Figure 4, you can see that the Web password is encrypted and stored in the Person document in the field titled Internet password. This field can either be set manually or set automatically from a registration Web site. Check out http://web7.notes.net/pubdown.nsf/categories to download the Registration database. Its obvious to say that secure Web sites, such as a Widgets sales force automation site, should have individual login accounts, but the Zerks customer site doesnt need that level of security. However, if Zerks decides to sell its product in the Internet, then a more secure site would be mandated.
As you may have guessed, James is developing a Domino application to encourage customer feedback from the Internet. There is a link named Whats New!, a link for discussion forums, and a link called Customer Feedback. The first two links will be driven from Notes views and the third link will be a Notes form. The Whats New! link lets Zerks communicate information to the general population, while the discussion forum is a vehicle to encourage interaction between the Internet community and the Zerks marketing group. Finally, the suggestion forum is a great way for people to communicate their ideas for improvements in Zerks products. We will watch as James improves the look and feel of the home page, then develops each link.
James has decided to use the Notes About document for the Zerks home page. He could have also chosen to use either a Notes navigator or an HTML document. Figure 5 shows the Properties box for James databases. Under the Launch tab, you will notice that the On Database Open parameter is set to Restore as last viewed by user and the On Web Open parameter is set to open About database document. This second parameter is new in Notes 4.6; it allows a database to launch in different ways depending on how the database is accessed. James wants the Notes launch option to remain the same as it has been, but he wants Web users to open up to the About database document, so he set the On Web Open option to Open About database document. Of course, James has created the About database document; it is shown Figure 6.
The completed About database document as displayed by a Netscape browser is rendered in Figure 7. It took James about five minutes to complete the document. The Whats New! and Product Discussion links are actually Notes views. To create a view link, James first went to the Whats New! view from the Notes navigator and selected Edit/Copy As Link/View Link from the menu options. He then went to his newly created About document, typed Whats New!, highlighted the phrase, and executed the menu option Create/Hotspot/Link Hotspot. You will notice the link placed a green box around the text (Figure 6). James repeated the process for the Product Discussion view. Notes does not provide the same linking facility for forms, so James had to create a URL link. He typed Customer Feedback, highlighted the words, and chose Create/Hotspot/URL Link from the Notes menu options. This brought up the Properties box for the URL Link Object. Under
the first tab, he typed /customer. nsf/Web+Feedback?OpenForm&subject=Customer+Feedback and selected the Show border around hotspot option. James knows that URLs do not support the space character, so he substituted a plus sign (+) for each space character when coding URL links. Incidentally, James could also have created URL links for the aforementioned views using the following code:
* /customer.nsf/Whats+New!? _ OpenView * /customer.nsf/Product+ _ Discussion?OpenView To finish off the About document, James centered a title at the top, pasted in the Zerks logo, and included a horizontal rule, some company information, and a Common Gateway Interface (CGI) hit counter. Ill explain more about CGI in the Tips and Techniques section of this article.
Great graphics are an important part of an excellent Web site. Lotus Domino provides two ways to add graphics to your Web site. You can paste any BMP, GIF, JPEG, TIFF, or PCX graphic into a Notes document. This first method does not allow you to use animated GIFs. An alternative method that does allow animated GIFs uses the HTML tag to reference graphics files stored in one of two places. The easiest method is to copy the files into the icon directory, which is configured in the Server document (see Figure 1). However, this method has two major disadvantages. First, you need to have direct access to the Domino server's file system. The other disadvantage is that the Domino application is not truly portable from server to server. You not only have to copy/replicate the NSF file, you also have to remember to copy all the external graphics files. Figure 8 shows us the graphics storage facility that James is using for the Customer Feedback application. This repository is basically an additional view and form within the database. The form has two fields: a text field for the graphic's name and a rich text field into which you attach the graphic file. The view sorts these documents on the graphic's name as entered in the text field. James has also added three more columns for greater usability: graphic size, graphic file name, and create date. These graphics are accessed using the following HTML code:
To further understand, lets dissect the URL in the listed HTML code:
/customer.nsf directs the Web browser to the CUSTOMER.NSF Notes database.
/GraphicView directs the Web browser to a view titled GraphicView in the database.
/NEW01/ further directs the Web browser to the NEW01 document as sorted in the aforementioned view.
$FILE/NEW01.GIF opens the file named NEW01.GIF in the previous document. Lets look at the first link James has created for his Zerks home pagethe Whats New! view. Figure 9 shows how this standard Notes view appears in Netscape. Visitors can click on the date of any documents they would like to view. James has set up the document so that Web surfers can easily return to the Whats New! page. Domino uses the Notes view title as the Web browser title and Web page header, inserts the column headers above each view column, and adds the graphics at the top and bottom of the page. However, Domino does not maintain the column width when translating the Notes view in HTML code. James felt that the native Notes view displayed fairly well in Netscape, but wanted to make one modification, which is the addition of the NEW and UPDATED graphics. The column formula takes advantage of the graphics storage facility as detailed in Figure 8:
@If(@Adjust(@Created;0;0;7;0;0;0) _ > _ @Today; ; _ @Adjust(@Modified;0;0;7;0;0;0) _ > @Today;[
/customer.nsf/GraphicView/ _ UPDATED/$FILE/UPDATED.GIF _ ALT = updated BORDER= _ 0>];) Basically, this code says that if a Notes document is less than a week old, a NEW graphic is placed to the right of the description. If the Notes document had been edited in the past week, an UPDATED graphic is displayed. This column formula demonstrates that you can combine Notes @functions with HTML code.
James has also developed a second view for Zerks home page. Instead of using the default view that Domino serves, as is the case with the Whats New! view in Figure 9, James wanted a more customized look. Domino facilitates this customization in two ways. The first method is to use a form named $$ViewTemplateDefault. As the name implies, this template will apply to all Domino views as shown through a Web browser. If you need unique customization for each view, you can use a form named $$ViewTemplate for
James has found that unlike the Notes environment, developing a good Web site can be more difficult in that the current Web page knows nothing about the page where the person was before, or where the person will be going next. In Notes, we are accustomed to features like inheritance, which do not exist on the Web side. Fortunately, a couple of tools can circumvent this problem. In the Customer Feedback form, James has addressed the problem with two techniques. Lets first look at the method for passing parameters in the URL. James wants to use the Feedback form in several locations on the Zerks home page, but would like the Subject field customized for each location. For instance, when the form is accessed from the Product Discussion page, he would like the words Product Discussion to appear in the subject, whereas in the Customer Feedback section, James wants to see Customer Feedback displayed in the Subject field. To do this, James will use the URL to pass the Subject field value between Web pages. As seen in Figure 6, James has used the following URL from the Zerks home page to the Customer Feedback page:
/customer.nsf/Web+Feedback? _ OpenForm&Subject=Customer+ _ Feedback All data after the Ampersand (&) will be placed in the Query_String field. James has then programmed the Subject field to parse out the values it needs from the Query_String field and replace the plus sign (+) with a space. This is accomplished with the following formula:
@Implode(@Explode(@Right(Que _ ry_String;Subject=);+); ) Of course, James will need to use a more complicated string parsing formula (using @Left and @Right) if he ever passes more than one variable/value pair in the URL.
Second, James has used cookies to save some user data for future use by the Web browser, in this case, the Web surfers names and telephone numbers. You can equate cookies to Notes environment variablesthey both save a variable with its value on the clients machine in an ASCII file. The HTTP_ COOKIE field is used to store the cookies that are set by the CGI variables.
To set the cookies, James has used some passthrough HTML code in the $$Return field (see Figure 11).
01-Jan-2002 12:00:00 GMT>+ As seen in Figure 12, James has coded the Your Name field with the following code that parses out name cookies as set in the previous HTML code.
tName := @Right _ (HTTP_COOKIE;UserName=); @If(@Contains(tName;;);@ _ Left(tName;;);tName) The $$Return field is significant in that the code in this field is executed when the Submit button is pressed. In this example, the Send Feedback button is actually the Submit button. As you can see in Figure 13, the button text is used as the button descriptor on the Web side. If James had left the button text blank or had not placed a button on the Notes form, the Web browser would display a button labeled Submit. Any code in the actual button is ignored when activated from the Web side, only the code in the $$Return field is executed. The Query_String, HTTP_COOKIE, and $$Return fields (see Figure 13) are hidden from both the Notes client and Web browsers. Figure 12 shows the page rendered in HTML.
Tips and Techniques
In order for the search function to work, as seen in Figure 9 and Figure 10, you must also create a Full Text Index for the database on the Domino server. To create a Full Text Index, first go to the database Properties box, then press the Create Index... button under the Full Text tab. I would also suggest using the Exclude words in Stop Word file option.
Normally, the first noncategorized column in a view is the default link column. Figure 14 shows a Properties box for a view column, which allows you to change the link column.
Since tabs are not included in the HTML standards, use a two-column table in your Notes form to separate the field and associated static text. Remember to uncheck the Fit table to width of window option.
Horizontal rules, anchor links, and background graphics are both supported in native Notes 4.6.
CGI scripts work great on the Domino server. Place the files in the CGI-BIN directory as set in the Server document in the NAB and reference the binaries in your HTML code. James has a counter on the Zerks home page coded as:
James has demonstrated some of the basics of development of Domino applications for Web browsers; you can now build on this knowledge to create Domino Web applications for your intranet or the Internet.
Figure 1: The Server document for the server known as Chaos
Figure 2: The default Notes database shown through a browser
Figure 3: Dominos Access Control List (ACL) feature lets you control how users work with databases.
Figure 4: A users Web password is encrypted and stored in the Person document in the field titled Internet password.
Figure 5: The Properties box for James databases
Figure 6: The Notes About document is being used as Zerks home page.
Figure 7: The completed About database document looks like this when viewed through a Netscape browser.
Figure 8: The graphics storage facility that James is using for the Customer Feedback application is essentially an additional view and form within the database.
Figure 9: The Whats New! View is a standard Notes view displayed in Netscape.
Figure 10: The $$ViewTemplate for Product Discussion has a ViewTitle field, an Embedded View Web Element, various graphics, and accompanying static text.
Figure 11: James is using passthrough HTML code to set cookies.
Figure 12: James has set up the Your Name field in the feedback form to parse out name cookies.
Figure 13: The button text in the Notes feedback form used as the button descriptor on the Web side.
Figure 14: When you open a Properties box for a view column you can change the link column.