11.3. Customizing Notification Messages

The email notifications are constructed using a template for each type of message. This allows messages to be informative, easily reproducible, and easily customizable. The CA uses templates for its notification messages. Separate templates exist for HTML and plain text messages.

11.3.1. Customizing CA Notification Messages

Each type of CA notification message has an HTML template and a plain text template associated with it. Messages are constructed from text, tokens, and, for the HTML templates, HTML markup. Tokens are variables, identified by a dollar sign ($), in the message that are replaced by the current value when the message is constructed. See Table 11.3, “Notification Variables” for a list of available tokens.
The contents of any message type can be modified by changing the text and tokens in the message template. The appearance of the HTML messages can be changed by modifying the HTML commands in the HTML message template.
The default text version of the certificate-issuance-notification message is as follows: 
Your certificate request has been processed successfully.
SubjectDN= $SubjectDN
IssuerDN= $IssuerDN
notAfter= $NotAfter
notBefore= $NotBefore
Serial Number= 0x$HexSerialNumber
To get your certificate, please follow this URL:
https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&
 serialNumber=$SerialNumber
Please contact your admin if there is any problem.
And, of course, this is just a \$SAMPLE\$ email notification form.
This template can be customized as desired, by rearranging, adding, or removing tokens and text, as shown: 
THE EXAMPLE COMPANY CERTIFICATE ISSUANCE CENTER
Your certificate has been issued!
You can pick up your new certificate at the following website:
https://$HttpHost:$HttpPort/displayBySerial?op=displayBySerial&
 serialNumber=$SerialNumber
This certificate has been issued with the following information:
Serial Number= 0x$HexSerialNumber
Name of Certificate Holder = $SubjectDN
Name of Issuer = $IssuerDN
Certificate Expiration Date = $NotAfter
Certificate Validity Date = $NotBefore
Contact IT by calling X1234, or going to the IT website http://IT
 if you have any problems.
Notification message templates are located in the /var/lib/pki/instance_name/ca/emails directory.
The name and location of these messages can be changed; make the appropriate changes when configuring the notification. All template names can be changed except for the certificate rejected templates; these names must remain the same. The templates associated with certificate issuance and certificate rejection must be located in the same directory and must use the same extension.
Table 11.1, “Notification Templates” lists the default template files provided for creating notification messages. Table 11.2, “Job Notification Email Templates” lists the default template files provided for creating job summary messages.

Table 11.1. Notification Templates

Filename Description
certIssued_CA Template for plain text notification emails to end entities when certificates are issued.
certIssued_CA.html Template for HTML-based notification emails to end entities when certificates are issued.
certRequestRejected.html Template for HTML-based notification emails to end entities when certificate requests are rejected.
certRequestRevoked_CA Template for plain text notification emails to end entities when a certificate is revoked.
certRequestRevoked_CA.html Template for HTML-based notification emails to end entities when a certificate is revoked.
reqInQueue_CA Template for plain text notification emails to agents when a request enters the queue.
reqInQueue_CA.html Template for HTML-based notification emails to agents when a request enters the queue.

Table 11.2. Job Notification Email Templates

Filename Description
rnJob1.txt Template for formulating the message content sent to end entities to inform them that their certificates are about to expire and that the certificates should be renewed or replaced before they expire.
rnJob1Summary.txt
Template for constructing the summary report to be sent to agents and administrators. Uses the rnJob1Item.txt template to format items in the message.
rnJob1Item.txt Template for formatting the items included in the summary report.
riq1Item.html Template for formatting the items included in the summary table, which is constructed using the riq1Summary.html template.
riq1Summary.html
Template for formulating the report or table that summarizes how many requests are pending in the agent queue of a Certificate Manager.
publishCerts
Template for the report or table that summarizes the certificates to be published to the directory. Uses the publishCertsItem.html template to format the items in the table.
publishCertsItem.html
Template for formatting the items included in the summary table.
ExpiredUnpublishJob
Template for the report or table that summarizes removal of expired certificates from the directory. Uses the ExpiredUnpublishJobItem template to format the items in the table.
ExpiredUnpublishJobItem
Template for formatting the items included in the summary table.
Table 11.3, “Notification Variables” lists and defines the variables that can be used in the notification message templates.

Table 11.3. Notification Variables

Token Description
$CertType
Specifies the type of certificate; these can be any of the following:
  • TLS client (client)
  • TLS server (server)
  • CA signing certificate (ca)
  • other (other).
$ExecutionTime Gives the time the job was run.
$HexSerialNumber Gives the serial number of the certificate that was issued in hexadecimal format.
$HttpHost Gives the fully qualified host name of the Certificate Manager to which end entities should connect to retrieve their certificates.
$HttpPort Gives the Certificate Manager's end-entities (non-TLS) port number.
$InstanceID
Gives the ID of the subsystem that sent the notification.
$IssuerDN Gives the DN of the CA that issued the certificate.
$NotAfter Gives the end date of the validity period.
$NotBefore Gives the beginning date of the validity period.
$RecipientEmail Gives the email address of the recipient.
$RequestId Gives the request ID.
$RequestorEmail Gives the email address of the requester.
$RequestType Gives the type of request that was made.
$RevocationDate Gives the date the certificate was revoked.
$SenderEmail Gives the email address of the sender; this is the same as the one specified in the Sender's E-mail Address field in the notification configuration.
$SerialNumber Gives the serial number of the certificate that has been issued; the serial number is displayed as a hexadecimal value in the resulting message.
$Status Gives the request status.
$SubjectDN Gives the DN of the certificate subject.
$SummaryItemList Lists the items in the summary notification. Each item corresponds to a certificate the job detects for renewal or removal from the publishing directory.
$SummaryTotalFailure Gives the total number of items in the summary report that failed.
$SummaryTotalNum Gives the total number of certificate requests that are pending in the queue or the total number of certificates to be renewed or removed from the directory in the summary report.
$SummaryTotalSuccess Shows how many of the total number of items in the summary report succeeded.