Action Blocks

Introduction

Action blocks allow you to group related actions together that can then be called from elsewhere as a single action (the "Action Block" action).

The action blocks feature can be accessed from the "Action Blocks" home screen tile. Pressing this will take you to a list of currently defined action blocks (or an empty list if you haven't defined any yet). From this list you can press the + button to add a new action block.

Each action block must be given a unique name and contain at least one action. A description is optional and you can also specify input and/or output parameters if you desire.

When to Use

The main reason to use action blocks is to minimize duplicated blocks of actions throughout your macros.

In some cases you may have common repeated functionality spread throughout multiple macros, for example you may set the brightness low and volume to zero at night time (using day/time trigger) in one macro. You may also wish to do the same elsewhere in another macro (for example using a location trigger when you are at the cinema). By grouping these actions into an action block you can call just a single action to invoke the action block. If you later decide to tweak these settings then you can just update the action block and avoid updating the settings in multiple places.

Kinds of variables used

Action blocks work with their own set of variables (plus Global ones if necessary) whose values can be passed from/to the calling macro.

Three kinds of variables can be used inside an action block: Input, Output and Working ones. Each one can be of any type (boolean, integer, decimal, string, array/dictionary).

All these variables are implicitly local and their lifetime is limited to action block execution. Their default values (see below) will be restored at the end of the execution so it is not possible to retreive previous values from a previous run (except when using Global variables).

Working variables are used to make all kinds of calculations/comparisons inside the action block, like any variable according to its type. The only difference with Input and Output ones is that they do not appear in the variables list when configuring the call, as they are not useful to the calling macro.

Input and Output Parameters

For more advanced use cases, action blocks allow you the option to pass in input parameters and return output parameters. In this way an action block may be used in a similar way to a function in computer programming.

For example suppose you wanted to convert from Celsius to Fahrenheit from within multiple macros. You could create an action block to do this that will take in an input parameter in Celsius and return an output parameter in Fahrenheit. The input parameters are available as local variables anywhere it makes sense to read a value. For example you can access the local variable in a pop up message, or in an expression when setting another variable value. The output variables are available as local variables anywhere it makes sense to set the value. For example in the set variable action you can assign to any output parameter.

Each input parameter will specify a default value and this value will be set in the case where you run a local test or if you do not specify an input value when calling the action block from a macro. Likewise all output parameters define a default value. In the case that the action block doesn't set an explicit value on an output parameter, it's default value will be returned.

When calling the action block you can specify what values will be passed in as input parameters and assign variables (either local or global) to capture the returned output parameters. You can also ignore any or all return parameters if you desire.

Differences between an action block and a macro?

A quick explanation might be: Macros are programs, Action blocks are functions. Below is a table that better describes the main differences.

Capabilities	Macros	Action Blocks
Has a disabling switch	Yes	No
Can be categorized	Yes	No
Has a trigger component	Yes	No
Triggers can be constrained individually	Yes	N/A
Has an action set component	Yes	Yes
Actions can include “Wait For Trigger"	Yes	Yes
Actions can be grouped into condition sets	Yes	Yes
Actions can be constrained individually	Yes	Yes
Has a constraint set component applied to all actions	Yes	No
Can create, read & update global variables	Yes	Yes
Can read & update calling macro's local variables	N/A	No
Can include Input variables	No	Yes
Can include Working variables	No	Yes
Can include Output variables	No	Yes