Concepts

Action Execution

How actions get executed

# Overview

Actions are the work horses of Stubber.
Actions are defined on the flow.
Anytime anything happens in Stubber, an action is being executed. Having an understanding of how actions are executed is key to understanding how Stubber works.
Actions can get triggered by various mechanisms, primarily on the stub interface, by an LLM, by a feedback call or by a webhook.
A full list of trigger methods can be found here.
Once an action is triggered it starts execution.

# Execution Phases

Actions do 4 things:

1. collect data
2. run tasks
3. send notifications
4. record metrics

Actions do these things in 3 execution phases:

1. intent - the user or AI is evaluating the action for required data
2. execution - the action is being executed
3. effect - the action is sending notifications and recording metrics

# Data Collection

The first part of action execution is to collect data. This is done by the system that will trigger the action.
This is usually one of the following:

# 1. Stub Action

On the Stubber Platform, a stub action is triggered by a user on the stub interface. A form is presented to the user and the user fills in the form and submits the form.

# 2. Feedback Action

A Stubber system receives a message for example a WhatsApp message, or Webchat message and the system will call the feedback action with all the data from the message. A feedback action could also be a LLM response, where the LLM is replying to a prompt.

# 3. LLM Action Call

The LLM calls an action directly. This is done by the LLM calling the action with the data that is specified in the action fields.

# 4. Webhook Action

A webhook is called by an external system and the webhook will call the action with the data that is specified in the action fields.

# 5. Heimdal Action

A Heimdal action is called by the Heimdal system when an event is triggered. The data passed to the action will be based on the event that was emitted into Heimdal.

A full list of trigger methods can be found here.

# Execution Order

# 1. Trigger and Queueing

The first part of understanding how actions work is to understand how an action is triggered.
Once an action is triggered it is allocated to a worker node within the Stubber Platform to be executed.
Actions are queued in sequence for a particular stub. This means if two actions are triggered immediately after each other, the first action will complete execution before the system starts to execute the second action.
The Stubber Platform ensures in-order execution of actions to prevent race conditions and allow deterministic flow through the states. (There is a action_meta property that can be set to allow out of order execution of actions, but this is not the default behavior, it's called bulk_random_order and is used for bulk actions). There are special cases where this is not desired and can be switched off by setting the action to a "bulk action".

Example : Triggers

• A webhook calls into Stubber and triggers an action called capture_sales_lead on a stub with stubref 2025-01-01-STUB-ABCD.
• 100ms later a Whatsapp message gets routed to the same stub which by default runs the feedback action _update_from_whatsapp.

Execution

• The first capture_sales_lead action starts to execute and the _update_from_whatsapp is queued
• After all the tasks have been run, notifications queued the capture_sales_lead action completes
• Then the _update_from_whatsapp action starts to execute.

# 2. Running Tasks

When the node starts executing an action the first execution step is to run the tasks in order sequentially.
The action's tasks will run one after the other by following the __order property in the task object.
The task's conditions array is evaluated and each entry is evaluated as a JSONata expresssion.
If all the items in the conditions array pass the task is run.
The type of task to run is specified in the tasktype property.
The result of the task is stored into the stubpost.tasks property along with any return data from the task.
Once all tasks are complete the action execution moves to the notifications part.

# 3. Sending Notifications

After all tasks have run, the notifications are queued.
It's important to note that notifications are done "out of band", which means they are queued to the various notification platforms.
The results of notifications are not readable by an action, the notifications are sent of in a "fire and forget" method.
This frees up the system from all the complexity of sending notifications and allows the action to execute quickly.
Notification handlers are specific to each platform and will read the notifications that are queue and send out the notifications, they usually run special actions called event actions to allow status of the notifications to feed back into the stub.

# 4. Recording Metrics

The last part of action execution is to record metrics. This is done once we know the action has completed all the work done, and any metric are supposed to record data for analytical data, give that the action executed successfully.

# 5. Saving the Stubpost

Once all the tasks have been run, notifications sent and metrics recorded, the system will save the result into the stub as a stubpost. The stubpost contains all the results of the task execution and the data that was collected / saved during the execution of the action.

# Practical Tips

# Finding the Action

When you need something to happen in Stubber the first thing you need to do is find the action that will be triggered.
It might be that a message is being received on a stub, then you need to look for the feedback action that is triggered when a message is received.
If you want something to happen when a stub is created you will likewise look for a lifecycle action like the _create action.
Sometimes the action is just a standard stub action and you can implement the action directly on the flow.