wareSource.com	Pay for courseware

Description

Notes makes it easy to attach files to documents. Once attached, document readers can double-click the attachment icon to open the attachment in its original application or use the built-in viewer. If the user has Author access to the document, changes to the attachment can be written back to the attachment. Unfortunately, the attachment is opened in a separate window, so if you want to work in both the Notes document and the opened attachment at the same time, you have to resize and position the two windows.

Recently we built an application for a customer that streamlines the accounts payable department. All invoices and supporting papers are scanned and automatically emailed by the scanner into the database using a Memo form with a PDF attached to the Body field. Once the Memo arrives in the database, invoices are moved through fourteen stages of approval and processing. Once processed, the paper copies of invoices are shredded. With the meta data, past invoices can be quickly found through a number of categorized views as well as full text search. Because adding meta data is a manual process, it was obvious that users need to see the invoice scan while they are working; once the approval process is underway, various managers also need to see the invoice scan to make sure it is billing the company for the correct services or goods. This is an example of the meta data entered for an invoice scan (Acrobat PDF plug-in in the right frame):



Using some of the same principles, we designed a generic side-by-side attachment viewer application that can display any file type recognized by Internet Explorer (or if no plug-in is available, by Windows using with software associated with the file type). This example shows an Excel file being attached to a document using a Rich Text Lite field:



Only one file can be attached; in fact, you are prevented from saving the document if there are multiple file attachments:



Click the Save action button to save the document. You cannot press ESC or use Ctrl-S to save the document. You'll see why later why this is a good idea.

Once saved and reopened in Read mode, the spreadsheet opens in the right pane:



To close the document click the red "X" action . In fact, you cannot close the document any other way. This is part of the overall strategy to control how a user opens and closes documents.

Obviously this is only the shell of an application to demonstrate some nifty techniques, and the document doesn't contain much in the way of descriptive information...that is for you to add!

Installation

To install the application, detach the NSF into your Notes Data directory. Better yet to a Domino Data directory. We'll assume that this is a Notes 7.0.2 application running under Windows XP (sp 2).



You should create a non-replica copy of the database and then delete the original NSF.

ACL

Add yourself as Manager with all attributes and roles selected. Then adjust the ACL to match these examples:

	Default for most users who only read documents to view attachments.	Yes, even readers must be Authors in this database. We'll prevent them from creating the "Main" document type with other mechanisms, but they must be able to (transparently) create a "User Profile" document.
	Users who can create documents	Because the Main form uses an Authors field, these users can edit or delete their own documents. You can boost one or two users to have Editor access if you want them to be able to edit or delete all the documents in the database.
	Database administrators who configure the database
	Servers	Manager, all attributes and roles selected.

Because document locking is enabled, be sure to set the Administration server on the Advanced tab in the ACL.

If using the database locally, be sure to select Enforce a consistent Access Control List across all replicas so that the ACL and roles are enforced.

Configuration

Assuming you have the Admin role, you will see this outline when you open the database:



(Users only see the Main outline entry, which opens the Main view.)

Click Blank Attachment. This opens a view that contains one document containing a file you want to display when a user is creating a new document or if a file was not attached. Ours says "Please attache ONE file to the document on the left." and is attached as an HTML file, but your "blank document" can say anything or indeed be blank. Just create it and attach it to the "Blank Attachment Document" document.



The first document is used, so there is no reason to add more than one document in this view.

A User Profile is created transparently for every user. This document keeps a list of all attachments a user has viewed and then uses that list when the user exits the database to clean up the temporary detachments. We will talk more about this later.

This application is designed for educational purposes to demonstrate these techniques:

• Automatic file detachment and use Internet Explorer to view attachments and . Because you cannot programmatically use the built-in Notes attachment viewer, the next best thing is to use the Notes Internet Explorer ActiveX control (and any IE plug-ins you have installed) to view the attachment after it has been detached to disk. To make this easy for the user is a little tricky:
1. When the document opens, the Queryopen event transparently detaches the file to the user's Windows TEMP folder. If there is a file already there with the same name, the new file name is incremented (e.g. myart_0.pdf) until a unique name is created and the file is saved.
2. The Queryopen even also creates a temporary Profile document named TempUserProfile keyed to the user name and sets the FileLocation field to the path/file name where the file was detached. This Profile is never saved (there is a problem using Profile documents and using Document locking) and is only held in memory long enough to pass the filename to the Frameset (and the browser) to open the detached file.
3. The Main form is set to launch inside the DocumentAttachment Frameset. The right frame uses this formula: @GetProfileField("TempUserProfile"; "FileLocation"; @UserName). This formula reads the file name of the last detached file. (Note: When you open and try to save the frameset, Notes thinks it is an invalid URL, but it will work just fine in practice.)
4. Because it is a URL that is to be opened, Notes looks for the browser specified in the Location document (more on that later) and passes the URL to the browser, in this case the URL uses the file:// protocol.
• Automatic cleanup of detached files. In our customer application, we started out using the same file name for every detached PDF so that we didn't fill up the user disk with files. Besides, the scanner named every PDF it mailed to the application the same name. But one of the hard lessons we learned is that the Acrobat plug-in does not like to open multiple files of the same name, especially under Windows 2000. Doesn't like it at all. It also became a problem when the user had multiple documents open, and switched back to the previous window. The image would be wrong. So we learned that when we detach files to disk that we had to name them all differently. The problem of course is now all these files detached to disk. So we decided to keep track of all the file names of detached files, and when the user closed the database, go delete them all. The list is kept for each user in the User Profile documents, which are created and maintained automatically. These are not true Profile documents but are just documents saved off to a dedicated view. And because users must created and edit these documents (through the code of course), they must have Author+ access and be able to create new documents.
• Automatic browser switching. The default browser to use is "Notes with Internet Explorer". This is the one you want so that the IE control opens in the Frameset. But some users have another browser defined, such as "Microsoft Internet Explorer", which doesn't work properly. So when a user opens the database, we make a note of the existing browser being used, if necessary change it to Notes with Internet Explorer, and then when the user exits the database, if necessary change it back to their browser preference. We also do this during the Form Initialize and Terminate events in the event that a user is emailed a document link to the document, in which case the database Postopen event is bypassed.
• Form/field validation in one place. The global variable AllowExit is set to True by the Save and Exit action buttons so that the form Querysave event will happen. But not before the conditions in the Global function OKToSave are met. There is where you will find the validation for the Subject field. OK, we lied. The validation for having more than one attachment is actually done in the Queryclose event of the form. This is because the rich text field containing the attachment isn't readable until after the document has been saved. So we do that checking after it is save, and also run a library function SetFN to extract the attachment name and put it into a regular text field (both for the view and to easily detach the file later).
• Automatic conversion of a Memo upon paste (or any other document where a single attachment is stored in the Body field). Only the Main view allows users (with Author/can create access and in the [CreateMain] role), but this view also has a little code in the Postpaste event that moves the attachment from the Body field into the field we are using.
• Exit Notes agent. Hopefully you will never need to use this (from the Actions menu). We found that at random times the Acrobat plug-in (or is the IE control?) puts Notes into a "funny" (not ha ha) state where the bookmarks disappear and the user cannot choose File - Exit Notes. Everything else seems to work, just you cannot exit. So this agent (Actions - Exit Notes) shells out to the operating system and runs NSD -kill. Not pretty, but it works (and the user doesn't need to reboot Windows to start Notes).

There are some other supporting techniques, but we'll let you discover these on your own.

This is an unsupported application, but if you have any recommendations for bug fixes or new features, please

Conditions of Use

©2007 wareSource.com

You may use this application free of charge. You cannot use it to develop a commercial product or benefit financially or otherwise from the sale of this product.

This application was developed as an educational tool and may not be complete or ready for production use. Use this application at your own risk and only after extensive testing to ensure that it is appropriate for your needs. wareSource assumes no responsibility for errors or omissions, nor for the uses made of the application and the decisions based on such use. No warrantees are made, express or implied, with regard to either the contents of this work, its merchantability, or fitness for a particular purpose. wareSource shall not be liable for direct, indirect, special, incidental, or consequential damages arising out of the use or inability to use the application. You may use the application but cannot sell the application or techniques or use the formulas in other applications. In no event shall wareSource be liable for any damages whatsoever (including without limitation, damages for loss of business profits, business interruption, loss of business information, or any other loss) arising out the use of or inability to use the application, even if they have been advised of the possibility of such damages.