Best practices

Early access feature

The "Automations" feature is in early access and only available to select customers. If you are interested in getting access, please contact us.

This is the recommended way to add proactive AI, or any other enrichment, to content. Give an automation ownership of a workflow stage: it fires when content enters that stage, does its work (review, translate, compute fields, generate metadata), then transitions the content forward on success or to an error stage on failure.

This makes "is the work done?" an observable workflow state, gives you a natural human checkpoint, and bounds how often the expensive work runs. In a multi-step workflow that may have several automation-powered stages, use a single automation to handle the whole workflow.

Configure the workflow stage the automation targets so the run can actually do that work:

  • Modify: Add the role the automation runs as to the stage's Modify permission. Without it, the run cannot change the content.
  • Outgoing transitions: On each transition the automation will take from that stage (for example, advancing on success or moving to an error stage), add the same role to Can transition.
  • Settings: If a Scout automation, or a code automation that calls Scout, will move content into a stage, leave Auto publish and Require validity unchecked on that destination stage.

Reserve auto-publish and require-validity for human stages

Auto publish and Require validity run in the editor, so they apply to transitions a person makes. Scout works headlessly and leaves those transitions to a human, which keeps publishing and validation under human review: it will not move content into a stage that has either setting on. Leave both unchecked on the stages Scout moves content into, and use them on human-facing stages such as a final Approved stage.

See the automation identity for how a code automation is granted a role. Scout automations are assigned a role in the dashboard when you create them.

Enrich content from a workflow stage, not from a save event#

Work that mutates the entity that was just saved, such as computing fields or enhancing content, is best triggered from a workflow stage rather than a save event. An automation that writes on save creates a new version while the author is still working, which can lead to save conflicts. The workflow-stage pattern above runs the same work at a deliberate moment instead.

Events are broadcast with no ordering guarantees when multiple automations subscribe to the same trigger. Write handlers that tolerate being run twice for the same input and that don't depend on another automation having finished first.

A run can't pause and resume or coordinate with other runs. Split multi-step flows across workflow stages rather than forcing them into a single handler, especially when the flow has a human checkpoint in it.

A filter drops uninteresting events before a run is created, which avoids the cost, log noise, and run-history clutter of a run that would immediately reject itself. This matters most for Scout automations, where every run consumes AI credits.

Logs are retained and viewable, and they aren't redacted. Keep credentials and personal data out of log output.

Write a unit test suite for each automation to pin its logical behavior, which makes revisions more reliable. Automations are ordinary functions, so testing them needs no special harness.

Automations are a good fit for focused, self-contained work. Consider running your own backend and triggering it with an outbound webhook instead when your job:

  • Needs to run longer than the automation limits allow.
  • Requires advanced execution logic or its own cloud architecture.
  • Requires multiple layers of permissions.
Last modified