Extending the Domino Administrator

by
Thomas
Gumz

Level: Beginner
Works with: Domino 5.0
Updated: 01-Nov-99

Did you know that you can teach Domino Administrator new tricks?

The Domino R5 Administrator not only introduces a graphical interface for working with your servers, but it also allows you to customize and extend the interface for third-party server tasks! You no longer need to know the names of server tasks and their exact command line parameters. If you consider that the shipping Domino R5 server has approximately 44 server tasks (excluding third-party tasks, such as virus checkers and more), Domino Administrator can give you a head start on using these server tasks. What's more, you can monitor all of these tasks in the Server Monitoring tool built right into Domino Administrator!

This article shows you how the Domino Administrator interface makes managing tasks easy. If you're a Lotus Business Partner or ISV who develops custom server tasks, you'll also learn exactly how to enable your tasks for display in the R5 Server Monitoring tool. To do this, you'll learn how to define new task forms and how to debug them until they work right for you.

Note: This article focuses on just some aspects of Domino Administrator. For detailed information on all the things you can do in Domino Administrator, see Domino Administration Help.

The interface for server tasks
You can use Domino Administrator to both start and stop server tasks, and to issue Tell commands. For example, consider if you wanted to run an incremental fixup of a database without purging corrupted documents. And when doing so, you also wanted to exclude views to make the whole operation a little faster. Before R5, you'd need to know the exact command line parameters for doing this at the console. Now, you can do it graphically with Domino Administrator.

To run the Fixup server task:

In Domino Administrator, click the Server - Status tab.
From the Task tools, click Start or right-click in the upper tasks pane and select Start New Task.
In the Start New Task dialog box, select the Fixup task and make sure that "Select advanced options" is enabled.
Click Start Task.
On the Basics tab, select to run Fixup on all databases, or only on specified databases or folders on the current server.
Click the Options tab and select the desired settings. Then click OK.

Domino Administrator now sends the required command to the server (which, in this case, is LOAD FIXUP -V -I -N).

Whenever you want to start a new task and the "Select advanced options" checkbox is available, Domino Administrator includes a dialog box with all the options for the selected server task.

Now, what about the Tell commands, such as TELL ROUTER COMPACT? Not to worry, Domino Administrator covers these too. For example, you can use Domino Administrator to tell the Router task to compact the server's MAIL.BOX file or files.

To issue a Tell command:

Select the Router task in the list.
From the Task tools, click Tell, or right-click anywhere on the pane and select Tell Task.
In the Tell Router dialog box, select "Compact mailbox file(s)" and click OK.

Domino Administrator now sends the corresponding command line TELL ROUTER COMPACT to the server.

Monitoring your server tasks
The other main area where server tasks play a vital role is in the Server Monitoring tool. If you want to monitor additional server tasks, you can easily add them to the Server Monitoring user interface. (Look for an article on the Server Monitoring tool in an upcoming issue of Iris Today.)

To monitor server tasks:

In Domino Administrator, click the Server - Monitoring tab.
Select "By State" in the list box.
Choose Monitoring - Monitor New Task for All.
In the Monitor New Task dialog box, select a new server task to monitor.

Registering custom server tasks
Now, let's start extending! To let Domino Administrator know about your custom server tasks, you need to first register them. You can register server tasks in the Domino Administrator database (DOMADMIN.NSF) as form design elements. You just need to create a new form.

The easiest way to create your own server task form is to copy and paste an existing server task form and use it as a boilerplate. This way, you don't need to create the task form from scratch. Let's say that you want to register a Virus Checker server task, and that you just want to be able to monitor it. (Registering a server task for monitoring is easier than adding GUIs for Load and Tell commands.) So, you can use the Billing task form as a starting point, because it doesn't contain GUIs for Load and Tell commands.

To register your server task just for server monitoring:

In Domino Designer, open the Domino Administrator (R5) database (domadmin.nsf) on your local system.
From the list of forms defining the server tasks, select the "Task \billing" form.
Choose Edit - Copy, and then Edit - Paste.
Click No when prompted whether this form should be automatically updated from the template. This makes sure that your custom form doesn't get replaced or overwritten when the design of the domadmin.nsf database gets refreshed in future releases.
Open the new "Copy of Task \billing" form that now appears at the top of the form list.
Choose Design - Form properties.
You now need to name the form so that Domino Administrator recognizes it as a server task definition. To do this, you must use the following syntax:

Task\name | task_name

where name is the server task filename that you would use for loading the task at the server console. For example, if you would type LOAD ANTIVIRUS to load the server task, the form name should be "Task\antivirus | task_antivirus." So, enter this form name in the Name field of the Form properties.
In the Comment field of the Form properties, enter a brief name for the server task, such as "Anti Virus server task." We strongly recommend following that naming convention, which is used by the other task forms in domadmin.nsf.
Save and close the form.

Verifying the form name
You can use a built-in debugging facility to verify that the form name is correct. This is important because if the form name is not correct, Domino Administrator rejects the form as an invalid server task definition.

To verify that your form name is correct:

In the forms list for domadmin.nsf, choose View - Go To.
Select Main and click OK. The Main view opens.
In the Main view, click the Debug task form button.
Verify that your new Antivirus task appears in the "Debug task forms" list. If it does, this means that the form is correctly recognized!

Enabling the form for server monitoring
To enable your new task form for use in the Server Monitoring tool:

In the forms list for domadmin.nsf, open your new task form and complete the fields listed in the table below. All other fields on the form are used only for the LOAD and TELL GUI dialog boxes.

Field name What to enter

Task_name The descriptive, "friendly name" of the server task. Domino Administrator displays this name in the dialog boxes when you start the task. For example: ACME Domino Anti-Virus Scanner.

Task_filename The file name of the server add-in task, excluding the first platform qualifier character. This is the file name that you enter at the server console to load the task. For example: antivirus.

Task_monitorname The name of the server task as it shows up in the "SHOW TASKS" output on the server console. If this name doesn't match the console add-in name, the Server Monitor can't detect it. So, make sure that the name is correct.
For example, the Monitor name for the HTTP server task is "HTTP Web Server."

Task_description A description of the server task. Domino Administrator displays this description in the dialog boxes when you start the task. For example, the HTTP Web Server description says "Enables the Domino server to act as a Web server so browser clients can access databases on the server."

Congratulations! You have successfully defined a custom server task form for the Server Monitoring user interface!

In order to include the newly defined task, make sure to restart Domino Administrator in order to see the new task form.

ABOUT THOMAS
Thomas Gumz is currently the Product Designer in the Domino Server Administration Group. While at Iris, he designed the new Domino R5 Administrator Client and also developed the underlying domadmin.ntf template. Now he is busy working on improving the Domino Administrator Client and rewriting its web-browser equivalent, the Domino Web Administrator UI. Previously, Thomas spent 2 years working in Lotus Product Management as the Lotus Notes for Windows NT Platform Product Manager. Lately he has also been seen cruising around in his new TT Coupe!

Field name	What to enter
Task_name	The descriptive, "friendly name" of the server task. Domino Administrator displays this name in the dialog boxes when you start the task. For example: ACME Domino Anti-Virus Scanner.
Task_filename	The file name of the server add-in task, excluding the first platform qualifier character. This is the file name that you enter at the server console to load the task. For example: antivirus.
Task_monitorname	The name of the server task as it shows up in the "SHOW TASKS" output on the server console. If this name doesn't match the console add-in name, the Server Monitor can't detect it. So, make sure that the name is correct. For example, the Monitor name for the HTTP server task is "HTTP Web Server."
Task_description	A description of the server task. Domino Administrator displays this description in the dialog boxes when you start the task. For example, the HTTP Web Server description says "Enables the Domino server to act as a Web server so browser clients can access databases on the server."