« Back to Product

Documentation

Actions

Require: IP-Symcon >= 6.0

Description

It is possible to define your own actions as part of the Library. After installing the library, these can be used as described under Actions .
If actions are saved or configured, this results in three values: The action target, the ActionID and the action parameters. The action target represents the target object, for example the underlying object in the case of an Event. The ActionID uniquely identifies the selected action. The parameters are a set of values which individually belong to the action. This allows a user to further parameterize an action and, for example, specify the value to which a variable should be switched.

Structure

For each action that should be part of the library, a JSON file must be created in the "actions" subfolder of the library. This JSON file must contain a JSON object that follows the following structure.

Parameter Data type Description
id string Unique GUID for the identification of the action. GUID Generator
caption string Visible name of the action
form array / string This field can contain an array of configuration elements as in the "elements" or "actions" areas of the Configuration Forms. Alternatively, the form can be generated dynamically by a PHP script. In this case, this field contains the corresponding code, which the configuration form returns as an object. The PHP code can be split into multiple strings in an array of strings. If an action that has already been defined is to be processed, for example in an Event, the defined parameters are available as system variables, see SelectAction. The settings of the form represent the parameters of the action, with each named configuration element making its value available under its "name".
action array / string PHP code that defines the execution of the action. If the action is carried out, the PHP code from this field is carried out. In doing so the parameters are available as system variables.
priority (optional) int Priority of the action, in a selection actions are sorted according to priority
category (optional) string (default: "other") The short form of the category of the action. Possible categories are listed under category .
restrictions (optional) array (default: []) A list of restrictions which limit the conditions under which this action is offered. The possible restrictions are described in the tables restrictions .
locale (optional) object (default: []) Here, as in the Localization of a Module, the action can be localized. This localizes both the form and the caption.
format (optional) string (default: content of caption) This string represents a short formatting of the action with its parameters, which can be displayed in different places. The formatting is noted in ICU syntax . There the parameters (name according to the parameter) and the target (name "TARGET") can be used as variables. Some additional Symcon-specific types are available for formatting. The content of format is translated by the locale.
description (optional) string (default: "") This text is displayed as a description for the action in the action selection. The content of description is translated by the locale.
readable (optional) array / string (default: content of action, whereby all status variables of parameters are replaced by the set values) PHP code, which returns the action as readable code. This is used, for example, for "insert commands" in the script editor. In doing so the parameters are available as system variables.
deprecated (optional) array / string (default: Not deprecated) If this parameter is set, this action is considered as deprecated and the action is not shown in any selections. Whenever a dialog to edit the action is opened, the PHP code in this parameter is executed with the currently set parameters. This action is immediately transformed to the action definition which is returned from the code.

category

Short form Name Description
target Target specific Actions that belong to a specific target, usually a module
math Mathematical operations Mathematical operations to modify objects
set Set value Actions that set the value of a variable
switch Switch value Actions that switch the value of a variable
expert Expert Actions that require a deeper understanding of IP-Symcon or PHP
other Other actions Actions that don't fit into any other category

restrictions

Restrictions for all object types

Parameter Data type Description
objectType array The action is only offered for targets of the specified types (0 = category, 1 = instance, 2 = variable, 3 = script, 4 = event, 5 = media, 6 = link)
includeEnvironments array A list of environments in which the action is offered, see Environments
excludeEnvironments array A list of environments in which the action is not offered. If it matches "includeEnvironments", the action is not displayed. See Environments
writable bool If this restriction is set to true, the action is only offered if the target object is not write-protected. If the target is a variable, it must not have a Variable Action.

Restrictions for Target Objects of the Type Instance

Parameter Data type Description
hasActionStatusVariables bool If this restriction is set to true, the action is only offered if the instance has at least one switchable status variable
hasInstanceFunctions bool If this restriction is set to true, the action is only offered if the instance has at least one public function that was not inherited from the IPSModule
moduleID array The action is only offered if the ModuleID of the target instance is included in this list
hasIdent array The action is only offered if the target instance has a child for each entry of the list, that has the corresponding ident (since IP-Symcon 6.1)
hasNoIdent array The action is only offered if the target instance has NO child that has an ident corresponding to an entry of the list (since IP-Symcon 8.0)

Restrictions for Target Objects of the Variable Type

Parameter Data type Description
requestAction bool If this restriction is set to true, the action is only offered if the variable has a variable action
variableType array The action is only offered if the variable type of the target variable is contained in this list (0 = Boolean, 1 = Integer, 2 = Float, 3 = String)
profilesInclude array The action is only offered if the name of the profile the target variable is currently using is included in this list
profilesExclude array The action is only offered if the name of the profile the target variable is currently using is NOT in this list
profileIsEnum bool If this restriction is set to true, the action is only offered if the profile of the variable represents an enumeration (step size = 0, at least one association)
profileIsPercentage bool If this restriction is set to true, the action is only offered if the profile of the variable represents a percentage value (suffix = "%", max value > min value)

Restrictions for Target Objects of the Type Automation

Parameter Data type Description
scriptType array The action is only offered if the automation type of the automation is included in this list (0 = PHP script, 1 = Flow script, 2 = IPSWorkflow) (since version 6.1)

Restrictions for Target Objects of the Type Event

Parameter Data type Description
eventType array The action is only offered if the event type of the event is included in this list (0 = Triggered, 1 = Cyclic, 2 = Schedule) (since version 6.3)

Environments

Environment Description
Default The default environment in which most actions are defined, many choices are limited to these actions or offer them in addition
TestCommands Action selection in the "Test commands" dialog of an instance, "Default" actions are not offered here
EventTrigger Action selection in a triggered event
EventCyclic Action selection in a cyclical event
EventSchedule Action selection in a weekly plan
FlowScript Action selection in the schedule
ScriptEditor Action selection in the "Add command" dialog of a script editor
Other environments You can define your own environments, for example to offer special actions as part of an instance configuration

System Variables

Both in a possible PHP script for the form and in the script for the execution, the target of the action and the set parameters can be accessed via system variables. The following system variables are available in these scripts:

System variable Description
$_IPS['TARGET'] ObjectID of the target of the action
$_IPS [(name of the parameter)] (e.g. $ _IPS ['VALUE']) The set or selected value of the parameter. These fields are not available in a script for the form if the action is initially selected and therefore no parameters have yet been selected. Therefore, the PHP function isset should be used to check whether the system variables are available.
Further system variables Additional system variables are available based on the execution of the action. If the parameter names overlap, the parameter values are used and the regular system variables cannot be accessed.

Formatting

All types of the ICU format can be used in the format field. In addition, Symcon-specific types were introduced. As usual with ICU, these consist of three parts: The parameter designation, the type designation and optional additional parameters.

profile

The value is presented based on the profile of the target variable. If the target does not have a profile, the value is displayed directly.

Examples: {VALUE, profile}

object

The name of the object with the ObjectID of the value is displayed.

Parameter Description
ident (optional) If "ident" is specified as the parameter followed by a parameter name, the name of the child with the ident that corresponds to the parameter is displayed instead. If the value is behind ident in single quotation marks ('), the value in between them is directly used as Ident.

Examples: {VARIABLE, object}, {TARGET, object, ident IDENT}

action

The formatting of the action, which is coded as a JSON string in the value, is shown.

Parameter Description
targetID (optional) If "targetID" is specified as the parameter followed by a parameter name, the TargetID of the formatted action is set to the value of the corresponding parameter. If "ident" is also given immediately afterwards, followed by a parameter name, the target ID is instead displayed on the child's object ID with the ident that corresponds to the parameter. If the value is behind ident in single quotation marks ('), the value in between them is directly used as Ident.

Beispiele: {ACTION, action}, {ACTION, action, targetID VARIABLE}, {ACTION, action, targetID TARGET ident IDENT}

scheduleAction

The names of weekly plan actions of weekly plans are displayed under the specified parent object with the ID of the value.

Parameter Description
parent If "parent" is specified as the parameter followed by a parameter name, the object is used as the parent object with the value as its ID
action If "action" is specified as the parameter, followed by an ActionID in single quotation marks ('), only the names of weekly plan actions that carry out the corresponding action are displayed

Examples: {SCHEDULE_ACTION, scheduleAction, parent PARENT}, {SCHEDULE_ACTION, scheduleAction, parent PARENT action '{7938A5A2-0981-5FE0-BE6C-8AA610D654EB}'}

Examples

switchValueString.json

{
     "id": "{A4D52B67-BE4B-4AD0-964F-B9BA2556AAB0}",
     "caption": "Switch to Value",
     "form": [
         {
             "type": "ValidationTextBox",
             "name": "VALUE",
             "caption": "Value"
         }
     ],
     "action": "RequestAction($_IPS['TARGET'], $_IPS['VALUE']);",
     "restrictions": {
         "objectType": [ 2 ],
         "variableType": [ 3 ],
         "profileIsEnum": false,
         "requestAction": true
     },
     "priority": 10,
     "locale": {
         "de": {
             "Switch to Value": "Schalte auf Wert",
             "Value": "Wert",
             "Set to {VALUE, profile}": "Setze auf {VALUE, profile}"
         }
     },
     "format": "Set to {VALUE, profile}"
 }

setValueIntegerPreviousReminder.json

{
     "id": "{92971E6F-4AC1-BEF8-B325-9E044D27B3EB}",
     "caption": "Set to Value",
     "form": [
         "$form = [",
         "    {",
         "        'type' => 'SelectColor',",
         "        'name' => 'VALUE',",
         "        'allowTransparent' => false,",
         "        'caption' => 'Value',",
         "        'writable' => true",
         "    }",
         "];",
         "if (isset($_IPS['VALUE'])) {",
         "    $form[] = {",
         "        'type' => 'Label'",
         "        'caption' => 'Previously selected value: ' . $_IPS['VALUE']",
         "    };",
         "}",
         "return $form;"
     ],
     "action": "SetValue($_IPS['TARGET'], $_IPS['VALUE']);",
     "restrictions": {
         "objectType": [ 2 ],
         "variableType": [ 1 ],
         "profilesExclude": [ "~HexColor" ]
     },
     "priority": 5,
     "locale": {
         "de": {
             "Set to Value": "Setze auf Wert",
             "Value": "Wert",
             "Set to {VALUE, profile}": "Setze auf {VALUE, profile}"
         }
     },
     "format": "Set to {VALUE, profile}"
 }

switchStatusVariable.json

{
     "id": "{E616C2B2-A827-1712-4AE0-841C57B3DD74}",
     "caption": "Switch Status Variable",
     "form": [
         "$options = [];",
         "$firstVariable = false;",
         "foreach (IPS_GetChildrenIDs($_IPS['TARGET']) as $childID) {",
         "    $object = IPS_GetObject($childID);",
         "    if (($object['ObjectType'] === 2) && ($object['ObjectIdent'] !== '')) {",
         "        if (!HasAction($childID)) {",
         "            continue;",
         "        }",
         "        if (!$firstVariable) {",
         "            $firstVariable = $object;",
         "        }",
         "        $options[] = [",
         "            'caption' => $object['ObjectName'],",
         "            'value' => $object['ObjectIdent']",
         "        ];",
         "    }",
         "}",
         "return [",
         "   [",
         "       'type' => 'Select',",
         "       'name' => 'IDENT',",
         "       'caption' => 'Status Variable',",
         "       'options' => $options,",
         "       'value' => $firstVariable['ObjectIdent'],",
         "       'onChange' => 'IPS_UpdateFormField(\"ACTION\", \"targetID\", IPS_GetObjectIDByIdent($IDENT, ' . $_IPS['TARGET'] . '), $id);'",
         "   ],",
         "   [",
         "       'type' => 'SelectAction',",
         "       'name' => 'ACTION',",
         "       'caption' => 'Action',",
         "       'targetID' => isset($_IPS['IDENT']) ? IPS_GetObjectIDByIdent($_IPS['IDENT'], $_IPS['TARGET']) : $firstVariable['ObjectID']",
         "   ]",
         "];"
     ],
     "action": [
         "$targetVariableID = IPS_GetObjectIDByIdent($_IPS['IDENT'], $_IPS['TARGET']);",
         "$action = json_decode($_IPS['ACTION'], true);",
         "echo IPS_RunActionWait($action['actionID'], $targetVariableID, $action['parameters']);"
     ],
     "restrictions": {
         "objectType": [ 1 ],
         "hasActionStatusVariables": true
     },
     "locale": {
         "de": {
             "Switch Status Variable": "Schalte Statusvariable",
             "Status Variable": "Statusvariable",
             "{TARGET, object, ident IDENT}: Switch Variable": "{TARGET, object, ident IDENT}: Schalte Variable"
         }
     },
     "format": "{TARGET, object, ident IDENT}: {ACTION, action, targetID TARGET ident IDENT}",
     "readable": [
         "$targetVariableID = IPS_GetObjectIDByIdent($_IPS['IDENT'], $_IPS['TARGET']);",
         "$action = json_decode($_IPS['ACTION'], true);",
         "$action['parameters']['TARGET'] = $targetVariableID;",
         "$action['parameters']['ENVIRONMENT'] = $_IPS['ENVIRONMENT'];",
         "$action['parameters']['PARENT'] = $_IPS['PARENT'];",
         "echo IPS_GetActionReadableCode($action['actionID'], $action['parameters']) . \"\\n\";"
     ]
 }

multiplySetVariable.json (deprecated action)

{
     "id": "{085176EC-BEE5-3732-15E5-8C82875CABD4}",
     "caption": "Multiply with Value of other Variable",
     "form": [
         "$variable = IPS_GetVariable($_IPS['TARGET']);",
         "$types = [];",
         "if ($variable['VariableType'] === 2) {",
         "    $types = [1, 2];",
         "}",
         "else {",
         "    $types = [ $variable['VariableType'] ];",
         "}",
         "return [",
         "   [",
         "       'type' => 'SelectVariable',",
         "       'name' => 'VARIABLE',",
         "       'caption' => 'Variable',",
         "       'validVariableTypes' => $types",
         "   ]",
         "];"
     ],
     "action": "SetValue($_IPS['TARGET'], GetValue($_IPS['TARGET']) * GetValue($_IPS['VARIABLE']));",
     "restrictions": {
         "objectType": [ 2 ],
         "variableType": [ 1, 2 ],
         "profileIsEnum": false,
         "writable": true
     },
     "locale": {
         "de": {
             "Multiply with Value of other Variable": "Multipliziere mit Wert einer anderen Variablen",
             "Variable": "Variable",
             "Multiply by value of {VARIABLE, object}": "Multipliziere mit Wert von {VARIABLE, object}",
             "Set the target variable to its current value multiplied with the value of another variable": "Setze die Zielvariable auf ihren aktuellen Wert multipliziert mit dem Wert einer anderen Variablen"
         }
     },
     "format": "Multiply by value of {VARIABLE, object}",
     "category": "math",
     "description": "Set the target variable to its current value multiplied with the value of another variable",
     "deprecated": [
         "return [",
         "   'actionID' => '{A3153696-013A-41B1-A001-5E8085D95465}',",
         "   'parameters' => [",
         "       'DYNAMIC' => true,",
         "       'FACTOR' => 0,",
         "       'VARIABLE' => $_IPS['VARIABLE']",
         "   ]",
         "];"
     ]
 }
Any questions?