Static Action structure

The following section will explain the structure of a static action.

Defining static actions

In Touch Portal there are several types of actions. At the moment those are static actions and dynamic actions.

Static Actions are actions that can be run without communication. Touch Portal allows communication between the plugin and Touch Portal but for some actions this is not required. For these situations you can use the static actions. This allows for developers to create plugins easier without to much hassle. With dynamic action you are required to set up and run an application or service that communicates with Touch Portal. With static actions you can use commandline execution that run directly from Touch Portal.

An static action is an object with the following structure:

  "name":"Execute action",
  "description":"This action will play a beep sound.",
  "execution_cmd":"powershell [console]::beep(200,500)",
  "data":[ objects...]

This is the smallest version of an action JSON you can create. The data is as follows:

Attribute Type Mandatory From version Description
id Text yes 1.0 This is the id of the action. It is used to identify the action within Touch Portal. This id needs to be unique across plugins. This means that if you give it the id "1" there is a big chance that it will be a duplicate. Touch Portal may reject it or when the other action is called, yours will be as well with wrong data. Best practice is to create a unique prefix for all your actions like in our case; tp_pl_action_001.
name Text yes 1.0 This is the name of the action. This will be used as the action name in the action category list.
prefix Text yes 1.0 This is the text that is displayed before the name of the action in the action list of a button.
type Text Yes 1.0 This is the attribute that specifies whether this is a static action "execute" or a dynamic action "communicate".
executionType Text Optional 1.0 This is the attribute that specifies what kind of execution this action should use. This a Mac only functionality. Options: "AppleScript" or "Bash".
execution_cmd Text Optional 1.0 Specify the path of execution here. You should be aware that it will be passed to the OS process exection service. This means you need to be aware of spaces and use absolute paths to your executable.

If you use %TP_PLUGIN_FOLDER% in the text here, it will be replaced with the path to the base plugin folder.
description Text Optional 1.0 This will add text to the popup window. It will be shown on the top of the popup. This can be used to explain parts of the plugin data.
2.0 From version 2.0 of the Api (Touch Portal v2.2) this description will also be used in the inline actions on top to be able to add information about the action where applicable.
data Collection Optional 1.0 This is a collection of data which can be specified by the user. These data id's can be used to fill up the execution_cmd text.
tryInline Switch Optional 1.0 Adding this attribute to the action will make this an inline action. User can edit data from the action list instead of a popup. Options are "true" or "false". Default is false.
format Text Optional 1.0 This will be the format of the inline action. Use the id's of the data objects to place them within the text. Example given:

"format":"When {$actiondata001$} has {$actiondata002$} and number {$actiondata003$} is {$actiondata004$}",

This is a fictive form but it shows how to use this. The data object with the id 'actiondata001' will be shown at the given location. To have an data object appear on the action line, use the format {$id$} where id is the id of the data object you want to show the control for.
hasHoldFunctionality Switch Optional 3.0 Adding this attribute to the action will allow the action to be used with the Hold functionality. The action will appear in the list when the user wants to add actions to the hold functionality. This switch will only work with dynamic actions. Options are "true" or "false". Default is false.

Here is an example where variables are used to fill in the command line option:

  "execution_cmd":"powershell [console]::beep({$first$},{$second$})",
  "data": [

As you can see, you can use the values if you add {$value$} in the text of the execution command.