by Firas Yasin

Level: Intermediate Works with: QuickPlace Updated: 03-Sep-2002

Of all the features QuickPlace offers, one of the more attractive is its capacity to let you customize and extend its functionality to suit your particular needs. This month's issue of LDD Today includes two article describing customization techniques that include using PlaceBots. (PlaceBots are special programs for performing a specific task. They are similar to agents in Notes/Domino.) In addition to this article, "Adding calendar roll-up to QuickPlace" explains how to combine calendars for multiple inner rooms and display them as a single calendar in the main room.

In this article, we describe another way you can customize QuickPlace, in this case enhancing its workflow. Our example extends QuickPlace's out-of-the-box workflow capabilities by providing a PlaceBot for automatically moving selected documents into an appropriate folder. We start by explaining what our example does and then give step-by-step instructions for incorporating the PlaceBot, which you can download from the Sandbox, into your own Place. This article assumes you're an experienced QuickPlace developer and are familiar with QuickPlace terminology.

Understanding the approval process workflow
Imagine your Human Resources department generates a document whenever a new employee is hired. These documents then need to be placed into the proper department folders for further processing. For example, if Sandy Smith is hired by your company, the applicable HR people must approve the New Employee document. This approval is done using standard QuickPlace workflow functionality. Once the final approver gives the go-ahead, Sandy Smith's document must be transferred into the personnel folder of the hiring department (for example Marketing).

To automate this process, we created a PlaceBot. This PlaceBot runs nightly to move these new hire documents from a folder called Approved to the appropriate department folders. The following graphic illustrates this process.



To implement this workflow process, you must:

• Create the appropriate QuickPlace folders. This includes the Waiting Approval and Approved folders, as well as the department folders (in our example, Marketing, Engineering, and Sales).
• Create a form for New Employee documents.
• Load the PlaceBot we provide, and schedule it to run with the scheduler

The following sections explain how to perform these three tasks.

Creating the folders
The first step in setting up the approval workflow is to create the folders to contain New Employee documents. To create folders, you must be logged in as a manager of the Place:

1. At your home QuickPlace page, click New.
2. Click the Folder radio button and then click Next. (If the Folder option doesn't appear, you may not be logged in as manager.) The New Folder page appears. This lets you select the type of folder you want to create (Discussion, Simple List, Headline, Slide Show, Ordered List).
3. Click Standard List, and then click Next.
4. In the “What is the title of this folder?” field, type Waiting Approval. Then click Next.
5. Select the location for the folder (the order in which it appears in the sidebar), and click Next.
6. Repeat this procedure for the remaining folders: Approved, Marketing, Engineering, and Sales.

You can also restrict the access of who can add pages to the folder to managers only. (We recommend you do this for the department folders and the Approved folders.) By doing this, you ensure that a document can't be added to any of these folders without being approved. You can restrict access by clicking the Only managers radio button when you choose the name of the folder.

After completing these steps, your welcome page should be similar to the following:



Creating the New Employee form
Now that your folders are in place, it's time to design the form to use when creating New Employee documents. As when creating the folders, you must be logged in as a manager of the Place:

1. After you log into your Place, click Customize on the sidebar. This displays the Customize page.
2. Click Forms, and then click the New Forms button.
3. Click the Simple Forms radio button, and then click Next. The New Forms page appears.
4. Enter New Employee in the “What is the title of this form?” field.
5. Click the Add button to add fields to the New Employee form. This displays the Add Field page.
6. Click the Plain Text radio button and click Next.
7. Enter a title for the field (for example, First Name) and click Next.
8. Repeat steps 5 through 7 for all the fields you want to add to the New Employee form. When you have finished, you must add one final field.
9. To do this, click Add. Then click the Pop-up List radio button, and click Next.
10. Enter Department in the title field.
11. In the Pop-up Choices field, type the appropriate department names (in our example Marketing, Engineering, Sales).
12. Click the “Alert the author if they forget to fill out this field” checkbox. At this point, your screen should look similar to the following screen:
    
    
    
13. Click Next. The New Forms page appears again.
14. Go to the Workflow section of the page, and click Modify.
15. Click the Approval Cycle radio button. Click Next to move to the next page.
16. In the "Who needs to approve this page" section, choose the names of the users in the Place by clicking the drop-down box and selecting the appropriate names. Note that you can enter up to four steps in the approval process, so that if a document is approved by the user named in step 1, it is routed to a user named in step 2, and so on.
17. In the “Do you want pages that are pending approval to be placed in a specific folder?” section, click the drop-down and select Waiting Approval. This will place any document waiting approval in this folder, providing a central location for users to check.
18. In the “Should the page be moved anywhere special after final approval?” section, click the drop-down box and choose Approved. This option will move approved documents to the Approved folder.
19. Fill out the remaining sections of the form as appropriate for your site. When you are finished, click Next, and then click Done to save the New Employee form.

You have created a new form that will place documents in the Waiting Approval folder. Documents will reside in that folder until the final approver checks off on it. Once that is done, the form will automatically move the document into the Approved folder.

The New Employee form you have just created can move approved documents into the correct folder. It can't, however, analyze the content of a particular field and route documents into the appropriate folders accordingly. This means the form cannot move New Employee documents into the folder for the correct hiring department. For that, you need a PlaceBot—which we'll describe next.

Creating the PlaceBot
Our PlaceBot is a Java program that runs within your Place. It looks in the Approved folder for any documents awaiting routing to the appropriate department. When the PlaceBot finds a document, it reads the value in its Department field. The PlaceBot then moves the document into the correct department folder.

To create the PlaceBot, you must first download its Java file (or .class file, if you do not want to see the actual code) from the Sandbox, and place it in a local file folder on your PC. You can compile the Java file and upload the .class file to QuickPlace, or you can upload the Java file directly. In our example, we will use the .class file.

You, as creator/signer, must have access to all folders and documents processed by this PlaceBot for it to run properly. To create the PlaceBot:

1. Log in as manager to your QuickPlace’s home page, and click Customize. Then click PlaceBots to see the PlaceBots page.
2. Click the New PlaceBot button to see the New PlaceBot page.
3. In the "What is the title of this PlaceBot?" field, enter DeptSorter.
4. In the "When should this PlaceBot run?" field, click the “On Scheduled basis” radio button. Then click the Set Schedule button to display the PlaceBot Schedule page.
5. In the “What pages should the PlaceBot affect?” section, choose “All the pages in this room” from the drop-down menu.
6. In the "How frequently do you want the PlaceBot to run?" section, select the frequency you would like the PlaceBot to run (monthly, weekly, daily, and so on). As you do so, try to strike a balance between extra load placed on the server and the requirements and expectations of your users. For example, you can choose to run DeptSorter once a month, but your users may feel they need more frequent updates. Conversely, you could theoretically schedule the PlaceBot to run every minute, which might give your users instantaneous updates but would obviously place additional load on the server. We recommend you run DeptSorter daily, preferably at night when not many people are working.
7. After completing the schedule, click Next. This returns you to the New PlaceBot page. You must now load the code we have provided.
8. Click the folder icon near the bottom of the page and select deptsort.class from the dialog box. (Your page should be similar to the following screen.) Then click Done.

After you click Done, QuickPlace displays a message stating it is uploading the .class file. When the upload is complete, the PlaceBots page reappears.

Testing the new approval process
Now it's time to see whether or not you've done everything correctly. To test the approval process, first create the New Employee document:

1. With your home page displayed, click New. The New Employee form should be listed as a radio button on the New page. If not, go back to the "Creating the New Employee form" section and complete its instructions. If the New Employee option is available, click it and then click Next.
2. Complete the New Employee form. For example, here is a simple version of the form, filled out with Sandy Smith's information:
   
   
   
3. When you are finished, click Submit to see the Submit page. You can submit with or without explanation, or you can save the document as a draft. You can also select another folder in which to place this document. The default is the Waiting Approval folder, so for testing purposes leave this unchanged and click Next.
   

The page will be placed in the Waiting Approval folder (which you can open to make sure everything's working properly). After all the required users approve this document, QuickPlace automatically puts it in the Approved folder. (Again, you can check on this by opening the Approved folder and ensuring approved documents have been routed there.)

Next you can run the DeptSorter PlaceBot to move the document to the appropriate department's folder. You can log into the QuickPlace as a manager and run the PlaceBot manually or wait until the scheduled time. For testing purposes, you can do this manually:

1. From your home page, click Customize, and then click PlaceBots. The DeptSorter PlaceBot should be listed as a radio button.
2. Choose the DeptSorter PlaceBot and then click the Run PlaceBot button.

DeptSorter runs, routing any documents in the Approved folder to the appropriate department folder. To do this, DeptSorter performs the following steps:

1. Initiates the department sort session.
2. Identifies the current database (file name, title).
3. Checks to see whether the database includes the Approved folder. If not, DeptSorter returns an error; otherwise, it proceeds with the session.
4. Checks the Approved folder for documents. If any exist, DeptSorter reads the first document.
5. Checks whether or not the document includes a valid Department value.
6. Copies the document into the appropriate department folder, based on the value of the Department field, and removes the document from the Approved folder.
7. Repeats steps 4 though 6 until all documents in the Approved folder are processed.
8. Ends the session.

To check whether DeptSorter has run properly, open a department folder and make sure your test documents have been placed where they belong.

For added security, you can modify DeptSorter to route the documents into department rooms instead of folders to store the final approved document. (QuickPlace rooms are Domino databases, folders are views within databases.) Note that the sample code we provide for DeptSorter includes explanatory comments, which you can follow to help you modify the PlaceBot if you choose.

Customizing QuickPlace: Endless possibilities
Our relatively simple example demonstrates one way you can extend the power of QuickPlace and adapt it to your own particular needs. Feel free to experiment with our sample code, especially if you're experienced with QuickPlace programming. To learn more about PlaceBots and other QuickPlace development features, see the QuickPlace documentation, available for download from the Documentation Library, or consult the IBM Redbook, Customizing QuickPlace.


ABOUT THE AUTHOR
Firas Yasin is a Software Engineer for IBM, providing pre-sales support for several Lotus products. He currently concentrates on QuickPlace and Sametime development and customization. He is also one of the authors of the IBM Redbook Working with the Sametime Community Server Toolkit. A University of Kentucky graduate, Firas lives in Lexington, Kentucky and enjoys tennis when he's not working.