A JSON object is used to specify each action. The action's name is specified using the name action and any arguments to the action are specified as part of the same object. For example, the following code puts the text "CSPro" onto the clipboard:
{
"action": "Clipboard.putText",
"text": "CSPro"
}
Multiple actions can be specified by using an array of objects. Each action is processed sequentially. For example:
[
{
"action": "File.copy",
"source": "Dayton.jpg",
"destination": "Dayton (City in Ohio).jpg"
},
{
"action": "File.copy",
"source": "Dayton (City in Ohio).jpg",
"destination": "Dayton (City in United States).jpg"
}
]
Arguments to actions are specified in one of the JSON types: string, number, boolean, array, or object. The help page for each action will list the type, or types, permitted for each argument.
The results of all actions are returned as a string containing JSON. When specifying a single action, the result is a single object. When specifying multiple actions, the result is an array of objects. Each result object contains type, which specifies the result type. Result types can be of type undefined, string, number, boolean, array, object, or exception. If the type is not undefined, another property, value, contains the result. For example, with this input:
[
{
"action": "Clipboard.putText",
"text": "Action Invoker - JSON Example"
},
{
"action": "Clipboard.getText"
},
{
"action": "Clipboard.GETTEXT"
}
]
The result is:
[
{
"type": "undefined"
},
{
"type": "string",
"value": "Action Invoker - JSON Example"
},
{
"type": "exception",
"value": "Action Invoker error: The component of the action name must be specified in the proper case: 'GETTEXT' -> 'getText'"
}
]
When executing actions from CSCode, you can choose to view results in JSON format, or in a parsed, more readable, format.
At runtime, if any of the arguments are invalid, or if there was an error executing the action, the Action Invoker throws an
exception. As shown in the example above, the result of the action will be of
type "exception", with the exception message specified in
value.
By default, when specifying multiple actions, an exception will result in the termination of processing and subsequent actions will not be executed. However, all JSON execution environments provide options to continue processing actions even when an exception is thrown.
Because
action is used to specify the name of the action to execute, it is not possible to directly execute actions that use
action as an argument. In these rare instances, you can use the
execute action to specify the arguments, which can then contain
action as one of the arguments. For example, the
Localhost.mapActionResult executes another action with the action name specified using the argument
action. This example shows the workaround used to execute this in JSON format:
{
"action": "execute",
"arguments": {
"action": "Localhost.mapActionResult",
"arguments": {
"action": "Message.formatText",
"arguments": {
"text": "%s, %s",
"arguments": [
"Hello",
"World!"
]
}
}
}
}