Chapter 14 Introduction to Job Scheduling and Notifications

Netscape 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.

• Overview of Job Plug-in Modules
• Event-Driven Notifications
• Customizing Notification Messages

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 java class that implements the job for scheduling renewal notifications is identified as follows:

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

• 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.

• 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.

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 java class that implements the job for request-queue-status notifications is identified as follows:

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

• 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.

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.

The java class that implements the job for scheduling removal of expired certificates from the directory is identified as follows:

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

• The schedule of times when the job will be run; see "Schedule for Executing Jobs".
• Whether a summary will be compiled and sent.

• 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.

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 14.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.

• Notifications of Certificate Issuance to End Entities

End entities are notified by email that a requested certificate has been issued. This is an event-driven notification.

• Notification of New Request in Queue

Agents are notified by email that a request has been added to the request queue. Alternatively (or in addition) a schedulable job can notify agents at regular intervals of the current state of the request queue; see "Notification of Request Queue Status".

You can configure the Certificate Manager or Registration Manager to send a notification message to users who have been issued certificates in response to enrollment requests. This message normally includes information about the issued certificate and instructions for importing the certificate into the user's client.

• The email resolver first checks the request for the email address and if doesn't find one, it checks the subject name of the certificate for the email address; if the subject name doesn't include the email address, the resolver checks the certificate for the Subject Alternative Name extension to see whether it specifies the email address. For specifying an email address in the Subject Alternative Name extension, see "Subject Alternative Name Extension Policy".
• In the absence of an email address, the notification is sent to the email address specified in the "Sender's Email Address" field, instead of the requestor, as an undeliverable notification. There'll also be a message to this effect in the logs; see "Monitoring Logs".

• Whether the listener is enabled.
• The sender of the notification messages (who will be notified of any delivery problems).
• The location of the notification email template.
• The subject line of the notification message.

To configure a Certificate Manager or Registration Manager to send certificate-issuance notifications to end entities:

1. Access the CMS window (see "Logging In to the CMS Window").
2. Click the Configuration tab.
3. In the navigation tree, select the subsystem, then click Notification. (The figure below shows the Certificate Manager's notification feature; the Registration Manager also has a similar feature.)

The Certificate Issued tab appears.



4. To enable the notification feature, check the "Enable Certificate Issued notification" option.
5. In the Email Information Settings section, enter information as appropriate:

Sender's E-mail Address. Type the sender's full email address (this is the person who should be notified of any delivery problems).

Subject. Type the subject title for the notification.

Content template path. Type the path, including the filename, to the directory that contains the template to be used for formulating the message content.

6. 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.

When a deferred end-entity request enters the request queue of a Certificate Manager or Registration Manager, agents assigned to manage the queue must review the request and reject or accept it. To help ensure that an agent processes the request in a timely manner, you can configure the subsystem to notify agents whenever a new request gets added to the request queue.

• Whether the listener is enabled.
• The sender of the notification messages (who will be notified of any delivery problems).
• The 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 is to review deferred enrollment requests.

To configure a Certificate Manager or Registration Manager to send email notifications to its agents:

1. Access the CMS window (see "Logging In to the CMS Window").
2. Click the Configuration tab.
3. In the navigation tree, select the subsystem, and then click Notification. (The figure below shows the Certificate Manager's notification feature; the Registration Manager also has a similar feature.)
4. In the right pane, click Request In Queue.

   

5. To enable the notification feature, check the "Enable Request In Queue notification" option.
6. Enter information as appropriate:

Sender's E-Mail Address. Type the sender's full email address (this is the person who should be notified of any delivery problems).

Subject. Type the subject title for the notification--for example, "End Entity Request in Queue."

Recipient's E-Mail Address. Type the recipient's full email address (this is the person who will check the queue). You can specify more than one recipient; separate email addresses by commas.

Content template path. Type the path, including the filename, to the directory that contains the template to be used for formulating the message content.

7. 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.

Table 14.6 lists the default template files provided for formulating event-triggered-notification messages. You can customize certain aspects of these templates--such as the subject of the email message and the location and name of the template file--using the CMS window.

<subsystem> specifies the prefix that identifies the subsystem to which the configuration parameter belongs--ca for the Certificate Manager and ra for the Registration Manager.

<notification_name> specifies the name of the event-triggered notification--certIssued for the certificate issuance notifications to end entities and requestInQ for the request in queue notifications to agents.

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

Table 14.7 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.

<job_name> specifies the job instance name. For a list of job instances created by default, see Table 15.1.

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

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".

Your certificate request ($RequestId) has been processed successfully. Details of your certificate are as follows:

Serial Number= $SerialNumber

SubjectDN= $SubjectDN

IssuerDN= $IssuerDN

Validity Period= $NotBefore - $NotAfter

To get your certificate, please follow this URL:

https://$HttpHost:$HttpPort/getCertFromRequest?requestId=$RequestId

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

Thank you.

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 Certificate Issuance Notifications to End Entities
• Tokens for Rejection Notifications to End Entities
• Tokens for Renewal Notification Messages
• Tokens for Request In Queue Notification Messages
• Tokens for Directory Update Notification Messages

Table 14.8 lists the tokens that are available in the message templates provided for formulating the content of email notifications to end entities; a Certificate Manager or Registration Manager can send these notifications upon issuance of the certificates they requested.

Table 14.9 lists tokens that are available in the message templates provided for formulating the content of email notifications to end entities; a Certificate Manager or Registration Manager can send these notifications to end entities when rejecting certificate requests.

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

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

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