Dokumentation
IPS_GetActionsByEnvironment
string IPS_GetActionsByEnvironment (int $ZielID, string $Umgebung, bool $StandardEinbeziehen)
Parameterliste
| ZielID | ID des Zielobjekts der Aktionen oder -1 für allgemeine Aktionen ohne Zielobjekt |
| Umgebung | Umgebung, in der die Aktionen angeboten werden, z.B. "Default", "EventTrigger" oder "FlowScript" |
| StandardEinbeziehen | Bei TRUE werden zusätzlich die Aktionen der Umgebung "Default" geliefert |
Rückgabewert
Ein JSON-kodierter String mit einem Array der passenden Aktionen. Jede Aktion hat denselben Aufbau wie bei IPS_GetActions.
Beschreibung
Die Funktion liefert die Aktionen, die für das Zielobjekt mit der ID ZielID in der Umgebung Umgebung angeboten werden. Diese Auswahl zeigt auch die Verwaltungskonsole, beispielsweise in Ereignissen oder Ablaufplänen. Das Ergebnis ist ein JSON-kodierter String und muss mit json_decode dekodiert werden.
Die Umgebung ist ein frei wählbarer String, der mit den Restriktionen includeEnvironments und excludeEnvironments der Aktionen verglichen wird. Die Verwaltungskonsole verwendet folgende Umgebungen, siehe auch Umgebungen:
| Umgebung | Verwendung |
|---|---|
| Default | Standardumgebung, in der die meisten Aktionen definiert sind |
| EventTrigger | Aktionsauswahl in einem ausgelösten Ereignis |
| EventCyclic | Aktionsauswahl in einem zyklischen Ereignis |
| EventSchedule | Aktionsauswahl in einem Wochenplan |
| FlowScript | Aktionsauswahl im Ablaufplan |
| ScriptEditor | Aktionsauswahl im "Befehl hinzufügen"-Dialog des Skripteditors |
| TestCommands | Aktionsauswahl im "Befehle testen"-Dialog einer Instanz |
Für jede Aktion gelten folgende Regeln:
- Eine Aktion wird nicht angeboten, wenn Umgebung in excludeEnvironments steht.
- Eine Aktion wird angeboten, wenn Umgebung in includeEnvironments steht oder StandardEinbeziehen TRUE ist und includeEnvironments "Default" enthält. Ohne includeEnvironments gilt die Aktion als Aktion der Umgebung "Default".
- Ist ZielID -1, werden nur allgemeine Aktionen ohne Zielobjekt geliefert (Restriktion general, z.B. "Warten").
- Bei jeder anderen ZielID muss das Objekt existieren, sonst schlägt die Funktion mit "Object #... does not exist" fehl. Allgemeine Aktionen werden dann nicht geliefert. Aktionen ohne Restriktionen werden nur geliefert, wenn StandardEinbeziehen TRUE ist oder Umgebung "Default" ist. Alle weiteren Restriktionen (Objekttyp, Variablentyp, Darstellung, Profil, Variablenaktion, Schreibschutz, Modul, Idents, Skripttyp, Ereignistyp) werden gegen das Zielobjekt geprüft, siehe restrictions.
Die Reihenfolge der Einträge ist nicht garantiert. Die Liste enthält auch veraltete Aktionen (deprecated). Die Verwaltungskonsole sortiert nach priority und blendet veraltete Aktionen aus.
Beispiel
// Aktionen für eine Boolean-Variable mit Variablenaktion
$aktionen = json_decode(IPS_GetActionsByEnvironment(12345 /*[Licht Wohnzimmer]*/, 'Default', true), true);
foreach ($aktionen as $aktion) {
$bezeichnung = $aktion['locale']['de'][$aktion['caption']] ?? $aktion['caption'];
echo $aktion['id'] . ' -> ' . $bezeichnung . PHP_EOL;
}
/* liefert z.B. (Auszug):
{46B65CA6-3098-4982-9A6C-B89DADBB0A96} -> Schalte auf Wert
{A7A928A3-86AB-4FFA-AECA-39C0A2E4933D} -> Sichtbarkeit setzen
{EF078D00-FBD5-8857-F5DC-F5B54B107DD3} -> Wert umschalten
...
*/
// Allgemeine Aktionen ohne Zielobjekt, wie sie ein Ablaufplan anbietet
$allgemein = json_decode(IPS_GetActionsByEnvironment(-1, 'FlowScript', true), true);