Running
Action Invoker actions from CSPro logic requires calling functions using
dot notation. All actions are contained within the
CS namespace, so when calling an action, write
CS. before the action name. Additional namespaces can be specified, separated by dots, followed by the action name. Specify arguments for the action using the
named arguments syntax. For example, the following code puts the text
"CSPro" onto the clipboard:
Arguments to actions are specified in one of the following types: string, number, boolean, array, or object. The help page for each action will list the type, or types, permitted for each argument. Because CSPro logic does not natively support all types, and does not support objects at all, you can use the @ operator to specify the type. The following table specifies how arguments can be specified:
For example, this code copies one file, specified as a string, to the directory "Images":
CS.File.copy(source := "Image01.jpg",
destination := "Images");
By using
@array, this code indicates that the
source argument is an array, not a string. This copies two files:
CS.File.copy(source := @array "[ \"Image01.jpg\", \"Image02.jpg\" ]",
destination := "Images");
If the second example were written without the @ operator specifying the argument type, CSPro would interpret the array argument as a string, which would ultimately result in a runtime error.
The results of all actions are returned as strings containing
JSON, or a value representing undefined. This return value can be of type undefined, string, number, boolean, array, or object. Because it is difficult to work with JSON in CSPro logic, a
logic setting, enabled by default, allows you to modify how results are returned to make them easier to use in CSPro logic. The following table gives examples of how return values are handled given the setting:
Return Type | As JSON | Converted for CSPro Logic |
undefined | "" | "" |
string | "\"text\"" | "text" |
number | "44" | "44" |
boolean | "true" / "false" | "1" / "0" |
array | "[1, 2, 3]" | "[1, 2, 3]" |
object | "{ \"key\": \"value\" }" | "{ \"key\": \"value\" }" |
Even with the conversion, the result is a string. If you want to convert it further to a native CSPro type:
Return Type | Conversion Strategy |
number | Use the tonumber function. |
boolean | Use the tonumber function. |
array | Use the Symbol.updateValueFromJson function with an Array or List object. |
object | At this time, CSPro logic does not provide a way to work with objects. Consider using JavaScript to work with actions that return objects. |
If you would like to process the result of an action before it is returned, you can add an
OnActionInvokerResult callback function to your code. If that function returns a non-blank string, the result will not be converted for CSPro logic, regardless of the logic setting.
When compiling actions, the compiler will issue errors if any required arguments are missing, or if the type of an argument is invalid. However, unlike many other logic functions, no additional checking is done during compilation. At runtime, if any of the arguments are invalid, or if there was an error executing the action, the Action Invoker throws an
exception. Because CSPro logic does not support handling exceptions, if an exception is thrown, CSPro will display a runtime error message and return a blank string.
To be notified when an exception is thrown, and to potentially process it, you can add an
OnActionInvokerResult callback function to your code. If that function suppresses the exception, no runtime error message will display.