Using the Personal Wizards plug-in in IBM Lotus Expeditor

Lawrence Bergman (bergmanl@us.ibm.com), Research Scientist, IBM

Lawrence Bergman received a Ph.D. in Computer Science in 1993 from the University of North Carolina at Chapel Hill. The following year he joined IBM T.J. Watson where he is a Research Staff Member. He has published papers on scientific visualization, human-computer interaction, intelligent user interfaces, multimedia databases, pervasive computing, and programming-by-demonstration. He currently works on recommender systems.

Vittorio Castelli (vittorio@us.ibm.com), Research Scientist, IBM

Vittorio Castelli received a Ph.D. in Electrical Engineering in 1995 from Stanford University. In the same year he joined IBM T.J. Watson where he is a Research Staff Member. He has published papers on computer-assisted instruction, statistical pattern recognition, data compression, image processing, multimedia databases, data mining, multidimensional indexing structures, intelligent user interfaces, reliability of computer systems and software rejuvenation, and on foundational problems in information theory. He currently works on natural language processing and information retrieval.

Summary: This article discusses the Personal Wizards plug-in in IBM Lotus Expeditor. You can use a Personal Wizards model as an automation tool, as interactive documentation, as a tutorial or guided walkthrough, or as a debugging instrument for Lotus Expeditor applications.

Date: 12 Feb 2008
Level: Intermediate
Activity: 846 views
Comments:

The Personal Wizards plug-in in IBM Lotus Expeditor can record the actions of Lotus Expeditor users performing specific tasks and can produce an executable model of the task. Personal Wizards is a tool for recording and replaying tasks on Lotus Expeditor applications. Examples of possible uses for Personal Wizards include:

Creating documentation to interactively guide users through the steps of specific tasks
Automating repetitive tasks for personal productivity
Building tutorials to showcase the features of new Lotus Expeditor applications or of new versions of existing applications
Debugging Lotus Expeditor applications by recording user actions and correlating them with server events

In this article, we demonstrate Personal Wizards through a number of usage scenarios.

Starting the Personal Wizards plug-in

After the Personal Wizards plug-in is installed (see the installation instructions at the Lotus Sandbox on developerWorks), a Personal Wizards menu item appears in the Lotus Expeditor main menu as shown in figure 1. Note that this menu item is displayed only after you launch an application using the launchpad.

Figure 1. Starting Personal Wizards

Choosing the Start PersonalWizards menu item causes the Personal Wizards interface to appear as shown in figure 2.

Figure 2. The Personal Wizards user interface

Creating a document to interactively guide a user through a specific task

The following steps allow you to create a Personal Wizards document using the plug-in:

Recording the task. Begin recording with Personal Wizards by clicking the Record tab. The background in the Personal Wizards window turns to red, indicating that the tool is recording. Now perform the task in the Lotus Expeditor application. Personal Wizards records your actions, creating a document that describes the steps in the task as shown in figure 3.

Figure 3. Recording with Personal Wizards

If you make an error performing the procedure, click the Undo button, which removes the last action from the procedure (but not from the Lotus Expeditor application). You can use the Undo button as many times in succession as needed. If you notice that you have performed extra steps, you can remove them without using Undo; simply highlight the lines in the document by clicking them (press the Ctrl key to select multiple lines, or press the Shift key to select a range of lines), and then press the Delete key.

When you have finished demonstrating the task, click the Stop tab. A Save procedure dialog box appears (see figure 4) that allows you to enter or select a name and a directory for the document. If the document is not to be saved, click the Discard button in this dialog box; note that once it is discarded, the document cannot be recovered. This dialog box also presents the directory in which documents (or procedures) are to be stored, which you can change by clicking the Change button.

Figure 4. Saving the document
Grouping steps within the document. To enhance the readability of your document, you may want to create groupings of steps. Select a contiguous set of steps, and then choose Authoring - Group steps. A dialog box appears that allows you to specify the text for the group; enter the name of the group in the Group Text field. After you enter the text, the selected text appears indented below the group header (see figure 5).

Figure 5. Grouping steps
Annotating steps within the document. Annotating steps within the document can further enhance readability. To annotate a step, select it, and then choose Authoring - Add/edit comment. The Annotate Step dialog box appears (see figure 6) that allows you to specify the comment that precedes the step as a line of green text in the document (see figure 7), new text for the step itself, and text that appears in an in-context pop-up text bubble during playback (see "Automating a Personal Wizards document" later, for an example of such a pop-up ).

Figure 6. Adding an annotation

Figure 7. Annotated document step

Interactive guidance with Personal Wizards

After you create a document with Personal Wizards, you can distribute it to users for interactively guiding them in performing a task. Here are the steps to follow:

Distributing a Personal Wizards document. Personal Wizards documents are stored in ZIP files. These files are stored in a location specified in the Save dialog box in either the default location or a location selected by the document author.
Loading a Personal Wizards document. Documents are loaded using the Load procedure option under the File menu.
Stepping through a Personal Wizards document. After a Personal Wizards document has been loaded, a Playback tab appears in the interface (see figure 8). Clicking this tab causes playback control buttons to appear on a green background. You also see a step highlighted in the document, indicating the starting position for playback. Normally, the step is highlighted in yellow. If Personal Wizards is unable to locate the widget that is associated with this step, the step is highlighted in aqua, and the status area at the bottom of the Personal Wizards window gives information (in purple text) about the missing widget (see figure 9). When a step is highlighted in yellow in the document, the associated widget is circled on the application GUI with a red ring (see figure 10). These are called on-UI highlights.

Figure 8. The Playback tab

Figure 9. The status area

Figure 10. The associated step

Click the Do Single Step button to perform the highlighted step. After the step has completed, Personal Wizards automatically advances the highlighting to the next step. If there are conditional statements (If statements) in the document, Personal Wizards will automatically evaluate them, moving the highlight within the document appropriately.

When the last step in the procedure has been completed, Personal Wizards presents a dialog box that states, "The procedure has completed." Click OK.

Automating repetitive tasks

In addition to allowing step-by-step replay of a task, Personal Wizards also supports full automation. You can automate a Personal Wizards document, or you can create a parameter in a Personal Wizards document.

Automating a Personal Wizards document

Load the document, and begin playback. Click the Do all button to begin automation. The steps in the document are automatically performed until either the task is completed or a step that requires user input is reached. Such a step is said to be parameterized because the specific value that was recorded (in the example that follows, the dollar amount entered into the Total Cash field) has been converted into a user-specified parameter. When a step containing a parameter is encountered, a prompt is displayed on the application UI, and Personal Wizards pauses, waiting for user input. After you perform the UI action required (for example, text entry or list selection), automation continues.

Creating a parameter in a Personal Wizards document

You can convert the widget specified in a particular step in a document into a parameter either while you record the document or at a later time when you use the Edit facility (invoked by clicking the Edit tab, which displays edit controls). Select the step to be parameterized by clicking the step, and then choose Authoring - Parameterize selected step. You are presented with a Parameterize Step dialog box (see figure 11). The Step Text field specifies how the step is described within the document, and it initially shows an automatically generated description. The Popup-bubble Text specifies text that is displayed in context on the application UI when the user plays back the document. The Selection type radio button indicates whether the user is allowed to make multiple selections from lists or only single-item selections. These two options are available only for actions for which they are both possible; the Allow Multi-select option is otherwise grayed out, as in the example shown in figure 11.

Figure 11. Parameterizing a step

When you complete editing by switching to another mode (Stop, Record, or Playback), you are presented with the same dialog box used to save recordings, and you are given the option of saving the edited document or discarding the edits.

Other applications

In this section, we describe two other applications of Personal Wizards: developing tutorials and debugging Lotus Expeditor applications.

Tutorials

You can use Personal Wizards to build tutorials that walk a user through a task. When using a Personal Wizards tutorial, the user is actually performing the task (not merely simulating it) and is given direct on-application guidance (not just a sequence of steps to be read and followed).

Tutorials are built the same way as all other Personal Wizards documents. The difference is the playback experience. When using a tutorial, rather than clicking the Do single step or Do all buttons, the user simply performs the steps. The step to be performed is indicated by the highlight in the document, and where to perform it is indicated by the associated on-UI highlight.

If the user performs a step other than that indicated by the document, the document highlight changes from yellow to magenta, indicating that the user has gone off-track. The off-track highlight remains in the document until the user performs the next expected step in the document, and the highlight then advances and returns to yellow.

This tracking facility also allows a user to jump to a different part of the document. For example, a document may contain some optional steps that a user wants to skip. If the user performs steps from a different portion of the tutorial, the highlighting automatically shifts to that portion of the document.

Debugging Lotus Expeditor applications

Personal Wizards can be used to debug client/server applications by recording client-side interactions. Personal Wizards creates a time-stamped log file of the interactions, which can then be used to correlate with server logs. For more information on this approach, see the "Problem Determination in Enterprise J2EE Systems: Motivating Precision in Root Cause Analyses."

Advanced uses

In this section, we describe some of the advanced features of Personal Wizards.

Combining multiple recordings into a single document

You may encounter situations where the steps in a Personal Wizards document do not correspond to the environment in which the document is being used. For example, the procedure recorded earlier begins with the step, "Double-click on 'Open Customer Session.'" If a customer session is already open, the Open Customer Session option is not available. Instead, a Close Customer Session control is shown in the application UI. In this situation, we need to close the existing customer session before opening a session for a different customer.

You can incorporate this information into the document by beginning a new recording, starting with the existing document. In figure 12, you see the environment, with the Close Customer Session control (and no Open Customer Session control).

Figure 12. A portion of the application GUI showing a change in environment

The steps to update the recording are these:

Load the original document.
Select the Record tab. This causes the first step ("Double-click the 'Open Customer Session'" option) to be highlighted just as when playing back a document. Because the Open control is not available, the highlight is in aqua.
Perform the first step of the task, which is to double-click the Close Customer Session option. Personal Wizards notices that this step is different from the expected first step, and it infers a reason for the difference. Notice in the updated document (shown in figure 13), Personal Wizards has determined that if the Close Customer Session option is available, then it is double-clicked; otherwise, all steps of the first demonstration are to be performed (because the environment of the first demonstration did not contain the Close Customer Session control).

Figure 13. Decision point created by Personal Wizards
Perform the second step of the task, which is to double-click Open Customer Session. Notice that the document changes (see figure 14). Only a single If statement containing Double-click on “Close Customer Session” is retained, and all other steps of the procedure are outside the If statement because both demonstrations contained the step "Double-click on 'Open Customer Session.'" Personal Wizards infers that that step, as well as all steps that follow it, are common to both demonstrations. Notice that the next step is highlighted in yellow, indicating the Personal Wizards guess as to the next step to be performed.

Figure 14. The decision point is complete, and Personal Wizards has resumed interactive guidance
Now, the demonstration can continue by performing more steps manually or by using the Do single step control, or the demonstration can be completed by clicking the Stop tab. When Stop is clicked, a Save dialog box is presented as with the original recording, allowing you to choose between saving the updated document (either with the same name to replace the existing document or with a new name) and discarding the new recording.

On-UI annotations

A useful feature when creating a tutorial is the ability to draw a user’s attention to some feature of the application UI. In the example that follows, the last steps of the procedure are to change focus to the Account Details tab and to check to make sure that the deposit has posted. A pop-up note showing the user what to look for accomplishes this goal. We call these pop-ups on-UI annotations. An on-UI annotation consists of an oval highlight that circles a specific widget on the GUI of the application on which the procedure is performed and of a text box with a message and an OK button. The text box is connected to the highlight by an arrow (see figure 15). When an on-UI annotation is displayed during playback, the execution is suspended until the user clicks the OK button.

Figure 15. An on-UI annotation

Follow these steps to create an on-UI annotation:

Select the step following which the pop-up is to be displayed (that is, on playback, first the selected step is performed, and afterward the annotation displays), and then choose Authoring - Annotate UI item.
Moving the cursor over the UI causes red rings to circle UI widgets. By moving the cursor over the UI, you can highlight different widgets. When the desired widget (the one that is to be annotated) is highlighted, press the F1 key. At any time, you can cancel the operation by pressing the Esc key.
The Annotate UI item dialog box appears (see figure 16) that allows you to specify the comment that appears in the text box of the on-UI annotation. Click OK to create the annotation, or click Cancel to cancel the operation.

Figure 16. Creating an on-UI annotation

Conclusion

The Personal Wizards plug-in for Lotus Expeditor can be useful in a wide variety of scenarios including capturing task how-to's for personal productivity, creating interactive tutorials and guided walk-throughs, and debugging Lotus Expeditor applications. The plug-in provides a simple record/playback interface as well as a variety of advanced features to create rich and powerful interactive task documentation.

Resources

Learn