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