Adding PowerShell Handlers to Alerts

Documentation Suite v10.1

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

Select the alert to which you want to add the event handler from the respective alert grid.
Check the Use handler box and select the PowerShell event handler in the dropdown.

Figure 137: 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).
Click the Configure button in the Use handler section of the page to open the Configure Event Handler dialog and then click Add.

Figure 138: Expiration Alert with PowerShell Event Handler
In the Configure Event Handler Parameter A parameter or argument is a value that is passed into a function in an application. dialog, select PowerShell Script Name as the parameter Type, and enter the filename and optional relative path to the PowerShell script, located in the extensions directory on the Keyfactor Command server, in the Value field.
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.
Click Save to save your first parameter.
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 139: 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:
```
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 139: PowerShell Event Handler with Multiple Parameters

Figure 140: Example of a List of Special Text Parameters
Click Close to return to the alert configuration and then save the alert.
If your PowerShell script is unsigned, you may need to enable execution of unsigned PowerShell scripts on the Keyfactor Command server with this PowerShell command:

Set-ExecutionPolicy RemoteSigned
Test the alert as described in Expiration Alert Operations. It is not necessary to check the Send Alerts box during the test to cause the PowerShell script to run.

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.

To create a PowerShell script that works with the event handlers, there are just a few things to keep in mind:

You need to declare the $context hashtable at the start of the script with this line:
```
[hashtable]$context
```
Parameters you want to use in your script are referenced using the $context syntax as follows (where "MyName" is the name you gave to the parameter in the event handler configuration or the name of the built-in parameter from Table 12: PowerShell Event Handler Special Fields):
```
$context["MyName"]
```

Here is a simple script that takes as inputs all the parameters you defined in your event handler configuration as well as the built-in parameters and outputs them to a file along with a comment and the date, with configuration to skip output of a defined list of the built-in parameters:

# This is a sample script that can be set up as a Keyfactor Command event handler. The script will output
# data passed to the handler to a text file. This script will be called for the combination of each
# certificate involved in the corresponding event and each configured email recipient.

# In order to communicate with the extension script, the Keyfactor Command event handler framework injects
# a hashtable into the PowerShell runspace. This hashtable will include the fields configured by the
# administrator when setting up the handler as well as some built-in system fields used for communication
# with the handler.

# The following fields are provided for communication with the handler:
#   Subject -        Email subject line that will be sent if the alert has the email subject configured
#   Message -        Email body that will be sent if the alert has the email message body configured
#   Recipient -      Email address where the alert will be sent if the alert has this configured
#   Certificate -    For internal use only
#   SendEmail -      Boolean (true/false) indicating if Keyfactor Command is planning on sending an email
#                    for this certificate / recipient combination
#   FirstRecipient - Boolean (true/false) indicating if this extension invocation is the first recipient
#                    for a given certificate
#                    This can be used in the event it is desired to execute some logic once per certificate
#                    This field applies only to expiration alerts

[hashtable]$context

# Four of the built-in context fields can be modified and used as output fields to change how (and if)
# Keyfactor Command will send emails related to the alert being processed:
#   Subject - If an email is produced this new value will be used to create the email subject.
#   Message - If an email is produced this new value will be used to create the email message body.
#   Recipient - If an email is produced this new value will be used as the email recipient.
#   SendEmail - This value can be used to override whether an email will be sent.
#     A value of "true" will cause an email to be sent, while "false" will cause the associated email
#     to not be sent.
#     Examples:
#       $context["Subject"] = "new subject line"
#       $context["Message"] = "new message line"
#       $context["Recipient"] = "newRecipient@keyexample.com"
#       $context["SendEmail"] = "false"

# Typically output values would be used with some form of logic. As an example, to change the recipient
# of the email based on a metadata field provided to the handler, uncomment the following, provide
# appropriate values (including a metadata field that's being passed in to the handler in place of
# "SampleMetadataField"), and remove Recipient from ignoreKeys:
#
#	if ($context["SampleMetadataField"] -eq "SomeValue") {
#		$context["Recipient"] = "newRecipient@keyexample.com"
#		}

# This example will output to a file the $context values for the user configured fields and skip the system
# supplied ones. To output the system supplied fields, remove the desired items from the $ignoreKeys array.
$ignoreKeys = "Subject", "Message", "SendEmail", "Certificate", "FirstRecipient", "Recipient"

# Path to the output file
$outputFile = ("C:\PSScripts\Output\SampleScriptOutput" + (get-date -UFormat "%Y%m%d%H%M") + ".txt")

# Add a comment and the date at the start of each output block
Add-Content -Path $outputFile -Value "Starting Output: $(Get-Date -format G)"

# Loop through all passed in key/value keys and process
$context.GetEnumerator() | % {
	if (-not $ignoreKeys.Contains($_.key)) {
		Add-Content -Path $outputFile -Value ($_.key + ": " + $_.value)
	}
}

# Add a blank line between output blocks
Add-Content -Path $outputFile -Value ""

Tip: A sample PowerShell script is installed with Keyfactor Command in the ExtensionLibrary directory.

Adding PowerShell Handlers to Alerts

Products

Solutions

Resources

Company