# Actors and Actions

Prefer the [XML schemas dialect](schema-manual://schema-xml-1/authoring) 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.

```xml
<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.