« Back to Product

Documentation

Send feedback!

IPS_GetActionsByEnvironment

 string IPS_GetActionsByEnvironment (int $TargetID, string $Environment, bool $IncludeDefault)

Parameters

TargetID

ID of the target object of the actions or -1 for general actions without a target object
Environment

Environment in which the actions are offered, e.g. "Default", "EventTrigger" or "FlowScript"
IncludeDefault

If TRUE, the actions of the environment "Default" are returned as well

Returns

A JSON encoded string with an array of the matching actions. Each action has the same structure as in IPS_GetActions.

Description

The function returns the actions that are offered for the target object with the ID TargetID in the environment Environment. The management console shows the same selection, e.g. in events or flow scripts. The result is a JSON encoded string and needs to be decoded with json_decode.

The environment is an arbitrary string that is compared with the restrictions includeEnvironments and excludeEnvironments of the actions. The management console uses the following environments, see also Environments:

Environment Usage
Default Default environment in which most actions are defined
EventTrigger Action selection in a triggered event
EventCyclic Action selection in a cyclic event
EventSchedule Action selection in a weekly schedule
FlowScript Action selection in a flow script
ScriptEditor Action selection in the "Add command" dialog of the script editor
TestCommands Action selection in the "Test commands" dialog of an instance

The following rules apply to each action:

  • An action is not offered if Environment is listed in excludeEnvironments.
  • An action is offered if Environment is listed in includeEnvironments, or if IncludeDefault is TRUE and includeEnvironments contains "Default". Without includeEnvironments, the action counts as an action of the environment "Default".
  • If TargetID is -1, only general actions without a target object are returned (restriction general, e.g. "Wait").
  • For any other TargetID, the object has to exist, otherwise the function fails with "Object #... does not exist". General actions are not returned in this case. Actions without restrictions are only returned if IncludeDefault is TRUE or Environment is "Default". All further restrictions (object type, variable type, presentation, profile, variable action, read-only, module, idents, script type, event type) are checked against the target object, see restrictions.

The order of the entries is not guaranteed. The list also contains deprecated actions (deprecated). The management console sorts by priority and hides deprecated actions.

Example

// Actions for a Boolean variable with a variable action
$actions = json_decode(IPS_GetActionsByEnvironment(12345 /*[Living Room Light]*/, 'Default', true), true);
foreach ($actions as $action) {
    echo $action['id'] . ' -> ' . $action['caption'] . PHP_EOL;
}

/* e.g. returns (excerpt):
{46B65CA6-3098-4982-9A6C-B89DADBB0A96} -> Switch to Value
{A7A928A3-86AB-4FFA-AECA-39C0A2E4933D} -> Set Visibility
{EF078D00-FBD5-8857-F5DC-F5B54B107DD3} -> Toggle Value
...
*/

// General actions without a target object, as offered by a flow script
$general = json_decode(IPS_GetActionsByEnvironment(-1, 'FlowScript', true), true);
Any questions?