Actors and Actions

Prefer the XML schemas dialect for embedded schemas. It supports native form annotations such as input-type="password", related-resource="device", editor-language="lua", and property-order. Existing JSON text and CDATA remain supported; each resource keeps its existing validation and execution restrictions.

An actor gives an instance its running behavior: lifecycle hooks, Lua libraries, event subscriptions, timers and Actions. Scripts use the instance’s declared bindings and modules. Lua syntax and types are checked by the shared language engine; resource access is enforced when the script runs.

An Action has a name, label, source and optional input, config and output schemas. Input is the first vararg; Action configuration is supplied separately at invocation. A running actor uses its instance's published definition.

<integration id="com.example.action" version="1.0.0" sdk-version="2.0">
  <actor><actions><action name="echo" label="Echo">
    <input-schema>
      <schema type="object" xmlns="urn:cococo:json-schema:1">
        <property name="value" type="string"/>
        <required name="value"/>
      </schema>
    </input-schema>
    <source><![CDATA[local input = ...; return { value = input.value }]]></source>
    <output-schema>
      <schema type="object" xmlns="urn:cococo:json-schema:1">
        <property name="value" type="string"/>
        <required name="value"/>
      </schema>
    </output-schema>
  </action></actions></actor>
</integration>

Actor source uses return values, rather than a global exports entry script. CustomApp server APIs have their own exports convention. Event subscriptions select event topics. Events carry identifiers; use the SDK to look up the details your handler needs. Timers name schedules. Neither subscriptions nor timers accept installation values.

Async SDK functions return a success flag followed by a value or error; check the flag first. timeout-ms is 1 to 60000 milliseconds, default 5000. Script and call data limits apply to every invocation. Inputs, Action configuration and results are limited to 2 MiB of encoded JSON per value. Instance configuration and incoming event payloads share the 2 MiB limit.

On an Integration instance, open Actions, select a callable Action, complete its input and Action configuration forms, and choose Invoke Action. Schemas come from the instance's published definition. Actions without object schemas accept JSON input. Results appear as JSON; validation and execution errors retain their field paths. Start a paused instance before invoking an Action.