Creating and Using PowerShell Scripts

Answer

Title :
Creating and Using PowerShell Scripts
Article:
PowerShell scripts can be used in Secret Server to automate specific tasks.  These scripts can be used in several places in Secret Server such as in creating custom remote password changers, custom dependency changers, discovery scanners, and custom ticket system integration.

Creating a PowerShell Script
From the Admin Menu, click Scripts button. On the PowerShell tab, click + Create New.  Enter the "Name", "Description", and "Script" in the dialog then click OK.  If PowerShell scripts will be use as dependencies ensures that Remote Password Changing is turned on by enabling it on the Remote Password Changing page.

Scripts may contain debug lines to help you in testing the working of the script. Debug statements use the Write-Debug command.

Example:

Write-Debug "The users name is $Username"

An input box for specifying arguments will exist in places where the PowerShell scripts are used.  Argument values are specified on a single line separated by a space.  Values containing spaces should be enclosed in quotes.  Parameters to PowerShell scripts are referenced through the zero based Args array.  It is often beneficial to assign Args variables to other more meaningful variables.

Example:

Arguments:  "Welcome back,"  Joe

$greeting = $Args[0]
$name = $Args[1]
Write-Debug "$greeting $name"?

Output: Welcome back, Joe

In situations where the script should fail given a specific set of conditions, an exception should be explicitly thrown.  When an exception is thrown, the script will stop running and the failure will be logged in the System Log.  The script is considered to have successfully run if no errors or exceptions occur while processing.

Example:

if ($meetsCondition -eq $false)
{
     throw "Did not meet condition"
}
 
Passing Parameter to PowerShell Scripts
Any use of PowerShell within Secret Server will involve passing a parameter string to the script. This string can contain literal values as well as tokens that represent values on the object in Secret Server to which the script is attached. For example, when creating a custom password changer, you will pass in values such as the user name, old password, and new password using tokens that represent these values whichever secret is running the password change script. Similarly, dependencies have a set of tokens that represent values on the dependency and it’s associated secret. Refer to the KB articles for the specific feature, such as the ones mentioned at the top of the article for specific details about what tokens are valid for that scenario. For more information, see How to Use Secret Fields in Scripts .