Complete Contents
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling Instances
Chapter 5: Starting and Stopping Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Using the PIN Generator Tool
Chapter 11: Configuring Authentication for End Entities
Chapter 12: Developing Authentication Plug-ins
PART 5: Job Scheduling and Notification
Chapter 13: Introduction to Job Scheduling and Notifications
Chapter 14: Configuring Jobs
PART 6: Policies
Chapter 15: Introduction to Policies
Chapter 16: Configuring Policies
PART 7: LDAP Publishing
Chapter 17: Introduction to LDAP Publishing
Chapter 18: Configuring Subsystems for LDAP Publishing
Chapter 19: Publishing CRLs
PART 8: Agent and End-Entity Interfaces
Chapter 20: Introduction to End-Entity and Agent Interfaces
Chapter 21: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 22: Introduction to Logs
Chapter 23: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 24: Issuing and Managing End-Entity Certificates
Chapter 25: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Previous Next Contents Index Bookshelf


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

You can also configure Certificate Management System to send email notifications automatically to end entities, agents, or administrators when certain events occur. Unlike jobs that are executed on a preconfigured schedule, these notifications are event-driven--that is, whenever an event occurs, the server notifies the user. Notifiable events include certificate issuance and pending requests in an agent queue.

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

 The chapter has the following sections:
Built-in Job Plug-in Modules
Certificate Management System comes with various job plug-in modules that can be employed by the server to automate certain activities. Table 13.1 lists these modules and indicates which subsystems can use them.

Table 13.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 "Certificate Renewal Notifications".

Both the Certificate Manager and Registration Manager provide this 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 "Notification of Request Queue Status".

Both the Certificate Manager and Registration Manager provide this 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 "Directory Update and Notification".

Both the Certificate Manager and Registration Manager provide this plug-in module.

Certificate Renewal Notifications

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.

Plug-in Module for Automated Renewal Notifications

The plug-in module implementation for scheduling renewal notifications is identified as follows:

com.netscape.certsrv.jobs.RenewalNotificationJob

 This plug-in 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>/<instance_id>/emails

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

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:

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

 Configurable Parameters

Figure 13.1 shows how the configurable parameters pertaining to the RenewalNotificationJob plug-in module are displayed in the CMS window.

Figure 13.1 Configurable parameters and values for the RenewalNotificationJob plug- in module

Table 13.2 gives details about each of these parameters.

Table 13.2 Configurable parameters for the renewal notification job and their values

Parameter name
Description
enabled

Specifies whether the job is enabled or disabled. To enable the job, enter true; to disable the job, enter false.

Example: true

Permissible values: Either of the following:

Object type: String

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.

Example: 03**1-5

Permissible values: Must follow the convention specified in "Schedule for Executing Jobs"

Object type: String

notifyTriggerOffset

Specifies how long (in days) before certificate expiration the first notification will be sent.

Example: 30

Permissible values: As applicable

Object type: Integer

notifyEndOffset

Specifies how long (in days) after the certificate expire notifications will continue to be sent, if the certificate is not renewed.

Example: 30

Permissible values: As applicable

Object type: Integer

senderEmail

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

Example: CertCentral@netscape.com

Permissible values: Complete email address

Object type: String

emailSubject

Specifies the subject line of the notification message.

Example: Certificate Renewal Notification

Permissible values: Alphanumeric string of up to 255 characters

Object type: String

emailTemplate

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

Example: C:/Netscape/Server4/cert-testCA/emails/renewJob.txt

Permissible values: Template file path, including the file name

Object type: String

summary.enabled
Specifies whether a summary report of renewal notifications should be compiled and sent:

Example: true

Permissible values: Either of the following:

Object type: String

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

Example: ca_agent1@netscape.com, ca_agent2@netscape.com

Permissible values: Full email addresses, separated by commas

Object type: String

summary.senderEmail
Specifies the sender of the summary message (who will be notified of any delivery problems).

Example: CAadmin@netscape.com

Permissible values: The full email address

Object type: String

summary.emailSubject

Specifies the subject line of the summary message.

Example: Certificate Renewal Notification Summary

Permissible values: Alphanumeric string of up to 255 characters

Object type: String

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

Example: C:/Netscape/Server4/cert-testCA/emails/renewJobItem.txt

Permissible values: Template file path, including the file name

Object type: String

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

Example: C:/Netscape/Server4/cert-testCA/emails/renewJobSummary.txt

Permissible values: Template file path, including the file name

Object type: String

Notification of Request Queue Status

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.

Plug-in Module for Sending Notifications of Request Queue Status

The plug-in module provided out of the box for request-queue-status notifications is identified as follows:

com.netscape.certsrv.jobs.RequestInQJob

 This plug-in 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>/<instance_id>/emails

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

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:

 Configurable Parameters

Figure 13.2 shows how the configurable parameters pertaining to the RequestInQJob plug-in module are displayed in the CMS window.

Figure 13.2 Configurable parameters and values for the RequestInQJob plug-in module

Table 13.4 gives details for each of these parameters.

Table 13.3 Configurable parameters for the request-in-queue notification job and their values

Parameter name
Description
enabled

Specifies whether the job is enabled or disabled. To enable the job, enter true; to disable the job, enter false.

Example: true

Permissible values: Either of the following:

Object type: String

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.

Example: 00**0

Permissible values: Must follow the convention specified in "Schedule for Executing Jobs"

Object type: String

subsystemid

Specifies the subsystem that this job is for.

Example: ca

Permissible values: Either of the following:

Object type: String

summary.enabled

Specifies whether a summary of the job accomplished should be compiled and sent:

Example: true

Permissible values: Either of the following:

Object type: String

summary.emailSubject

Specifies the subject line of the summary message.

Example: Summary Report of Requests in the Agent Queue

Permissible values: Alphanumeric string of up to 255 characters

Object type: String

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

Example: C:/Netscape/Server4/cert-testCA/emails/reqInQJobSummary.txt

Permissible values: Template file path, including the file name

Object type: String

summary.senderEmail

Specifies the sender of the notification message (who should be notified of any delivery problems).

Example: CAadmin@netscape.com

Permissible values: The full email address

Object type: String

summary.recipientEmail

Specifies the recipients of the summary message. These should be, for example, agents who need to process pending requests.

Example: ca_agent1@netscape.com, ca_agent2@netscape.com

Permissible values: Full email addresses, separated by commas

Object type: String

Directory Update and Notification

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.

Note that the job automates removal of expired certificates from the directory. You can also remove expired certificates manually following the instructions in "Manually Updating Certificate Information in the Directory".

Plug-in Module for Removing Expired Certificates from the Directory

The plug-in module implementation for scheduling removal of expired certificates from the directory is identified as follows:

com.netscape.certsrv.jobs.UnpublishExpiredJob

 This plug-in 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>/<instance_id>/emails

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

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:

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

 Configurable Parameters

Figure 13.3 shows how the configurable parameters pertaining to the UnpublishExpiredJob plug-in module are displayed in the CMS window.

Figure 13.3 Configurable parameters and values for the UnpublishExpiredJob plug-in module

Table 13.4 gives details for each of these parameters.

Table 13.4 Configurable parameters for the unpublish expired certificates job and their values

Parameter name
Description
enabled

Specifies whether the job is enabled or disabled. To enable the job, enter true; to disable the job, enter false.

Example: true

Permissible values: Either of the following:

Object type: String

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.

Example: 00**6

Permissible values: Must follow the convention specified in "Schedule for Executing Jobs"

Object type: String

summary.enabled

Specifies whether a summary of the certificates removed by the job should be compiled and sent:

Example: true

Permissible values: Either of the following:

Object type: String

summary.emailSubject

Specifies the subject line of the summary message.

Example: Expired Certificate Removal Job Summary

Permissible values: Alphanumeric string of up to 255 characters

Object type: String

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

Example: C:/Netscape/Server4/cert-testCA/emails/unpublishCertsJobSummary.html

Permissible values: Template file path, including the file name

Object type: String

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

Example: C:/Netscape/Server4/cert-testCA/emails/unpublishCertsJobItem.txt

Permissible values: Template file path, including the file name

Object type: String

summary.senderEmail

Specifies the sender of the summary message (who should be notified of any delivery problems).

Example: CAadmin@netscape.com

Permissible values: The full email address

Object type: String

summary.recipientEmail

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

Example: cert_agent1@netscape.com, cert_agent2@netscape.com

Permissible values: Complete email addresses, separated by commas

Object type: String

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


Event-Driven Notifications
You can configure a Certificate Manager or Registration Manager to send email notifications automatically to end entities, agents, or administrators when certain events occur. Unlike jobs that are executed at a preconfigured schedule by the Job Scheduler component, these notifications are event driven--that is, whenever the specified event occurs, the server notifies the configured user.

 Notifiable events include the following:

 Notifications of Certificate Issuance to End Entities

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.

This kind of notification involves a listener class in the subsystem that registers an interest in an appropriate event, in this case successful completion of an enrollment request. In the CMS configuration, this listener class for a Certificate Manager is defined as ca.notification.certIssued and for the Registration Manager it is defined as ra.notification.certIssued.

 When a certificate is issued, the listener builds a notification message based on a configured template and sends it to an email address that it determines by using an email resolver. By default, the email address is found in the certificate itself or in the certificate's associated enrollment request.

 The template that the listener uses to construct the email notification message is located in the configured directory. This directory has the following default location:

 <server_root>/<instance_id>/emails

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

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

Messages can be sent as HTML or plain text.

 For the certIssued listener, you can configure the following:

 Configuring a Subsystem to Send Notifications to End Entities

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

  1. Access the CMS window (see "Accessing 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.)

    4. The Certificate Issued tab appears.

  4. To enable the notification feature, check the "Enable Certificate Issued notification" option.
    5.

  5. In the Email Information Settings section, enter information as appropriate:

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

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

Notification of New Request in Queue

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.

This kind of notification involves a listener class in the subsystem that registers an interest in an appropriate event, in this case the addition of a request to the request queue. In the CMS configuration, this listener class is identified as follows:

 
ca.notification.requestInQ

When a request is added to the queue, the listener builds a notification message based on a configured template and sends it to one or more agents' email addresses as configured.

The template that the listener uses to construct the email notification message is located in the configured directory. This directory has the following default location:

 <server_root>/<instance_id>/emails

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

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

For the requestInQ event listener, you can configure the following:

 Configuring a Subsystem to Send Request Queue Notifications

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

  1. Access the CMS window (see "Accessing 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:

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

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

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


Customizing Notification Messages
Notification and 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>/<instance_id>/emails/...

<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.

<instance_id> is the ID for this instance of Certificate Management System. You first specified this when you installed this server.

Both text an HTML templates are included by default. They are listed in Table 13.6 and Table 13.7.

Templates for Event-Triggered Notifications

Table 13.6 lists the default template files provided for formulating event-triggered-notification messages. You can change the name of these files as applicable; be sure to make the appropriate changes to the configuration (see the "Content template file" field on page 367 and page 369).

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 13.6 Default templates for event-triggered notifications

Filename
Description
certIssued_CA

Template for the Certificate Manager to send plain-text notifications to end entities upon issuance of certificates.

certIssued_CA.html

Template for the Certificate Manager to send HTML notifications to end entities upon issuance of certificates.

certIssued_RA

Template for the Registration Manager to send plain-text notifications to end entities upon issuance of certificates.

certIssued_RA.html

Template for the Registration Manager to send HTML notifications to end entities upon issuance of certificates.

reqInQueue
Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.

reqInQueue.html

Template for the Certificate Manager or Registration Manager to send plain-text notifications to agents when a request enters the queue.

Note that in the CMS configuration, template files for event-triggered notifications are identified as follows:

 
<subsystem>.notification.<notification_name>.emailTemplate=

<template_file_path>


<subsystem>.notification.<notification_name>.emailTemplate=

<template_file_path>

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

Templates for Summary Notifications

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

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


Template for formatting the items to be included in the summary table, which is constructed using the riq1Summary.html template.

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

Template for formatting the items to be included in the summary report, which is constructed using the rnJob1Summary.txt template.

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. For a list of job instances created by default, see Table 14.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.

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 ISSUANCE NOTIFICATION

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@netscape.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 Certificate Issuance Notifications to End Entities

Table 13.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 13.8 Tokens defined in templates used for certificate-issuance notifications

Token
Description
$HttpHost
Specifies the fully qualified host name of the Certificate Manager or Registration Manager to which end entities should connect to retrieve their certificates. (This token enables you to construct the URL from which end entities can download 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 end-entity requests. (This token enables you to construct the URL from which end entities can download their certificates; see the example in "Customizing Message Templates".)

$InstanceID
Specifies the ID assigned to the subsystem that sent this notification.

$IssuerDN
Specifies the distinguished name of the CA that issued the certificate.

$NotAfter
Specifies the NotAfter attribute.

$NotBefore
Specifies the NotBefore attribute.

$RequestId
Specifies the request ID.

$SerialNumber
Specifies the serial number of the certificate that has been issued.

$SubjectDN
Specifies the distinguished name of the certificate subject.

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

Table 13.9 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 13.10 lists the tokens for the inner list items.

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

$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 13.11 lists the tokens that you can use for formulating the content of the RequestInQueueJob job's summary report.

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

Token
Description
$InstanceID
Specifies the ID assigned to the subsystem that sent this notification.

$ExecutionTime
Specifies the time the job (instance) was run.

$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 13.12 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 13.13.

Table 13.12 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 13.13 lists the tokens for the inner list items.

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

$Status
Specifies whether the operation failed or succeeded.

$SubjectDN
Specifies the distinguished name of the certificate subject.
 

© Copyright 1999 Netscape Communications Corp., a subsidiary of America Online, Inc. All rights reserved.