Chapter 17   Scheduling Automated Jobs


iPlanet Certificate Management Server (CMS) provides a customizable Job Scheduler component that supports various mechanisms for scheduling cron jobs. This chapter explains how to configure Certificate Management System to use specific job plug-in modules for accomplishing jobs. The chapter also shows how plug-in implementations and configured instances for various job items appear in the configuration file.

The chapter has the following sections:

• Configuring a Subsystem to Run Automated Jobs

• Managing Job Plug-in Modules

Configuring a Subsystem to Run Automated Jobs

---

You can configure the Certificate Manager and Registration Manager to run automated jobs, that is execute specific jobs at specified times. The steps are as follows:

• Step 1. Before You Begin

• Step 2. Modify Existing Jobs

• Step 3. Delete Unwanted Jobs

• Step 4. Add New Jobs

• Step 5. Schedule the Frequency

• Step 6. Verify Mail Server Settings

• Step 7. Test Your Configuration

For information on adding or changing job-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.

Step 1. Before You Begin

Before configuring a Certificate Manager or Registration Manager to run jobs, be sure to do the following:

• Read Chapter 2 , "Job Plug-in Modules" of CMS Plug-Ins Guide, and determine the jobs you want the server to run.

  Jobs that you might want to schedule include email notifications of timed events (such as the expiration of a certificate) that require action on the part of users, and periodic activities such as removing expired certificates from the publishing directory.

• Each job uses templates for formulating the notification-message and summary-message contents. Be sure to read the "Customizing Notification Massages" section to get familiar with the templates the server uses for formulating notification messages. If you want to customize them, do that before you start configuring a job plug-in; check the list of tokens to see if they're useful for customizing your message body.

Step 2. Modify Existing Jobs

Modifying a job involves changing the configuration parameter values of the job instance; you cannot change the name of a job. To change the name of a job, create a new job using the same job plug-in module (that you used to create the job you want to rename) with the same parameter values, and delete the old one.

As a part of modifying a job, you can change its status from enabled to disabled or vice versa by checking or unchecking the enable parameter. A subsystem executes only those jobs that are enabled.

During installation, the Certificate Manager and Registration Manager automatically create a set of jobs (that you would most likely want to use) using the job plug-in modules registered by default. Figure 17-1 shows the jobs created for a Certificate Manager. The Registration Manager also has a similar list. Table 17-1 summarizes the default jobs created for both Certificate Manager and Registration Manager.

After installation, you must verify whether you want to use these jobs, check how these jobs are configured, and make the appropriate configuration changes. If you don't want to use a job, delete it from the configuration following the instructions in Step 3. Delete Unwanted Jobs; alternatively, you may keep it in the disabled state. If you want to create a new job, follow the instructions in Step 4. Add New Jobs.

Figure 17-1    Default jobs created for a Certificate Manager

Table 17-1    Default jobs created for a Certificate Manager and Registration Manager  

Job name	Certificate Manager	Registration Manager
certRenewalNotifier	Yes	Yes
requestInQueueNotifier	Yes	Yes
unpublishExpiredCerts	Yes	No

To modify a configured job in the CMS configuration:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select Job Scheduler, then select Jobs.

   The Job Instance tab appears (Figure 17-1) showing the default jobs.

4. In the Instance Name list, select a job that you want to modify.

   For the purposes of this instruction, assume that you selected the job named unpublishExpiredCerts.

5. Click Edit/View.

   The Job Instance Editor window appears, showing how this job is currently configured. An example is shown below.
   
   

6. Make the necessary changes and click OK.

7. Repeat steps 4 through 6 for the remaining jobs.

8. Click Refresh.

Step 3. Delete Unwanted Jobs

You can delete unwanted jobs from the CMS configuration, by using the CMS window. If you think you might need a job in the future, instead of deleting it from the configuration you should disable it by setting the enable parameter value to false. In this way, you can avoid re-creating the job in the future. Because Certificate Management System executes only those jobs that are currently enabled, keeping unwanted jobs in a disabled state in the configuration does not affect the server's functioning.

To delete a job from the CMS configuration:

1. In the Job Instance tab, select the job you want to delete and click Delete.

2. When prompted, confirm the delete action.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. Don't restart the server yet; you can do so after you've made all the required changes.

Step 4. Add New Jobs

Typically, you don't need to create a new job because jobs for all the default plug-ins are created for you during installation. However, in certain circumstances, for example, if you deleted a default instance, you might have to create a new job.

Adding a job to the CMS configuration involves creating a new instance of an already registered plug-in module, assigning a unique name (an alphanumeric string with no spaces) for the instance, and entering appropriate values for the parameters that define the plug-in module you want to create an instance of. When you add a job, the CMS configuration is updated with the appropriate information.

When naming a job, be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-); other characters and spaces are not allowed. For example, you can type My_Job or MyJob as the instance name, but not My Job.

Figure 17-2 shows the job modules registered with a Certificate Manager. The Registration Manager also has a similar list. Table 17-2 summarizes the default modules registered with both Certificate Manager and Registration Manager. If you have registered any custom job modules (see Registering a Job Module), they too will be available for selection.

Figure 17-2    Default job modules registered with a Certificate Manager

Table 17-2    Job modules registered with a Certificate Manager and Registration Manager  

Job plug-in module name	Provided with Certificate Manager	Provided with Registration Manager
RenewalNotificationJob	Yes	Yes
RequestInQueueJob	Yes	Yes
UnpublishExpiredJob	Yes	No

To add a job to the CMS configuration:

1. In the Job Instance tab, click Add.

   The Select Job Plugin Implementation window appears.
   
   

2. Select a module.

   For the purposes of this instruction, assume that you selected the RenewalNotificationJob module.

3. Click Next.

   The Configure Job Instance Parameters window appears. It lists the configuration information required for this job.
   
   

4. Enter the appropriate information.

   Job Instance ID. Type a unique name that will help you identify the job. Be sure to formulate the name using any combination of letters (aA to zZ), digits (0 to 9), an underscore (_), and a hyphen (-). For example, you can type My_Job or MyJob as the instance name, but not My Job.

   enabled. To enable the job, type true; to disable the job, type false.

   cron. Specifies the cron specification for when this job should be run. In other words, it specifies the time at which the Job Scheduler daemon thread should check the certificates for sending renewal notifications. For example, 03**1-5.

   notifyTriggerOffset. Type the number of days before certificate expiration the first notification should be sent. For example, if you want the server to send renewal notifications to users 30 days before their certificates expire, type 30.

   notifyEndOffset. Type the number of days after the certificate expire notifications will continue to be sent, if the certificate is not renewed. For example, if you want the server to continue sending renewal notifications to users (if they don't renew their certificates) 30 days after their certificates expire, type 30.

   senderEmail. Type the complete email address to which the server should send notifications regarding any delivery problems. For example, CertCentral@siroe.com.

   emailSubject. Type the subject line of the notification message; the subject line must be an alphanumeric string of up to 255 characters. For example, Certificate Renewal Notification.

   emailTemplate. Type the path, including the filename, to the directory that contains the template to be used for formulating the message content. For example: C:/iplanet/servers/cert-testCA/emails/renewJob.txt.

   summary.enabled. Type true if you want the server to compile a summary report of renewal notifications and send. Type false if you don't want the server to compile a summary report of renewal notifications.

   summary.recipientEmail. Type the email addresses of recipients of the summary report; when specifying multiple recipients, separate addresses by commas. These can be, for example, agents who need to know the status of user certificates. For example, ca_agent1@siroe.com, ca_agent2@siroe.com.

   summary.senderEmail. Type the full email address of the sender (of the summary message); in case of a delivery problem, the server will send a notification to this address. For example, CAadmin@siroe.com.

   summary.emailSubject. Type the subject line of the summary message; the subject line must be an alphanumeric string of up to 255 characters. For example, Certificate Renewal Notification Summary.

   summary.itemTemplate. Type the path, including the filename, to the directory that contains the template to be used for formulating the content and format of each item to be collected for the summary report (see the summary.emailTemplate parameter below). For example, C:/iplanet/servers/cert-testCA/emails/renewJobItem.txt.

   summary.emailTemplate. Type the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For example, C:/iplanet/servers/cert-testCA/emails/
   renewJobSummary.txt.

5. Click OK.

   You are returned to the Policy Rules Management tab.

6. Repeat steps 1 through 5 and create additional rules, if required.

Step 5. Schedule the Frequency

The Certificate Manager and Registration Manager can execute a job only if the Job Scheduler is turned on (or enabled). As a part of turning the Job Scheduler on, you also specify the frequency at which the Job Scheduler daemon should check if any of the configured jobs need to be executed.

To schedule the interval for executing the job:

1. In the navigation tree, click Job Scheduler.

   The General Settings tab appears. It shows whether the Job Scheduler component is currently enabled or disabled.
   
   

2. Enter information as appropriate:

   Enable Job Scheduler. Check this option to enable the Job Scheduler. To disable the Job Scheduler uncheck the option; disabling turns off all the jobs.

   Check Frequency. Type the frequency at which the Job Scheduler daemon thread should wake up and call the configured jobs that meet the cron specification. By default, it is set to one minute.

3. To save your changes, click Save.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.

Step 6. Verify Mail Server Settings

The Certificate Manager and Registration Manager use the mail server specified in the SMTP tab (of the CMS window) for routing or sending email notifications automatically. If you've already set it up, you should verify that the host name and port number of the mail server are accurate. Otherwise, follow the procedure below to specify the mail server details.

To identify the mail server that the Certificate Manager or Registration Manager should use for routing email notifications:

1. In the CMS window, select the Configuration tab, and then in the right pane, select the SMTP tab.
   
   

2. Identify the mail server by providing the following details:

   Server name. Make sure the field shows the correct host name for your mail server. Otherwise, type the full host name of the machine on which your mail server is installed. Certificate Management System uses this name to access the mail server. The format for the host name is as follows:

   <machine_name>.<your_domain>.<domain>

   By default, the host name of the mail server is shown as localhost instead of the actual host name (for example, mail.siroe.com).

   Port number. Make sure that the field shows the correct port number at which the mail server is listening for requests. Otherwise type the port number.

3. To save your changes, click Save.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.

Step 7. Test Your Configuration

• Change the email addresses in the notification configuration to your email address.

• Go to the end-entity interface and request a certificate using the manual enrollment form. When the request gets queued for agent approval, you should get notified. Check the message to see if has the correct information. Otherwise, correct the message template.

• Next, login to the agent interface and approve the request. Whren the server issues a certificate, you should get a notification.

Managing Job Plug-in Modules

---

This section explains how to use the CMS window to perform the following operations:

• Registering a Job Module

• Deleting a Job Module

For information on adding or changing job-specific information in the configuration file, see Changing the Configuration by Editing the Configuration File.

Registering a Job Module

You can register custom job plug-in modules from the CMS window. Registering a new module involves specifying the name of the module and the full name of the Java class that implements the module. For example, you can add a job implementation named as follows:

com.iplanet.jobscheduler.unpublishUserCert

Before registering a module, be sure to put the Java class for the module in the classes directory (the implementation must be on the class path).

To register a job module in the CMS framework:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select Job Scheduler, then select Jobs.

   The Job Instance tab appears. It lists any currently configured jobs.

4. Select the Job Plugin Registration tab.

   The Job Plugin Registration tab appears.
   
   

5. Click Register.

   The Register Job Scheduler Plugin Implementation window appears.
   
   

6. Specify information as appropriate:

   Plugin name. Type a name for the plug-in module.

   Class name. Type the full name of the class for this module—that is, the path to the implementing Java class. If this class is part of a package, be sure to include the package name. For example, if you are registering a class named myJob and if this class is in a package named com.myCompany, type com.myCompany.myJob.

7. Click OK.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.

Deleting a Job Module

You can delete unwanted job plug-in modules by using the CMS window. Before deleting a module, be sure to delete all the instances that are based on this module; for instructions, see Step 3. Delete Unwanted Jobs.

To delete a job module from the CMS framework:

1. Log in to the CMS window (see Logging In to the CMS Window).

2. Select the Configuration tab.

3. In the navigation tree, select Job Scheduler, then select Jobs.

   The Job Instance tab appears. It lists any currently configured instances.

4. Select the Job Plugin Registration tab.

   The Job Plugin Registration tab appears. It lists currently registered job modules.

5. In the Plugin Name list, select the module you want to delete and click Delete.

6. When prompted, confirm the delete action.

   The CMS configuration is modified. If the changes you made require you to restart the server, you will be prompted accordingly. In that case, restart the server.