Pending Request Alert Operations

1. In the Management Portal, browse to Alerts > Pending Request.
2. On the Pending Certificate Request Alerts page, click Add from the top menu to create a new alert, or Edit from either the top or right click menu, to modify an existing one.

3. In the Pending Request Alert Settings dialog, select your Certificate Template (or select All Templates) in the first dropdown.

   

   Figure 120: Create a New Pending Request Alert

4. In the Display Name field, enter a name for the alert. This name appears in the pending request alerts grid in the Management Portal.

5. In the Subject field, enter a subject line for the email message that will be delivered when the alert is triggered. You can use substitutable special text in the subject line. Substitutable special text uses a variable in the alert definition that is replaced by data from the certificate or certificate metadata Metadata provides information about a piece of data. It is used to summarize basic information about data, which can make working with the data easier. In the context of Keyfactor Command, the certificate metadata feature allows you to create custom metadata fields that allow you to tag certificates with tracking information about certificates. at processing time. For example, you can enter {rcn} in the alert definition and each alert generated at processing time will contain the specific requested common name A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com). of the given certificate request instead of the variable {rcn}.

   To add substitutable special text to the subject line; place your cursor where you would like the text to appear on the subject line, select the appropriate variable from the Insert special text dropdown, and click Insert. Alternately, type the special text variable enclosed in curly braces (e.g. {cn A common name (CN) is the component of a distinguished name (DN) that represents the primary name of the object. The value varies depending on the type of object. For a user object, this would be the user's name (e.g. CN=John Smith). For SSL certificates, the CN is typically the fully qualified domain name (FQDN) of the host where the SSL certificate will reside (e.g. servername.keyexample.com or www.keyexample.com).}).

6. In the Message box, enter the body of the email message that will be delivered when the alert is triggered. You can use the Insert special text dropdown below the message window to add substitutable special text to the message. The metadata that appears in the dropdown will depend upon the custom metadata you have defined (see Certificate Metadata). Place your cursor where you would like the text to appear, select the appropriate variable from the dropdown, and click Insert. Alternately, you can type the special text variable enclosed in curly braces directly. In addition to the substitutable special text fields available in the dropdown, you can also build your own substitutable fields for the requester based on string values from the user or computer Active Directory record. See Table 10: Substitutable Special Text for Pending Request Alerts. If desired, you can format the message body using HTML. For example, you could place the certificate detail information into a table by replacing this text:

   CN: {rcn}
   DN A distinguished name (DN) is the name that uniquely identifies an object in a directory. In the context of Keyfactor Command, this directory is generally Active Directory. A DN is made up of attribute=value pairs, separated by commas. Any of the attributes defined in the directory schema can be used to make up a DN.: {rdn}
   SAN The subject alternative name (SAN) is an extension to the X.509 specification that allows you to specify additional values when enrolling for a digital certificate. A variety of SAN formats are supported, with DNS name being the most common.: {san}

   With this HTML code:

   <table>
   <tr><td>CN:</td><td>{rcn}</td></tr>
   <tr><td>DN:</td><td>{rdn}</td></tr>
   <tr><td>SAN:</td><td>{san}</td></tr>
   </table>
7. The Approval Link substitutable special text field is an important one to include in your alert intended for the administrator responsible for approving or denying the certificate request. This provides a link in the email message that the administrator can click to be taken to an approve/deny page for the certificate in the Management Portal to either approve or deny the request. This certificate-specific approval page cannot be directly accessed within the Management Portal (though you can approve certificate requests in the Management Portal from the Certificate Requests page (see Certificate Requests).

8. Check the Use handler box if you would like the alert to trigger an event handler at processing time, select the appropriate handler in the dropdown, and click the Configure button to configure the event handler. See Using Event Handlers for more information on using event handlers.

   Note:  As of version 9.0 of Keyfactor Command, PowerShell scripts for alert handlers need to be in the extension path or a subdirectory of it specified by the Extension Handler Path application setting (see Application Settings: Console Tab). By default this is:

   C:\Program Files\Keyfactor\Keyfactor Platform\ExtensionLibrary\

   For example, create a directory called Scripts under the ExtensionLibrary directory and then reference your PowerShell script as Scripts\MyPowerShell.ps1. Any scripts referenced by PowerShell handlers that are outside this path will fail to run.

9. In the Recipients section of the page, click Add to add a recipient to the alert. Each alert can have multiple recipients. Recipients should be added one at a time. You can enter specific email addresses and/or use substitutable special text to replace an email address variable with actual email addresses at processing time. The built-in variable can be selected in the Recipient dialog Use a variable from the certificate request dropdown. In addition, you can type a special text variable enclosed in curly braces in the Email field if you have, for example, a metadata field that contains an email address.

   Keyfactor Command sends SMS (text) messages by leveraging the email to text gateways that many major mobile carriers provide. Check with your carrier for specific instructions. Keyfactor has tested that AT&T can be addressed using 10-digit-number@txt.att.net (e.g. 4155551212@txt.att.net) and Verizon can be addressed using 10-digit-number@vtext.com (e.g. 2125551212@vtext.com). T-Mobile can be addressed using 10-digit-number@tmomail.net (e.g. 2065551212@tmomail.net), but functionality can be spotty. Reliability of alerting via this method depends on the reliability of the carrier’s gateways.

   

   Figure 121: Pending Request Alerts Recipients

10. Click Save to save your pending request alert.

You may use the copy operation to create multiple similar alerts—for example, one to the requester of the certificate and one to the administrator(s) responsible for approving it.

1. In the Management Portal, browse to Alerts > Pending Request.
2. On the Pending Certificate Request Alerts page, highlight the row in the alerts grid and click Copy at the top of the grid, or from the right click menu.
3. The Pending Request Alert Settings dialog will pop-up with the details from the selected alert. The display name field will have "- Copy" tagged to the end of it to indicate it is a new alert. You may modify the alert as needed and click Save to add the new alert, or Cancel to cancel the operation.

1. In the Management Portal, browse to Alerts > Pending Request.
2. On the Pending Certificate Request Alerts page, highlight the row in the alerts grid and click Delete at the top of the grid, or from the right click menu.
3. On the Confirm Operation alert, click OK to confirm or Cancel to cancel the operation.

After adding your desired pending request alerts, you may configure a schedule to send the alerts.

1. In the Management Portal, browse to Alerts > Pending Request.
2. On the Pending Certificate Request Alerts page, click the Configure button at the top of the Pending Request Alerts page to open the Pending Certificate Request Alert Schedule dialog and configure a monitoring execution schedule. This defines the frequency with which alerts are sent. You can choose to schedule the alerts for:

• Daily delivery at a specified time

• An Interval of anywhere from every 1 minute to every 12 hours

• Turn Off a previously configured schedule

Once the alerts are configured, you may run a test of all or selected alerts to see if they are configured correctly.

1. In the Management Portal, browse to Alerts > Pending Request.
2. On the Pending Certificate Request Alerts page, either highlight one row in the pending request alerts grid and click the Test button at the top of the grid or click the Test All button at the top of the grid to test all the alerts.
3. In the Pending Alert Test dialog in the Alert Parameters section, click the toggle button for Send Alerts , if you would like to deliver email messages as part of the test.
4. Click the Generate button to begin generating alerts. Depending on the number of certificate requests to process, this may take a few seconds.
5. In the Pending Alert Test dialog in the Alert Data and Alert Message sections, you can review the certificate requests found to confirm that the expected requests are appearing and that the substitutable special text is being replaced as expected. Scroll the First, Previous, Next and Last buttons at the bottom of the dialog. The number of alerts generated will display between the navigation buttons.