Function

Description

To allow reuse, a function can be defined that will execute a block of commands. This function can then be called in multiple places and multiple operations. The 'Function' keyword is used both when defining and invoking a function.

Function Definition

A user-defined function is defined in the 'Functions' array.

Parameter Name	Description	Type	Resolved Type	Required
Name	The unique name that identifies the user-defined function.	String	String	Yes
Parameters	An optional array of parameters expected by the function.	Array	Array	No
Do	The list of commands that will be executed when the function is invoked. The function may return a value at any point by calling the 'Return' command. The returned value can be of any type - either a simple type (e.g. string, boolean) or a complex object. If no Return is encountered, all the commands in the Do block are executed.	Do Block	Do Block	Yes

Function Parameters

Each parameter in the declared list must specify the name, type and default value.

Parameter Name	Description	Required
Name	The name used to identify the parameter	Yes
Description	A description of the parameter	No
Type	The type of the parameter. Current types are: Boolean Integer Float String Array Object Secret Email	Yes

Function Call

Invoke a user-defined function. Parameters can optionally be passed in to the function, and a result may optionally be passed back from the function. The function definition determines whether parameters are expected, and whether a value is returned.

Parameter Name	Description	Type	Resolved Type	Required
Name	The name of the user-defined function.	String	String	Yes
Parameters	An array of parameters to pass in to the function. A value must be passed in for each parameter declared by the function.	Array	Array	No
ResultVariable	The name of the variable to receive the return value of the function call (if there is one). This variable will be created if it does not already exist. The type is determined by the value returned by the function. The script writer must ensure that function call and definition manipulate the same type	String	String	No
IsSecret	If true, causes the ResultVariable created to be flagged as secret so that it's value is not logged. Default=false.	Boolean	Boolean	No

Examples

Example: Define the function 'LoginSsh'

"Functions":[
  {
     "Name":"LoginSsh": {
     "Parameters": [
       { "UserName": { "Type": "String" }},
       { "Password": { "Type": "Secret" }},
       { "LoginKey": { "Type": "Secret" }}
     ],
     "Do": [
        { "Comment": { "Text": "Your code here" }},
        { "Return" : { "Value": true } }
     ]
  }
]

Example: Call the function 'LoginSsh' with the appropriate args, and log the result

{
    "Function": {
        "Name": "LoginSsh",
        "ResultVariable": "LoginResult",
        "Parameters": [
            "%FuncUserName%",
            "%FuncPassword%",
            "%UserKey::$%"
        ]
    }
},
{ "Log": { "Text":"Login function returned the bool value %{ LoginResult }%" }},
{ "Condition": { "If" : "%{ LoginResult }%", 
   "Then" : { "Do": [ { "Log": { "Text" : "Function was successful" }}]},
   "Else" : { "Do": [ { "Log": { "Text" : "Function failed" }}]}
}