Adding PowerShell Handlers to Alerts

To add a PowerShell handler to an alert, the alert must first be created and saved. See Alerts for more information on creating various alerts. The example below uses an expiration alert, but the process applies to all types of alerts.

Next, you must create the PowerShell script and import it into Keyfactor Command. See PowerShell Scripts for important information regarding working with scripts.

1. Select the alert to which you want to add the event handler from the respective alert grid.

2. Check the Use handler box and select the PowerShell event handler in the dropdown.

   

   Figure 148: Use PowerShell Expiration Event Handler

   Tip:  If the expected event handler types do not appear, confirm that they exist and are enabled on the Event Handler Registration page (see Event Handler Registration).

3. Click the Configure button in the Use handler section of the page to open the Configure Event Handler dialog and then click Add.

   

   Figure 149: Expiration Alert with PowerShell Event Handler

4. In the Configure Event Handler Parameters dialog, select PowerShell Script Name as the parameter A parameter or argument is a value that is passed into a function in an application. Type. The Parameter Name field will change to ScriptName. Select the desired script from the dropdown, Only scripts that are configured for the selected alert category and imported to the Keyfactor Command database will display in the dropdown. See PowerShell Scripts for more information on script handling.

5. Click Save to save your first parameter.

6. If desired, you can pass one or more parameters into your PowerShell script—either fixed text (type Static Value) or substitutable special text (type Special Text). To pass in fixed text, enter a name for the parameter (e.g. MyName), select the Static Value radio button, and type your fixed text in the Value field. To pass in special text, enter a name for the parameter (e.g. MyOtherName), select the Special Text radio button, and select your desired substitutable special text field in the Value dropdown. When referring to these parameters in your PowerShell script, refer to them using a $context hashtable parameter passed to the script, whose keys are the names entered in the event handler configuration. See Figure 150: PowerShell Event Handler with Multiple Parameters. For example, for the parameter named “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).” in the event handler configuration, you might use this line in a PowerShell script:

   Copy

   if ($context.ContainsKey("cn")) { Add-Content -Path "C:\Stuff\MyOutput.txt" -Value $context["cn"] }

   In addition to the parameters you opt to pass in the event handler configuration, there are several built-in parameters that are always passed. These can be found in Table 12: PowerShell Event Handler Special Fields. You can reference these in your PowerShell script without having to specify them in your event handler configuration.

   

   Figure 150: PowerShell Event Handler with Multiple Parameters

7. Click Close to return to the alert configuration and then save the alert.

Table 12: PowerShell Event Handler Special Fields

Name	Alert Type	Description
SendEmail	All	If true, email messages are sent in addition to processing of the PowerShell script.
Subject	All	The full subject line of the alert.
Message	All	The full message body of the alert.
Recipient	All	The recipient of the alert. Alerts configured with more than one recipient will execute the PowerShell script multiple times—once for each recipient and each certificate or request.
Certificate	Expiration Only	For internal Keyfactor use only.
First Recipient	Expiration Only	If true and the alert has multiple recipients configured, this output is for the first recipient for the given certificate. Subsequent output for the same certificate and different recipients will show false for this value.