Reusable WOML Definitions

A reusable definition creates a project-owned custom step tag without creating another workflow run.

Define props and behavior

<woml>
  <props><prop name="subtotal" required="true" /></props>
  <step name="Calculate tax"><script>
    return { tax: props.subtotal * 0.2 };
  </script></step>
</woml>

Import the file with <module name="calculate-tax" from="./calculate-tax.woml" />, then place <calculate-tax subtotal="{{context.payload.subtotal}}" /> where a normal step is allowed.

Reusable steps may include on-success, on-error, and on-complete lifecycle hooks. Props are explicit and validated. A reusable document cannot contain <workflow>, triggers, or context-dependent undeclared inputs.

Build and invoke a reusable step

Create components/calculate-tax.woml:

<woml>
  <props>
    <prop name="subtotal" required="true" />
  </props>

  <step name="Calculate tax" description="Apply the shared project tax rate.">
    <script>
      const subtotal = Number(props.subtotal);
      const tax = subtotal * 0.2;
      return { subtotal, tax, total: subtotal + tax };
    </script>
  </step>
</woml>

Import it in a runnable document:

<imports>
  <module name="calculate-tax" from="./components/calculate-tax.woml" />
</imports>

Use the custom tag where a normal step is valid:

<calculate-tax
  id="tax"
  subtotal="{{context.steps.order.subtotal}}"
  retry="3"
/>

The invocation is one durable step and publishes context.steps.tax. Invocation IDs and retry attributes remain visible in the parent workflow.

Use props as the public API

Props belong outside the reusable step in its definition file. They are invalid in runnable workflow documents. Kebab-case prop names become lower camel case under props.

Mark a prop with secret="true" when callers must supply one exact secret reference. The definition receives only declared props and should not depend on hidden parent context.

Add reusable lifecycle observation

Reusable definitions may declare on-success, on-error, and on-complete. These hooks are observational and script-only. They cannot alter the returned result or recover failed business work.

Use reusable steps for project-owned components, not arbitrary structural macros. Custom tags cannot generate hidden branches or accept arbitrary children in v1.