Apilio

View saved version →

---
name: build-automation
description: Build a new Apilio automation from a plain-language description ("turn the heating down when nobody is home", "notify me at 7am on weekdays"). Use when the user wants to create, extend, or restructure a logicblock.
---

# Building an Apilio automation

An automation is a **logicblock**: a set of conditions combined by boolean logic, plus
actions that run when the result is true (`positive`) or false (`negative`).

Conditions and the logicblock are created separately, and conditions must exist first —
`create_logicblock` links them by UUID.

## Workflow

1. **Discover what exists.** `list_devices` (optionally `service:`), then
   `get_device_attributes` on the device you need — it returns the attribute IDs that
   conditions require and the `available_actions` that actions accept. Use
   `list_variables` for user-defined variables.

2. **Restate the automation as events + guards before creating anything.** Present the plan
   and wait for approval.

3. **Create the conditions.** `create_device_condition` for device state,
   `create_time_condition` for schedules and time windows. Keep each returned UUID.

4. **Create the logicblock.** `create_logicblock`, passing the UUIDs in the parameter
   matching each condition's type: `condition_uuids` (variable conditions),
   `timecondition_uuids`, `tuyacondition_uuids` (device conditions).

5. **Add the actions.** `add_tado_action`, `add_ewelink_action`, `add_apilio_action`,
   `add_alexa_action`, `add_ifttt_action`, or `add_action_to_logicblock` for an email
   notification. Each takes `action_group: "positive" | "negative"`.

6. **Read it back** with `get_logicblock` and summarise it for the user.

## Decisions that matter

**Mark every condition that is an event, and only those.** `triggering: true` means "when
this condition's *result* flips, re-evaluate the logicblock". Conditions that merely qualify
when the automation may act — guards — stay `triggering: false`.

- No triggering condition → the automation never fires on its own.
- A guard marked triggering → the automation fires on changes the user didn't ask about.
- An event left non-triggering → that event is silently missed.

For "turn on the fan when the temperature goes above 25°C but only in the evening", the
temperature condition is the event and the evening time frame is a guard. But for "notify me
when motion is detected or the door opens", **both** conditions are events and both must
trigger — otherwise one of them never fires the automation.

(`trigger_on_content_update` is a separate, noisier setting: it re-evaluates on every value
update rather than only when the condition's result changes.)

Time *events* (`timeevent_absolute`, `timeevent_at_sunrise`, `timeevent_at_sunset`) are
always triggering — that is what they are for. Time *frames* (`timeframe_*`) are usually
pre-conditions.

**Prefer one logicblock over several.** Combine conditions with
`condition_logic: "complex"` and a `condition_expression` using AND, OR, XOR, NOR, NAND —
e.g. `OR(motion_detected,AND(door_open,evening_hours))`, where the names are the condition
names. Nested expressions are a premium feature; the response reports
`complex_conditions_available`. Fall back to `condition_logic: "and"` when it isn't
available.

**Use the negative branch instead of an inverse logicblock.** "Heating on when home, off
when away" is one logicblock with a positive and a negative action, not two logicblocks.

## Limits and gaps

- Max 15 conditions and 20 actions per logicblock; condition and logicblock names are max
  50 characters and unique per user.
- Tuya, Philips Hue and HTTP actions cannot be created over MCP. Add an email notification
  action as a placeholder and tell the user to swap it in the Apilio web app.
- Variable conditions cannot be created over MCP either — only linked by UUID if they
  already exist.

View saved version →

---
name: troubleshoot-automation
description: Diagnose why an Apilio automation did not fire, fired at the wrong time, or produced the wrong result. Use when the user reports that a logicblock is misbehaving, or asks what a logicblock actually does.
---

# Troubleshooting an Apilio automation

Read the configuration before theorising. `list_logicblocks` gives names and UUIDs;
`get_logicblock` gives the whole thing — conditions with their comparison details, whether
they trigger re-evaluation, and the current value of the variable each one reads, plus the
condition logic and the actions for both branches.

## Workflow

1. `list_logicblocks` → find the logicblock the user means, take its UUID.
2. `get_logicblock` → the full configuration. Work through the checks below.
3. `list_log_entries` with `parent_type: "logicblock"` and `parent_uuid` → what actually
   happened, including the linked actions.
4. `get_variable` on a condition's `variable_uuid` when you need more than its current value
   — in particular when it last changed.
5. Report the cause and propose a fix. Make changes only after the user agrees.

## What to check, in order

**Is it active?** `active: false` does not stop the logicblock from evaluating — it stops it
from running any actions. So the symptom is "the logs show it evaluated but nothing
happened". The most common cause by far.

**Which condition is false?** Each condition carries `variable_value` — the current value of
the variable it reads — plus its `comparison`. Work the comparison out yourself: a numeric
condition with `variable_value: "18"` and `comparison: {operator: "greaterthan", constant:
"25"}` is false. With `condition_logic: "and"` a single false condition blocks everything;
with `condition_logic: "complex"`, read `condition_expression` — the names in it are the
condition names — and evaluate it against what you worked out.

Apilio does not persist a per-condition result, so there is no stored true/false to read
back. A `variable_value` of `null` means that variable has never received a value, which is
itself usually the answer.

Time conditions have no variable. Read `cron_expression`, `duration_seconds` and `timezone` and
reason about the schedule directly.

**Is anything triggering it?** There are two automatic paths, and a condition may use
either:

- `triggering: true` — re-evaluate when this condition's **result** flips.
- `trigger_on_content_update: true` — re-evaluate on every **value update**, even when the
  result is unchanged and even when `triggering` is false.

So check both fields on every condition before concluding nothing drives the automation. If
the event the user describes belongs to a condition with both set to false, that event never
starts it. If no condition sets either, it only ever runs when something
else evaluates it explicitly — an `apilio` action of type `logicblock_evaluate` in another
logicblock, a webhook, or a manual run. "It only works when I press the button" is this.

**Is a timing guard suppressing it?** Each condition's `timing` holds `modified_within`
(the value must have been updated within N seconds — a stale sensor makes this false) and
`unmodified_since` (the value must have been stable for N seconds — a flapping sensor makes
this false).

**Did the right branch run?** Actions are split into `positive` and `negative`. An
automation that "does nothing" often has its action on the branch that isn't being reached.

**Was the action delayed?** Each action has a `delay` of `{type: "fixed", seconds: N}` or
`{type: "random", min_seconds:, max_seconds:}`. A long delay looks like a failure.

**Did the action itself fail?** The log entries carry the failure reason. `api_error` and
`connection_error` on a Tado or eWeLink action usually mean the account connection is
broken and needs reconnecting in the Apilio web app.

## Evaluating on purpose

`evaluate_logicblock` runs the logicblock **and fires its actions** — it will switch real
devices (unless the logicblock is inactive, in which case it evaluates but runs nothing).
Ask the user before calling it, and prefer working from `variable_value`,
`last_evaluation_result` and the log entries first.