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.

category

restrictions

Restrictions for all object types

Restrictions for Target Objects of the Type Instance

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

Restrictions for Target Objects of the Type Event

Environments

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:

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.

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.

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.

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']",
         "   ]",
         "];"
     ]
 }