POST Extensions Scripts

The POST /Extensions/Scripts method is used to add a new script to the database. This method returns HTTP 200 OK on a success with details of the newly created script record.

Important:  This is the only means to add a script to the database. There is no UI equivalent for security reasons. (Upgrading from a version previous to version 11 will import existing scripts into the database as the only other means of adding scripts to the database).
Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/scripts/modify/

Table 483: POST Extensions Scripts Input Parameters

Name In Description
Name Body Required. A string indicating the user-defined name of the script. The name of a script cannot be changed once posted.

Contents

 Body

Required. A JSON-escaped string containing the contents of the script on a single line.

Tip:  See below for examples of creating and handling this string.
Categories Body

Required. An array of either integers or case-sensitive strings indicating which category or categories the script applies to. The category of a script cannot be changed if it is in use in any alerts or workflows of that category.

Example:  Two Approaches to Importing Scripts to the Database

To create a string value for the Contents field, you need to take your script, turn it into a string, and JSON-escape the string so that CR/LFs, tabs and the like will be encoded appropriately and the string will be on a single line. For example, the following string contains escaped CR/LFs (\r\n):

$MyVar = \"Hello, World!\"\r\n\r\nWrite-Host $MyVar

One approach to doing this uses a PowerShell script similar to the following, which takes the script to be uploaded as input and creates an output file with the JSON-escaped string:

Copy 
# Path to the input file
$filePath = "C:\Stuff\UpdateSubjectSANs.ps1"

# Get the contents of the input file as a string (as opposed to an array of strings) into a variable
$fileContent = Get-Content -Path $filePath -Raw

# Set variables for the other body parameters - for multiple categories, use commas (e.g. 2,3,4)
$ScriptName = "UpdateSubjectSANs"
[int32[]]$Categories = 6 

# Build the body
$body = @{
   "Name" = $ScriptName
   "Contents" = $fileContent.ToString()
   "Categories" = $Categories
}

# JSON escape the body elements
$JSONbody = ConvertTo-JSON $body

# Output the body elements including the escaped Contents string to a file
Set-Content -Value $JSONbody -Path C:\Stuff\MyOutFile.txt

The contents of the output file will look something like (the Contents field is shown truncated here):

Copy 
{
   "Categories":  [
      6
   ],
   "Contents":  "# Declare your parameters at the beginning ($CSRSubject, $CSRSANs)\r\nparam(\r\n   [string]$CSRSubject,\r\n   [string]$CSRSANs,\r\n",
   "Name":  "UpdateSubjectSANs"
}

You can then open the output file, display the content without line wrapping the Contents field, and copy either the entire body or the JSON-escaped Contents string for pasting into your APIClosed command. Any line wraps that display on the screen in the Contents field will be interpreted by copy/paste as CR/LF, which will cause the API command to fail. If your script is long, you will need to be sure to use a text editor to open the file that can display the entire length of the Contents string as a single line. The built-in Windows Notepad application will display a maximum of 1024 characters on a line before wrapping even if word wrap is disabled. A tool such as the third-party Notepad++ is much less limited.

Alternately, you can do the JSON-escaping and update to the Keyfactor Command database in a single PowerShell script and skip the file output with copy/paste. The following script will JSON-escape a script and add it to the database:

Copy 
# Prompt for credentials to authenticate to the Keyfactor API
$cred = Get-Credential

# Encode credentials (assumes the Keyfactor API is using Basic authentication)
$pair = "$($cred.Username):$($cred.GetNetworkCredential().Password)"
$encodedCreds = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($pair))
$basicAuthValue = "Basic $encodedCreds"

# Path to the input file
$filePath = "C:\Stuff\UpdateSubjectSANs.ps1"

# Keyfactor Command server name and optional port for API request
$APIServer = "keyfactor.keyexample.com"

# Set variables for the other body parameters - for multiple categories, use commas (e.g. 2,3,4)
$ScriptName = "UpdateSubjectSANs"
[int32[]]$Categories = 6

# Get the contents of the input file as a string (as opposed to an array of strings) into a variable
$fileContent = Get-Content -Path $filePath -Raw

# Build the headers
$headers = @{
   "Authorization"=$basicAuthValue
   "Accept"="application/json"
   "x-keyfactor-requested-with"="APIClient"
}

# Build the body
$body = @{
   "Name" = $ScriptName
   "Contents" = $fileContent.ToString()
   "Categories" = $Categories
}

# Make the API request to create a new script in the database
Invoke-WebRequest -Uri "https://$APIServer/KeyfactorAPI/Extensions/Scripts" -Method:Post -Headers $headers -ContentType "application/json" -Body ($body|ConvertTo-Json) -ErrorAction:Stop -TimeoutSec 60

Table 484: POST Extensions Scripts Response Data

Name Description
id An integer indicating the Keyfactor Command reference ID for the script.
Name A string indicating the user-defined name of the script. The name of a script cannot be changed once posted.

Contents

A JSON-escaped string containing the contents of the script on a single line.
Categories

An array of either integers or case-sensitive strings indicating which category or categories the script applies to. The category of a script cannot be changed if it is in use in any alerts or workflows of that category.

Tip:  See the Keyfactor API Reference and Utility which provides a utility through which the Keyfactor API endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the top of the Management Portal page next to the Log Out button.