Chapter 2   Job Plug-in Modules


iPlanet Certificate Management System (CMS) includes a component called Job Scheduler that can execute specific jobs at specified times. The job scheduler functions similar to a traditional Unix cron daemon in that it takes registered cron jobs and executes them at a preconfigured date and time. If configured, the scheduler checks at specified intervals for jobs waiting to be executed; if the specified execution time has arrived, the scheduler initiates the job automatically. 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 updates of related directories.

This chapter describes the job plug-in modules that are provided with Certificate Management System and explains how to schedule times for jobs.

The chapter has the following sections:

• Overview of Job Plug-in Modules

• RenewalNotificationJob Plug-in Module

• RequestInQJob Plug-in Module

• UnpublishExpiredJob Plug-in Module

• Customizing Notification Messages

Overview of Job Plug-in Modules

---

Both the Certificate Manager and Registration Manager provide a set of job plug-in modules that can be employed by the server to automate certain activities. The Job Plugin Registration tab of the CMS window (see Figure 2-1) lists all the modules and the corresponding classes that are currently registered with a Certificate Manager.

Figure 2-1    Default job modules for the Certificate Manager

Table 2-1 lists these modules.

Table 2-1    Schedulable job plug-in modules for Certificate Manager and Registration Manager  

Plug-in module name	Description
RenewalNotificationJob	A schedulable job that notifies end entities by email that their certificates are about to expire and must be renewed, and optionally sends a summary of these notices to agents. For more information, see "RenewalNotificationJob Plug-in Module".
RequestInQueueJob	A schedulable job that notifies agents at regular intervals of the current state of the request queue. In addition, agents can also be notified by email that a request has been added to the request queue by configuring an event-driven notification. See "RequestInQJob Plug-in Module".
UnpublishExpiredJob	A schedulable job that updates the configured publishing directory periodically by removing expired certificates, and sends a summary of removed certificates to agents or administrators. For more information, see "UnpublishExpiredJob Plug-in Module".

Jobs are implemented as Java classes, which are then registered with Certificate Management System as plug-in modules. You can use a given implementation of a job module and configure multiple instances of it. Each instance must have a unique name (an alphanumeric string with no spaces) and can contain different input parameter values to apply to different jobs.

Note that the name of the Java class for a job plug-in module is in this format:

com.netscape.certsrv.jobs.<plugin_name>

where <plugin_name> is the name of a plug-in module. For example, the Java class for the RenewalNotificationJob module would be:

com.netscape.certsrv.jobs.RenewalNotificationJob

RenewalNotificationJob Plug-in Module

---

When a certificate is about to expire, the owner of the certificate needs to renew it. Using the Jobs Scheduler, you can configure a Certificate Manager or Registration Manager to automatically send email-based renewal notices to users whose certificates are about to expire or have expired. You can also configure these subsystems to send one or more administrators or issuing agents a summary of users who have received these reminders.

The RenewalNotificationJob plug-in module is a schedulable job. When an instance of the job is enabled, it checks for certificates that are about to expire in the internal database. When it finds one, it automatically emails the certificate's owner and continues sending email reminders for a configured period of time, or until the certificate is renewed. The job also collects a summary of all such renewal notifications and mails the summary to one or more agents or administrators.

The job determines the email address to which to send the notification using an email resolver, which you can customize. By default, the email address is found in the certificate itself or in the certificate's associated enrollment request.

The email notification message, as well as the summary message, are constructed using a template found in the configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails

You can configure both the path and filenames of the template files for each job and modify the templates to customize the contents and appearance of the messages. Messages can be sent as HTML or plain text. For customization information, see "Customizing Notification Messages".

For each instance of the RenewalNotificationJob class, you can configure the following:

• The schedule of times when the job will be run; see "Schedule for Executing Jobs".

• How long before expiration the first notification will be sent.

• How long, after the certificate expires, notifications will continue to be sent if the certificate is not renewed.

• The sender of the notification messages (who will be notified of any delivery problems).

• The file location of the notification email template.

• The subject line of the notification message.

• How the email address for the notification is to be resolved.

• Whether a summary will be compiled and sent.

If a summary is to be sent, you can configure the following:

• The recipients of the summary message. These can be, for example, agents who need to know the status of user certificates.

• The sender of the summary message (who will be notified of any delivery problems).

• The file location of the summary message template.

• The file location of content and format of each item to be collected for the summary.

• The subject line of the summary message.

Configuration Parameters of RenewalNotificationJob

In the CMS configuration file, the RenewalNotificationJob module is identified as jobsScheduler.impl.RenewalNotificationJob.class=com.netscape.
certsrv.jobs.RenewalNotificationJob.

In the CMS window, the module is identified as RenewalNotificationJob. Figure 2-2 shows how the configurable parameters pertaining to the plug-in module are displayed in the CMS window.

Figure 2-2    Parameters defined in the RenewalNotificationJob module

Table 2-2 gives details about each of these parameters.

Table 2-2    Description of parameters defined in the RenewalNotificationJob module  

Parameter	Description
enabled	Specifies whether the job is enabled or disabled. Check the box to enable the job. Uncheck the box to disable the job. If you enable the job and set the remaining parameters correctly, the server runs the job at scheduled intervals.
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. Permissible values: Must follow the convention specified in "Schedule for Executing Jobs" Example: 03**1-5
notifyTriggerOffset	Specifies how long (in days) before certificate expiration the first notification will be sent. Permissible values: As applicable. Example: 30
notifyEndOffset	Specifies how long (in days) after the certificate expire notifications will continue to be sent, if the certificate is not renewed. Permissible values: As applicable. Example: 30
senderEmail	Specifies the sender of the notification messages (who will be notified of any delivery problems). Permissible values: The complete email address. Example: CertCentral@siroe.com
emailSubject	Specifies the subject line of the notification message. Permissible values: An alphanumeric string of up to 255 characters. Example: Certificate Renewal Notification
emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the message content. Permissible values: Template file path, including the file name. Example: C:/Netscape/Server4/cert-testCA/emails/renewJob.txt
summary.enabled	Specifies whether a summary report of renewal notifications should be compiled and sent. Check the box if you want the server to compose and send a summary report. Uncheck the box if you don't want the server to compose and send a summary report. If you check the box, be sure to set the remaining parameters; these are required by the server to send the summary report.
summary. recipientEmail	Specifies the recipients of the summary message. These can be, for example, agents who need to know the status of user certificates. Permissible values: Full email addresses, separated by commas. Example: ca_agent1@siroe.com,ca_agent2@siroe.com
summary.senderEmail	Specifies the sender of the summary message (who will be notified of any delivery problems). Permissible values: The full email address. Example: CAadmin@siroe.com
summary. emailSubject	Specifies the subject line of the summary message. Permissible values: An alphanumeric string of up to 255 characters. Example: Certificate Renewal Notification Summary
summary. itemTemplate	Specifies 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 details, see "Customizing Notification Messages". Permissible values: The template file path, including the file name. Example: C:/Netscape/Server4/cert-testCA/emails/ renewJobItem.txt
summary. emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For details, see "Customizing Notification Messages". Permissible values: The template file path, including the file name. Example: C:/Netscape/Server4/cert-testCA/emails/ renewJobSummary.txt

RequestInQJob Plug-in Module

---

In addition to or instead of notifying agents of new requests, you might want to schedule a job that regularly notifies them of the status of the request queue. Such a job can check at a configured interval whether there are any deferred enrollment requests waiting for review. It can then send an email message to agents informing them of the number of requests waiting in the request queue for which they are responsible.

The RequestInQJob plug-in module is a schedulable job. When an instance of the job is enabled, it gets activated at the configured interval and checks the status of the request queue. If any deferred enrollment requests are waiting in the queue, the job constructs an email message summarizing its findings and sends it to the specified agents.

The job constructs the summary message by using a template located in a configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails

You can configure the path and filename of the template file for each job and modify the templates to customize the contents and appearance of the messages. Messages can be sent as HTML or plain text.

For each instance of the RequestInQJob class, you can configure the following:

• The subsystem, Certificate Manager or Registration Manager, that should use this job.

• The schedule of times when the job will be run; see "Schedule for Executing Jobs".

• The sender of the notification messages (who will be notified of any delivery problems).

• The file location of the notification email template.

• The subject line of the notification message.

• The email addresses of message recipients; these should be subsystem agents whose task it is to review manual enrollment requests.

Configuration Parameters of RequestInQJob

In the CMS configuration file, the RequestInQJob module is identified as
jobsScheduler.impl.RequestInQJob.class=com.netscape.certsrv.
jobs.RequestInQJob.

In the CMS window, the module is identified as RequestInQJob. Figure 2-3 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 2-3    Parameters defined in the RequestInQJob module

Table 2-3 gives details for each of these parameters.

Table 2-3    Description of parameters defined in the RequestInQJob module  

Parameter	Description
enabled	Specifies whether the job is enabled or disabled. Check the box to enable the job. Uncheck the box to disable the job. If you enable the job and set the remaining parameters correctly, the server runs the job at scheduled intervals.
cron	Specifies the cron specification for when this job should be run. This is the time at which the Job Scheduler daemon thread checks the queue for pending requests. Permissible values: Must follow the convention specified in "Schedule for Executing Jobs" Example: 00**0
subsystemid	Specifies the subsystem that this job is for. Permissible values: ca or ra. ca specifies that the job is for the Certificate Manager. ra specifies that the job is for the Registration Manager. Example: ca
summary.enabled	Specifies whether a summary of the job accomplished should be compiled and sent. Check the box if you want the server to compose and send a summary report. Uncheck the box if you don't want the server to compose and send a summary report. If you check the box, be sure to set the remaining parameters; these are required by the server to send the summary report.
summary. emailSubject	Specifies the subject line of the summary message. Permissible values: An alphanumeric string of up to 255 characters. Example: Summary Report of Requests in the Agent Queue
summary. emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For details, see "Customizing Notification Messages". Permissible values: The template file path, including the file name. Example: C:/Netscape/Server4/cert-testCA/emails/ reqInQJobSummary.txt
summary.senderEmail	Specifies the sender of the notification message (who should be notified of any delivery problems). Permissible values: The full email address. Example: CAadmin@siroe.com
summary. recipientEmail	Specifies the recipients of the summary message. These should be, for example, agents who need to process pending requests. Permissible values: Full email addresses, separated by commas. Example: ca_agent1@siroe.com,ca_agent2@siroe.com

UnpublishExpiredJob Plug-in Module

---

Certificate Management System doesn't automatically remove expired certificates from the publishing directory. If you configure a Certificate Manager or Registration Manager to publish certificates to an LDAP directory, over time the directory will contain expired certificates. To help you remove expired certificates from the directory, both the Certificate Manager and Registration Manager come with a plug-in module that allows you to create a schedulable job that periodically removes (or unpublishes) certificates that have expired. When the directory has been updated, the job can collect a summary report of the certificates that have been removed and send it to people who need to have this information. Typically, you would want to send this notification to certificate issuing agents or the administrator of the publishing directory.

Th UnpublishExpiredJob plug-in module is a schedulable job. When an instance of the job is enabled, it gets activated at the configured interval and checks for certificates that have expired and are still marked as published in the internal database. The job connects to the publishing directory and deletes these certificates; it then marks these certificates as unpublished in the internal database. The job also collects a summary of expired certificates that it deleted and mails the summary to one or more agents or administrators as specified by the configuration.

The job constructs the summary message by using a template located in a configured directory. This directory has the following default location: <server_root>/cert-<instance_id>/emails

You can configure the path and filename of the template file for each job. You can also modify the templates to customize the contents and appearance of the messages; see "Customizing Message Templates".

Messages can be sent as HTML or plain text.

For each instance of the UnpublishExpiredJob class, you can configure the following:

• The schedule of times when the job will be run; see "Schedule for Executing Jobs".

• Whether a summary will be compiled and sent.

If a summary is to be sent, you can configure the following:

• The recipients of the summary message. These can be, for example, administrators who are responsible for the publishing directory.

• The sender of the summary message (who will be notified of any delivery problems).

• The file location a of the summary message template.

• The file location of content and format of each item to be collected for the summary.

• The subject line of the summary message.

Note that the job automates removal of expired certificates from the directory. You can also remove expired certificates manually following the instructions outlined in section "Manually Updating Certificates and CRLs in a Directory" in Chapter 19, "Setting Up LDAP Publishing" of CMS Installation and Setup Guide.

Configuration Parameters of UnpublishExpiredJob

In the CMS configuration file, the UnpublishExpiredJob module is identified as
jobsScheduler.impl.ExpiredUnpublishJob.class=com.netscape.
certsrv.jobs.UnpublishExpiredJob.

In the CMS window, the module is identified as UnpublishExpiredJob. Figure 2-4 shows how the configurable parameters for the module are displayed in the CMS window.

Figure 2-4    Parameters defined in the UnpublishExpiredJob module

Table 2-4 gives details for each of these parameters.

Table 2-4    Description of parameters defined in the UnpublishExpiredJob module  

Parameter	Description
enabled	Specifies whether the job is enabled or disabled. Check the box to enable the job. Uncheck the box to disable the job. If you enable the job and set the remaining parameters correctly, the server runs the job at scheduled intervals.
cron	Specifies the cron specification for when this job should be run. This is the time at which the Job Scheduler daemon thread checks the certificates for removing expired certificates from the publishing directory. Permissible values: Must follow the convention specified in "Schedule for Executing Jobs" Example: 00**6
summary.enabled	Specifies whether a summary of the certificates removed by the job should be compiled and sent. Check the box if you want the server to compose and send a summary report. Uncheck the box if you don't want the server to compose and send a summary report. If you check the box, be sure to set the remaining parameters; these are required by the server to send the summary report.
summary. emailSubject	Specifies the subject line of the summary message. Permissible values: An alphanumeric string of up to 255 characters. Example: Expired Certificate Removal Job Summary
summary. emailTemplate	Specifies the path, including the filename, to the directory that contains the template to be used for formulating the summary report. For details, see "Customizing Notification Messages". Permissible values: The template file path, including the file name. Example: C:/Netscape/Server4/cert-testCA/emails/ unpublishCertsJobSummary.html
summary. itemTemplate	Specifies 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 above). Permissible values: The template file path, including the file name. Example: C:/Netscape/Server4/cert-testCA/emails/ unpublishCertsJobItem.txt
summary.senderEmail	Specifies the sender of the summary message (who should be notified of any delivery problems). Permissible values: The full email address. Example: CAadmin@siroe.com
summary. recipientEmail	Specifies the recipients of the summary message. These can be, for example, agents who need to know the status of user certificates. Permissible values: Complete email addresses, separated by commas. Example: cert_agent1@siroe.com,cert_agent2@siroe.com

Schedule for Executing Jobs

The Job Scheduler uses a variation of the Unix crontab entry format to specify dates and times for checking the job queue and executing jobs. As shown in Table 2-5, the time entry format consists of five fields (the sixth field specified for the Unix crontab is not used by the Job Scheduler). Values are separated by spaces or tabs.

Table 2-5    Time format for scheduling jobs  

Field	Value
Minute	0-59
Hour	0-23
Day of month	1-31
Month of year	1-12
Day of week	0-6 (where 0=Sunday)

Each field can contain either a single integer or a pair of integers separated by a hyphen or dash (-) to indicate an inclusive range. To specify all legal values, a field can contain an asterisk rather than an integer. Day fields can contain a comma-separated list of values.

For example, the following time entry specifies every hour at 15 minutes (1:15, 2:15, 3:15 and so on):

15 * * * *

The following example specifies a job execution time of noon on April 12:

0 12 12 4 *

The day-of-month and day-of-week fields can contain a comma-separated list of values to specify more than one day. If both day fields are specified, the specification is inclusive; that is, the day of the month is not required to fall on the day of the week to be valid. For example, the following entry specifies a job execution time of midnight on the first and fifteenth of every month, and on every Monday:

0 0 1,15 * 1

To specify one day type without the other, use an asterisk in the other day field. For example, the following entry specifies a job execution time of 3:15 a.m. on every weekday morning:

15 3 * * 1-5

Customizing Notification Messages

---

Summary email messages are constructed using templates located in the emails directory of a CMS instance. This directory has the following default location: <server_root>/cert-<instance_id>/emails

Both text an HTML templates are included by default. They are listed in Table 2-6.

Templates for Summary Notifications

Table 2-6 lists the default template files for formulating the notification messages that summarize jobs that were executed by the Job Scheduler component of a Certificate Manager or Registration Manager. You can change the name of these files as applicable; be sure to make the appropriate changes to the configuration.

For summaries, a separate template is used to format the entry for each item in the summary. The item entries are then added to a table in the summary message.

Tokens, which you can use as variables in the body of the message, are defined for each templates enabling you to customize the message; the token is replaced by its current variable value in the constructed message. For details, see "Customizing Message Templates".

Table 2-6    Default templates for summary notifications  

Filename	Description
Templates for UnpublishExpiredJob module
ExpiredUnpublishJob	Template for formulating the summary report or table that summarizes removal of expired certificates from the directory.
ExpiredUnpublishJobItem	Template for formatting the items to be included in the summary table, which is constructed using the ExpiredUnpublishJob template.
Templates for RequestInQueueJob module
riq1Item.html	Template for formatting the items to be included in the summary table, which is constructed using the riq1Summary.html template.
riq1Summary.html	Template for formulating the summary report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager or Registration Manager.
Templates for RenewalNotificationJob module
rnJob1.txt	Template for formulating the message content to be sent to end entities to inform them that their certificates are about to expire and that they should renew their certificates before expiration.
rnJob1Item.txt	Template for formatting the items to be included in the summary report, which is constructed using the rnJob1Summary.txt template.
rnJob1Summary.txt	Template for formulating the summary report to be sent to agents and administrators.

Note that in the CMS configuration, template files for schedulable jobs are identified as follows:

jobsScheduler.job.<job_name>.summary.emailTemplate=
<template_file_path>

jobsScheduler.job.<job_name>.summary.itemTemplate=
<template_file_path>

<job_name> specifies the job instance name.

<template_file_path> specifies the path, including the filename, to the directory that contains the template to be used for formulating the message content.

Customizing Message Templates

You can modify the templates to customize the contents and appearance of messages. The message body can contain HTML or plain text. In the body of the message, you can use tokens or keywords as variables. A token is indicated by the dollar character ($) and is replaced by its current variable value in the constructed message. Different tokens are available for each job or notification class. These are listed in "Tokens Available in Message Templates".

For example, a certificate-issuance-notification message can make use of tokens as follows:

------------------------------------
CERTIFICATE RENEWAL NOTIFICATION
------------------------------------

Your certificate will expire soon:

Serial Number= $SerialNumber
SubjectDN= $SubjectDN
IssuerDN= $IssuerDN
Validity Period= $NotBefore - $NotAfter

To renew your certificate, please follow this URL:

https://$HttpHost:$HttpPort

If you have any questions or problems, please send an email to cert_central@siroe.com.

Thank you.

Tokens Available in Message Templates

This section explains the tokens provided in the templates used by the default job plug-in and event-triggered notification modules to formulate notification messages.

• Tokens for Renewal Notification Messages

• Tokens for Request In Queue Notification Messages

• Tokens for Directory Update Notification Messages

Tokens for Renewal Notification Messages

This section lists the tokens that are available in the message templates for instances of the RenewalNotificationJob class or plug-in module.

Table 2-7 lists the tokens that you can use for formulating this job's summary report. You can customize the content and format of the items in the report by using the tokens defined in Table 2-8.

Table 2-7    Tokens for the renewal-notification job's summary report  

Token	Description
$ExecutionTime	Specifies the time the job (instance) was run.
$InstanceID	Specifies the name of the job instance.
$SummaryItemList	Specifies the list of items in the summary notification. Each item corresponds to a certificate the job detects for renewal.
$SummaryTotalfailure	Specifies the total number of items in the summary report that failed.
$SummaryTotalNum	Specifies the total number of items (certificates that require to be renewed) in the summary report.
$SummaryTotalSuccess	Specifies how many of the total number of items in the summary report succeeded.

Table 2-8 lists the tokens for the inner list items.

Table 2-8    Tokens for items in renewal-notification job's summary report  

Token	Description
$CertType	Specifies the type of certificate—whether SSL client (client), SSL server (server), Registration Manager's signing certificate (ra), Certificate Manager's CA signing certificate (ca), router certificate (Cisco-router), or other (other).
$HttpHost	Specifies the fully qualified host name of the Certificate Manager or Registration Manager to which end entities should connect to renew their certificates. (The token enables you to construct the URL which end entities use to renew their certificates; see the example in "Customizing Message Templates".)
$HttpPort	Specifies the port number at which the Certificate Manager or Registration Manager is listening to certificate-renewal requests from end entities. (The token enables you to construct the URL which end entities use to renew their certificates; see the example in "Customizing Message Templates".)
$IssuerDN	Specifies the distinguished name of the certificate issuer.
$NotAfter	Specifies the NotAfter attribute.
$NotBefore	Specifies the NotBefore attribute.
$RequestorEmail	Specifies the requestor's email address.
$RequestType	Specifies the request type—whether it is a certificate enrollment, certificate renewal, certificate revocation, key archival, or key recovery request.
$SerialNumber	Specifies the serial number of the certificate; the serial number will be displayed as a hexadecimal value in the resulting message.
$Status	Specifies whether the operation failed or succeeded.
$SubjectDN	Specifies the distinguished name of the certificate subject.

Tokens for Request In Queue Notification Messages

Table 2-9 lists the tokens that you can use for formulating the content of the RequestInQueueJob job's summary report.

Table 2-9    Tokens for the request-in-queue job's summary report  

Token	Description
$InstanceID	Specifies the ID assigned to the subsystem that sent this notification. If the notification is sent by a Certificate Manager, this will be ca. If the notification is sent by a Registration Manager, this will be ra.
$ExecutionTime	Specifies the time the job (instance) was run.
$RecipientEmail	Specifies the email address of the recipient.
$SenderEmail	Specifies the email address of the sender.
$SummaryTotalNum	Specifies the total number of items (certificate requests that are pending in the queue) in the summary report.

Tokens for Directory Update Notification Messages

This section lists the tokens that are available in summary message templates for instances of the UnpublishExpiredJob class or plug-in module.

Table 2-10 lists the tokens that are available for this jobs's summary report. You can customize the content and format of the items in the report by using the tokens defined in Table 2-11.

Table 2-10    Tokens for the unpublish-expired job's summary report  

Token	Description
$InstanceID	Specifies the name of the job instance that generated this summary report.
$ExecutionTime	Specifies the time the job (instance) was run.
$SummaryItemList	Specifies the list of items in the summary notification. Each item corresponds to a certificate the job detects for removal from the publishing directory.
$SummaryTotalfailure	Specifies the total number of items in the summary report that failed.
$SummaryTotalNum	Specifies the total number of items (certificates to be removed from the directory) in the summary report.
$SummaryTotalSuccess	Specifies how many of the total number of items in the summary report succeeded.

Table 2-11 lists the tokens for the inner list items.

Table 2-11    Tokens for items in the unpublish-expired job's summary report  

Token	Description
$CertType	Specifies the type of certificate—whether SSL client (client), SSL server (server), Registration Manager's signing certificate (ra), Certificate Manager's CA signing certificate (ca), router certificate (Cisco-router), or other (other).
$IssuerDN	Specifies the distinguished name of the certificate issuer.
$NotAfter	Specifies the NotAfter attribute.
$NotBefore	Specifies the NotBefore attribute.
$RequestorEmail	Specifies the requestor's email address.
$SerialNumber	Specifies the serial number of the certificate; the serial number will be displayed as a hexadecimal value in the resulting message.
$Status	Specifies whether the operation failed or succeeded.
$SubjectDN	Specifies the distinguished name of the certificate subject.