Skip to content
Innomesh Docs
Room Manager

Macros

Macros are custom actions, defined as scripts, that fire on a trigger. Triggers can be event-based (e.g. when the system powers on) or time-based (optionally restricted to specific days). Common applications include automatically powering rooms at set times, recalling DSP presets when rooms link, and recalling lighting presets when a source is selected.

Macros consist of two components: triggers (event based or time based) and actions (what executes when triggered). Macros can be created at the template level, with room-level editing available if enabled in the template’s Room Options.

📝 Note
If you have a use case that is not covered here, contact your Account Manager. Our engineers can help design the right triggers and actions for your room.

Macro Structure

Each macro is made up of the following fields:

FieldTypeRequiredDescription
IDstringYesThe unique identifier for the macro.
NamestringNoA name for easy reference. Required for manually triggerable macros.
Manually TriggerablebooleanNoDefaults to false. Exposes the macro as a button on supported UIs and makes it reachable via room.TriggerMacro.
TriggersobjectNoThe triggers that set off the macro: Time Triggers, Event Triggers, and an optional Condition. Required for the macro to fire on its own; a macro that is only triggered manually (or via room.TriggerMacro) needs no triggers.
ActionsarrayYesThe actions the macro executes when triggered.
📝 Note
Not all user interfaces are capable of manually triggering macros. Contact your Account Manager for details regarding compatibility and potential costs.

Triggers

By default a macro fires when any one of its triggers fires. Since v2.23.0 you can instead require all event triggers, or a custom combination, to be satisfied. See Conditional Macro.

Time Based Triggers

These activate at specified times, using the room’s local time. Each time trigger has the following fields:

FieldTypeRequiredDescription
IDstringYesThe unique identifier for the trigger.
TimestringYesThe 24-hour time (HH:mm:ss) at which the macro triggers.
DaysstringNoThe day(s) of the week on which the macro triggers. Accepts comma-delimited weekday names, or Weekday / Weekend. If omitted, the macro triggers every day.
🚨 Caution
Time must be zero-padded HH:mm:ss exactly. A value like 9:00:00 passes validation but never fires; write 09:00:00. Day names in Days are case-sensitive (Monday, not monday).

Event Based Triggers

Event triggers monitor room or device state changes. Each event trigger has the following fields:

FieldTypeRequiredDescription
IDstringYesThe unique identifier for the trigger.
GuidstringYesThe trigger identifier of the object publishing the state: a manager guid (e.g. audio.manager) or a device’s configured ID.
PropertystringYesThe state (property) this trigger watches.
KeystringNoFor states with multiple values (e.g. one per destination type), the key by which the value is accessed.
IndexstringNoFor list states, the index by which the value is accessed.
ValuestringNoThe value the state must change to for the trigger to fire. If omitted, an empty string must match.
❗ Important
Value matching is exact and case-sensitive. Boolean states publish as True and False (capitalised); a lowercase true in a trigger never matches. This is the opposite of action scripts, where lowercase true / false is correct.

Event triggers fire on the transition into the configured value, not while the state simply holds that value. For device states this typically happens shortly after startup as devices connect, so a trigger on a value a device already holds can fire on boot.

Available Triggers and Actions

The full, versioned catalogue of trigger states and action functions lives on two reference pages: see Available States for every Guid / Property (and its Key / Value forms) you can trigger on, and Available Actions for every function you can call from a script, with parameters and version availability. Anything not listed there is internal and unsupported in macros.

❗ Important
Managers have two identifiers. A manager is triggered by its guid (e.g. Guid: "audio.manager" in an event trigger) but called by its binding (e.g. audio.SetAudioLevel(...) in a script). Only room is the same in both roles. Devices are triggered by their configured device ID as the Guid, and called through the device keyword with the action’s Device ID field set. Both reference pages list each manager’s pair.

Actions

Each action defines what executes when the macro fires, using the following fields:

FieldTypeRequiredDescription
IDstringYesThe unique identifier for the action.
ScriptstringYesThe script the action runs: a prefix and a function call.
Device IDstringNoRequired when the script uses the device keyword: the ID of the device the action targets.
DelayintegerNoThe delay, in whole seconds, between the trigger(s) firing and the action executing.

Actions are written as a prefix and a function call, for example room.SetSourceSelect("source.pc", "Main"). The prefix is the manager’s binding (room, audio, video, etc., shown beside each title on the Available Actions page). Actions without a Delay run in the order they are listed; delayed actions are queued and run after their delay elapses.

All parameters listed for a function must be provided.

Examples and Common Use Cases

Below are complete macro configuration examples showing the JSON structure, trigger conditions, and action scripts.

Automatic Lighting on Shutdown

Turn off the lights every night at 11:00 PM, with a short delay to allow shutdown processes to complete.

{
  "ID": "lights.off",
  "Name": "Nightly Lights Off",
  "Triggers": {
    "Time Triggers": [
      { "ID": "trigger.nightly", "Time": "23:00:00" }
    ]
  },
  "Actions": [
    { "ID": "lights.off", "Script": "lighting.PresetRecall(\"preset.off\")", "Delay": 5 }
  ]
}

Unmute the Microphone When a Call Connects

Note the dual identifiers: the trigger uses the guid conferencing.manager, while the script calls the same manager as conferencing.

{
  "ID": "macro.unmute.on.call.connect",
  "Name": "Unmute Mic When Call Connects",
  "Triggers": {
    "Event Triggers": [
      { "ID": "incall.trigger", "Guid": "conferencing.manager", "Property": "CallStatus", "Value": "InCall" }
    ]
  },
  "Actions": [
    { "ID": "action.mic.unmute", "Script": "conferencing.PerformConferencingAction(\"microphone unmute\")" }
  ]
}

Recall a DSP Preset When a Source is Selected

When the jack input is selected on the “Main” destination type, recall a preset on the DSP. The trigger uses a Key because SourceSelect holds one value per destination type, and the action uses Device ID so the script’s device keyword resolves to the DSP.

{
  "ID": "macro.audio.jack",
  "Name": "Switch Jack Audio",
  "Triggers": {
    "Event Triggers": [
      { "ID": "event.jack.selected", "Guid": "room", "Property": "SourceSelect", "Key": "Main", "Value": "av.source.jack" }
    ]
  },
  "Actions": [
    { "ID": "dsp.preset.recall.1", "Script": "device.PresetRecall(\"{}:source:jack\")", "Device ID": "dev.dsp.1" }
  ]
}

Set Presentation Lighting When a Source is Routed

When a source is selected on the “Audience Left” destination, recall the presentation lighting preset.

{
  "ID": "macro.lights.presentation",
  "Name": "Presentation Lighting",
  "Triggers": {
    "Event Triggers": [
      { "ID": "trigger.1", "Guid": "room", "Property": "SourceSelect", "Key": "Audience Left", "Value": "source.pc.left" }
    ]
  },
  "Actions": [
    { "ID": "action.1", "Script": "lighting.PresetRecall(\"preset.presentation\")" }
  ]
}

Tips

  • Escaping quotes: Macro scripts are JSON strings, so double quotes inside a script must be escaped with a backslash (\") when uploading JSON.
  • Delays: Use whole-second delays to sequence actions that depend on each other (e.g. wait for a display to power on before routing a source).
  • Multiple triggers: A single macro can have both event and time triggers. By default it fires when any trigger fires; see Conditional Macro to require all event triggers or a custom combination of them. Time triggers are not part of the Condition and always fire independently.
  • Device actions: When using device. functions, always set the action’s Device ID field to the target device’s ID, and keep manager-prefixed calls in a separate action.