Otter Documentation

powershell - PSEnsure

  • Last Modified: 2018-11-09

This is generated from the built-in components of Otter 2.1, and may be different than what you have installed (especially if you have extensions); go to [User Icon] > Documentation within your Otter instance to see exactly what operations are available.

PSEnsure

Uses two PowerShell scripts to Collect, and then Ensure a configuration about a server.

Operation type:

Ensuring - this operation will ensure a specified configuration exists on a remote server after comparing its current state to the desired state.

Script usage:

PSEnsure(
	Key: <text>,
	Value: <text>,
	[Collect: <text>],
	[Configure: <text>],
	[CollectScript: <text>],
	[ConfigureScript: <text>],
	[UseExitCode: <true/false>],
	[Debug: <true/false>],
	[Verbose: <true/false>],
	[CollectScriptParams: <%(key1: value1, ...)>],
	[ConfigureScriptParams: <%(key1: value1, ...)>]
);

This operation may be prefixed with PowerShell::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name Format Script Usage Usage Notes
Configuration key
text
Key
This argument is required.
Expected value
text
Value
This argument is required.
Collection script
text
Collect
The output of this PowerShell script will be used to collect the current configuration of the server. Variables are not expanded within the contents of this property.
Configure script
text
Configure
This PowerShell script is executed if the configuration gathered using the collection script does not match the stored configuration. Variables are not expanded within the contents of this property.
Collection script asset
text
CollectScript
The name of a PowerShell script asset to use for collection. The output of this PowerShell script will be used to collect the current configuration of the server.
Configuration script asset
text
ConfigureScript
The name of a PowerShell script asset to use for configuration. This script is executed if the configuration gathered using the collection script does not match the stored configuration.
Use exit code
true/false
UseExitCode
When set, the exit/return code of the script will be used instead of the output stream for collection.
Debug
true/false
Debug
Captures the PowerShell Write-Debug stream into Otter's execution debug log.
Verbose
true/false
Verbose
Captures the PowerShell Write-Verbose stream into Otter's execution debug log.
Collection script parameters
%(key1: value1, ...)
CollectScriptParams
Map containing named arguments to pass to the PowerShell collect script.
Configure script parameters
%(key1: value1, ...)
ConfigureScriptParams
Map containing named arguments to pass to the PowerShell configure script.

Note: The Key is a unique string per server, and having multiple operations attempt to use the same key will yield in unpredictable behavior.

Example:

# ensures the BuildMaster Agent service exists on the remote server
PSEnsure(
    Key: BuildMasterAgentInstalled,
    # returns the count of INEDOBMAGT services installed
    Collect: @(Get-Service | Where-Object {$_.Name -eq "INEDOBMAGT"}).Count,
    # expected value is 1
    Value: 1,
    # if the returned value is 0 instead of 1, the installer will run
    Configure: & '\\filesrv1000\$e\Resources\BuildMasterAgentSetup.exe' /S /AgentType=TCP /Port=8080,
    Debug: true,
    Verbose: true
);

# ensures the BuildMaster Agent service exists on the remote server, using a
# PowerShell script asset to perform the configuration
PSEnsure(
    Key: BuildMasterAgentInstalled,
    # returns the count of INEDOBMAGT services installed
    Collect: @(Get-Service | Where-Object {$_.Name -eq "INEDOBMAGT"}).Count,
    # expected value is 1
    Value: 1,
    # use script stored in InstallBmAgent asset
    ConfigureScript: InstallBmAgent,
    ConfigureScriptParams: %(
        AgentType: TCP,
        Port: 1000),
    Debug: true,
    Verbose: true
);

Have a question? Try the Q&A Forum

Our documentation is now Open Source and on GitHub. We highly encourage our users to contribute and get involved! .