Actions
Actions
An action is a named side effect, such as starting a workflow or sending a notification. An action runs only when a state machine transition that references it fires. For more information on transitions, see State machines.
You usually define actions inline, in a transition's _actions array. Each inline action has an _executionOrder, which must be unique in the transition. You can also manage actions on their own through the actions calls. Inline actions appear in those lists too. Action names must be unique in the ontology version.
Like the rest of a state machine, actions are part of the ontology's definition. You create and change them in a draft version. For more information, see Create an action and Create a state machine.
Action types
Each action has an _actionType, and a _params object with the settings for that type:
- Script runs a script, named by
_userTypeand_scriptName. The service runs the script through a Workflow Service workflow with a single script execution task. - Workflow starts a Workflow Service workflow, named by
_workflowDefId. To pass input, set_workflowInputto a string that holds a JSON object. The service merges the transition details over it. - AI team starts an AI Service conversation with the team in
_aiTeamId. The service sends_systemPromptas you write it, with no placeholder substitution, so write the full prompt you want the team to receive. - Notification emits a platform event for the Notification Service trigger in
_notificationTriggerId. The Notification Service decides whether and how to deliver a notification. - Event fires an event on another state machine in the same ontology. By default, it targets the individuals that moved in the current transition. To target fixed individuals instead, set
_targets.
Note: The service doesn't stop an event action that leads back to its own machine and event, directly or through other machines. Such a chain repeats without end, so don't wire event actions in a cycle.
For the settings each type needs, see Action types.
When actions run
The service runs a transition's actions after it stores the new state of the individuals. The actions receive only the individuals that moved.
Keep the following in mind when you design actions:
- A failed action doesn't undo the state change.
- Actions run in
_executionOrder. Order is guaranteed only within one transition. - The service retries a failed action a limited number of times. If it still fails, the service marks it failed and runs the next action.
- An action can run more than once. To avoid duplicate effects, use the
_eventTriggerIdof the event in the systems your actions call.
The transition history doesn't record what an action did. To see each action's status, attempts, and last error, use List action executions. To find the actions of one event, filter on its _eventTriggerId.