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,
        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)