Overview
The CommandHandler allows for any command to be executed on a server as if it were being called from the command line prompt. This assumes any required software for the command is installed and execute rights exist for the user making the execute request.
(Example : If the command is "sqlplus.exe", the handler assumes that Oracle has been installed where the command will run and that whatever credentails the handler is running under has rights to run "sqlplus.exe" on that destination.)
Plan Details
Config
The config section of the plan specifies the command to execute and where it should be executed. It also indicates how long it should attempt to run the command before giving up and what to do if that time is exceeded.
Sample
Handler:
Type: Synapse.Handlers.CommandLine:CommandHandler
Config:
Type: Yaml
Values:
RunOn: myserver.mydomain.com
WorkingDirectory: C:\Temp
Command: powershell.exe
TimeoutMills: 10000
TimeoutStatus: Failed
KillRemoteProcessOnTimeout: true
ValidExitCodes:
- "EqualTo 0 Complete"
ReturnStdout: true
Element | Type/Value | Required | Description |
---|---|---|---|
RunOn | String | No | Server where the command should be executed. (Default = localhost) |
WorkingDirectory | String | No | Directory where the command should be run from. (Default = C:\Temp) |
Command | String | Yes | The command to execute (ex: powershell.exe) |
TimeoutMills | long | No | Number of milliseconds to wait before timing out. (Default = Never Timeout) |
TimeoutStatus | "None" "New" "Initializing" "Running" "Waiting" "Cancelling" "Complete" "Success" "CompletedWithErrors" "SuccessWithErrors" "Failed" "Cancelled" "Tombstoned" "Any" |
No | Status to return when a timeout occurs. Click here for more details on Synapse StatusType values. (Default value = "None". Return status will be evaluated based on Exit Code instead.) |
KillRemoteProcessOnTimeout | boolean | No | Specifies whether the process running on the "RunOn" server should be terminiated when a timeout occurs. This only applies when RunOn is specified. Process will always terminate on timeout when RunOn is not specified. (Default Value = false) |
ValidExitCodes | "EqualTo" "NotEqualTo" "LessThan" "LessThanOrEqualTo" "GreaterThan" "GreaterThanOrEqualTo" "Between" "NotBetween" |
No | Specifies what status to report back based on exit code returned from the action exexuted Click here for detailed scription of the syntax. (Default = "EqualTo 0"). Syntax : [OPERATOR] VALUE1 [VALUE2] [STATUS] |
ReturnStdout | boolean | No | Specifies whether or not StdOut / Stderr should be returned in the ExitData field and made available in the ParentExitData element for future actions. (Default Value = true) Used mostly when excessive command output being stored in memory becomes a memory usage issue for the handler. |
SupportsDryRun | boolean | No | Indicates that the script or command specified has implemented the DryRun functionality, and should be called when the DryRun flag is specified. (Default Value = false) The plan is responsible for passing the ~~IsDryRun~~ flag into the script or command where expected. |
Parameters
The Parameters section specifies any arguments passed to the command, and optionally manipulates the argument string using Regular Expression replacement.
Sample
Parameters:
Type: Yaml
Values:
Arguments: -ExecutionPolicy Bypass -File C:\Temp\test-base64.ps1 -p1 aaa -p2 bbb -p3 ccc
Expressions:
- Find: (-p1\s*)aaa(\s*-p2)
ReplaceWith: ${1}xxx${2}
- Find: bbb
ReplaceWith: yyy
- Find: ccc
ReplaceWith: Hello World
Encoding: Base64
Element | Type/Value | Required | Description |
---|---|---|---|
Arguments | String | No | The arguments passed into the command. |
Expressions | List of : - Find: ..ReplaceWith: ..Encoding: |
No | Performs a Regular Expression replacement of the Arguments element matching on element "Find" and replacing with value "ReplaceWith". Optional "Encoding" of the value can occur. Supported Encoding : "Base64" Click here for detailed description of each element. |
Parameter Substitution
The command handler allows for certain Synapse data to be passed into the command arguments via parameter substitution. These "variables" are specified by enclosing the parameter name between double-tilde delimeters like "~~ PARAMETER ~~". These parameter names are case insenstive and any white space between the tildes is ignored.
Parameters:
Type: Yaml
Values:
Arguments : -ExecutionPolicy Bypass -File C:\Hold\test.ps1 -p1 "~~IsDryRun~~" -p2 "bbb" -p3 "ccc"
Expressions:
- Find: bbb
ReplaceWith: Action Name = ~~actionName~~
- Find: ccc
ReplaceWith: ~~ rUnTiMeTiMeTyPe ~~
Available Handler Variables
Variable | Native Type | Passed As | Description |
---|---|---|---|
InstanceId | Long | String | Unique Identifier for this run of Synapse. |
PlanInstanceId | Long | String | Unique Identifier for this run of Synapse. (Same as InstanceId) |
ActionInstanceId | Long | String | Unique Identifier for this action in this run of Synapse. |
IsDryRun | Boolean | "True" or "False" | Flag indicating whether this is a true "run" of the hander, or a test. |
ParentExitData | Object | Base64 Encoded Result of "ToString()" | Standard Output and Standard Error logs from the command. |
RequestNumber | String | String | Id tying the run back to a change request. |
RequestUser | String | String | User making the request. |
ActionName | String | String | Action name from the plan document. |
RuntimeType | String | String | Description of which handler dll was being used by Synapse. |
Detailed Descriptions
Below are detailed descriptions of the enumerations and synatax used in the config and parameter sections above.
ValidExitCodes Values and Syntax
A space-delimited string that specifies exit codes and what status they represent.
Syntax : "[OPERATOR] VALUE1 [VALUE2] [STATUS]"
Value | Required | Description |
---|---|---|
OPERATOR | No | Indicates how the exit code is to be evaluated. See table below for details. (Default = "EqualTo") |
VALUE1 | Yes | The value to compare to the exit code. |
VALUE2 | Yes* | The 2nd value to compare the exit code to. Only used with Between and NotBetween Operators. |
STATUS | No | The StatusType to return when the expression is true. (Default = "Complete") |
Possible Operators :
Operator | Example | Description |
---|---|---|
EQ, EQU, or EqualTo | EQ 0 xxxxx | Returns STATUS when exit code is equal to VALUE1 |
NE, NEQ, or NotEqualTo | NEQ 0 xxxxx | Return STATUS when exit code is not equal to VALUE1 |
LT, LSS or LessThan | LessThan 0 xxxxx | Returns STATUS when exit code is less than VALUE1 |
LE, LEQ, or LessThanOrEqualTo | LE -1 xxxxx | Returns STATUS when exit code is less than or equal to VALUE1 |
GT, GTR or GreaterThan | GTR 0 xxxxx | Returns STATUS when exit code is greater than VALUE1 |
GE, GEQ, or GreaterThanOrEqualTo | GreaterThanOrEqualTo 1 xxxxx | Returns STATUS when exit code is greater than or equal to VALUE1 |
BT, BTW, or Between | BTW 10 20 xxxxx | Returns STATUS when exit code is between VALUE1 and VALUE2 (inclusive) |
NB, NBT, or NotBetween | NB -20 -10 xxxxx | Returns STATUS when exit codes is not between VALUE1 and VALUE2 (exclusive) |
StatusType Values
StatusType values are part of the Synapse Core project. The values below are current as of the last update to this documentation, but for the most recent values, please check the SynapseProject GitHub page. (synapse.net > Synapse.Core > Classes > Enums > StatusType.cs)
namespace Synapse.Core
{
public enum StatusType
{
None = 0,
New = 1,
Initializing = 2,
Running = 4,
Waiting = 8,
Cancelling = 16,
Zombie = 32,
Complete = 128,
Success = 128,
CompletedWithErrors = 256,
SuccessWithErrors = 256,
Failed = 512,
Cancelled = 1024,
Tombstoned = 2048,
Any = 16383
}
}
EncodingType Values
Tells the CommandHandler how the values should be encoded when replaced.
Value | Description |
---|---|
None | No Encoding Used. |
Base64 | Encodes value as BASE64 string. |
Regex Arguments
A detailed description of the Regex variable replacement object used in the Parameters section of the CommandHandler.
Element | Type/Value | Required | Description |
---|---|---|---|
Find | String | Yes | Regex string to match against the Argument string. |
ReplaceWith | String | Yes | String to replace matched values with |
Encoding | Enum | No | Specifies how to encode the ReplaceWith string before replacement. Click here for valid values. (Default = None) |