Automation Triggers
What It Is
This chapter is the trigger reference for the Automation Builder.
The Automation Builder, opened from an Automation detail, is the central and only place where an automation defines:
- its trigger resource
- its optional trigger selectors
- its trigger event
- its action content
- its workflow variables
In other words, this is where you define both what starts the automation and what the automation does.
Why It Matters
Jetstack does not use one flat list of trigger names. A trigger is always a combination of:
- a trigger resource class
- zero or more selectors
- an event published by that resource
That structure matters because the same event name can mean different things on different resources, and because selectors let one resource family specialize itself for a concrete context such as:
- a custom object type
- a presenter action
- a concrete module
- a webhook path
Trigger Model
The trigger builder is driven by three contracts exposed by trigger resources:
getResourceIdentification()Provides the builder group and the resource choice shown in the trigger builder.getKnownSelectors()Provides pre-known selector values for that resource where the platform can enumerate them.getPublicEvents()Provides the events that may be selected for that resource, including the trigger parameters exposed to the automation.
At runtime, trigger parameters are available inside the automation through the trigger("code") function.
How Resource Class, Selectors, And Event Work Together
An automation trigger is stored with three main keys:
automationTriggerResourceautomationTriggerSelectorsautomationTriggerEvent
The resource class is always the primary identifier.
This is important:
- for
User, you listen directly on the User resource or the Users manager - you do not listen through
SoopioObject[user] - for a custom type such as
client, you do useSoopioObject[client]orSoopioObjects[client]
The selector only specializes the resource. It does not replace it.
Selector Matching Rules
Selectors are additive and subset-based.
If an automation is configured with selectors, the emitted event must contain all of them. The emitted event may contain more selectors than the automation requires.
This means:
- a trigger without selectors listens to the general resource
- a trigger with selectors listens to a narrower slice of that resource
- the resource class must still match exactly
Two Triggering Modes
Not all trigger definitions are executed the same way.
Auto-driven triggers
These are discovered from active automations and registered into the global hook map. They run automatically when the platform emits the matching system event.
This is the main model for:
- manager CRUD and query lifecycle events
- active-resource field-update events
- presenter lifecycle events
- webhook requests
- activity events
Caller-driven triggers
These are not resolved by the global hook map. Instead, another platform element points directly to the automation and passes the trigger parameters explicitly.
This is the main model for:
- button-invoked automations
- canvas-triggered automations
- automation-to-automation calls
- form event automations
- scheduled-task execution
- view-action automations
In these cases, the trigger definition is still important because it defines the contract of the incoming trigger parameters and keeps the automation understandable in the builder.
Selector Notes
Selectors are only pre-filled when the selected resource can enumerate them.
That means:
- custom object resources can enumerate custom type system names
- presenter resources can enumerate action names
ModulePresentercan enumerate module selectors in addition to action selectors
Some selectors are contextual or free-form and are therefore not fully enumerable in advance. The most important examples are:
- webhook selectors
- data-display runtime selectors
Trigger Resource Families
The following table groups resources by the event set they expose.
| Builder category | Trigger resource identifications | Selectors | Event group | Execution mode | Notes |
|---|---|---|---|---|---|
Resources | App\Model\Automation, App\Model\Canvas, App\Model\EmailTemplate, App\Model\Folder, App\Model\Group, App\Model\LegalGround, App\Model\MediaFile, App\Model\Module, App\Model\Purpose, App\Model\Query, App\Model\Role, App\Model\Root, App\Model\Type, App\Model\User, App\Model\View | none | ActiveResource events | mixed | onUpdateFields, onBeforeActionsBuild, onAfterActionsBuild, and onMentioned are emitted automatically. onButtonClick and onPerformAction are caller-driven patterns. |
Resources | App\Model\SoopioObject | optional custom type selector such as client, project, invoice | ActiveResource events | mixed | This is the resource family for custom implemented object types. It follows the same active-resource event split as the system resources. |
Managers | App\Model\Automations, App\Model\Canvases, App\Model\EmailTemplates, App\Model\Folders, App\Model\Groups, App\Model\LegalGrounds, App\Model\MediaFiles, App\Model\Modules, App\Model\Properties, App\Model\Purposes, App\Model\Queries, App\Model\Roles, App\Model\Roots, App\Model\Types, App\Model\Views | none | Manager events | auto-driven | These resources cover create, list, get, update, delete, and duplication-form lifecycle on system object managers. |
Managers | App\Model\Users | none | Manager events and User-manager extra events | auto-driven | User management adds registration and password-reset related events. |
Managers | App\Model\SoopioObjects | optional custom type selector such as client, project, invoice | Manager events | auto-driven | This is the manager family for custom object types. |
App pages | App\Presenters\PresenterCommons | optional action selector such as actionDefault, actionCreate, actionEdit | Presenter events | auto-driven | This is the generic presenter-wide resource for “any presenter” hooks. |
App pages | Concrete presenters: ActiveResourcePresenter, AiAgentsPresenter, ApiAiPresenter, ApiV1Presenter, ApplicationPresenter, AsyncAutomationPresenter, AutomationsPresenter, BatchPresenter, CanvasesPresenter, CloudConsolePresenter, CodeInspectorPresenter, CustomizationPresenter, DataPresenter, EmailTemplatesPresenter, Error4xxPresenter, ErrorPresenter, FilterListsPresenter, FoldersPresenter, GroupsPresenter, HomepagePresenter, IdentityPresenter, ImplementationSyncPresenter, InstallPresenter, LegalGroundsPresenter, LinkPresenter, LinksPresenter, LocalStoragePresenter, MappingPresenter, MediaFilesPresenter, ModulesPresenter, ObjectPresenter, PermissionsPresenter, PropertiesPresenter, PublicPresenter, PurposesPresenter, QueriesPresenter, RolesPresenter, RootsPresenter, SchedulerPresenter, SearchPresenter, SecretsPresenter, StatusPresenter, TagsPresenter, TranslationsPresenter, TypesPresenter, UploadPresenter, UserPresenter, UsersPresenter, VersionsPresenter, ViewsPresenter | optional action selector from that presenter’s action* methods | Presenter events | auto-driven | Use a concrete presenter when the hook should be limited to one page controller instead of all presenters. |
App pages | App\Presenters\ModulePresenter | optional action selector plus optional module selector such as module_15 | Presenter events | auto-driven | This is the main presenter resource that supports both action specialization and module specialization. |
App pages | App\Presenters\WebhookPresenter | optional webhook selector equal to the request path segment after /webhook/ | Webhook events | auto-driven | The selector is the webhook ID, not an action name. This is the main exception inside presenter-like resources. |
Forms | App\Canvas\BaseForm | none | Form events | caller-driven | Both canvas Form and CustomForm items use this trigger contract. |
Scheduler | App\Model\Scheduler | none | Scheduler events | caller-driven | Triggered by scheduled task execution. |
Extras | App\Automations\CommonEvents | none | Common caller events | caller-driven | Used when another element explicitly calls the automation as a button, canvas, or automation invocation. |
Extras | App\Model\Activities | none | Activity events | auto-driven | Currently focused on type schema lifecycle. |
Extras | App\Model\ViewControl, App\Model\QueryResultControl | no pre-known selectors, but runtime emits selectors such as view=<id> and type=<typeId> | Data-display events | mixed | onDataLoaded is auto-driven when the control loads data. onViewActionAutomationRun is caller-driven from view-action execution. |
Event Groups
Manager Events
These events are provided by the base manager contract and therefore apply to all manager resources unless a more specific manager adds extra events.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onInitialize | app, callerObject |
onDuplicateFormInit | app, originalObject, data |
onBeforeCreate | app, data, isDuplication |
onAfterCreate | app, data, object, isDuplication |
onBeforeList | app, query |
onAfterList | app, query, items, groups |
onBeforeGet | app, id, internalEventData |
onAfterGet | app, id, data, internalEventData |
onBeforeGetMany | app, ids, internalEventData |
onAfterGetMany | app, items, internalEventData |
onBeforeUpdate | app, object, data, changes |
onAfterUpdate | app, object, data, dataFinal, changes |
onBeforeDelete | app, id |
onBeforeDeleteACLPassed | app, id |
onAfterDelete | app, id |
User-Manager Extra Events
These events exist only on the Users manager.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onRegistrationInitiated | app, object |
onRegistrationComplete | app, object |
onPasswordResetInit | app, object |
Active Resource Events
These events are exposed by concrete resources such as User, Module, View, Type, and also by SoopioObject.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onBeforeActionsBuild | app, callerObject, showAll |
onAfterActionsBuild | app, callerObject, showAll |
onUpdateFields | app, callerObject, data, initiator |
onButtonClick | app, callerObject |
onPerformAction | app, callerObject, args |
onMentioned | app, target, referrer, referringProperty, referringCommentId |
Presenter Events
These events are exposed by presenter resources.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onBeforeStartup | app, presenter, action |
onAfterStartup | app, presenter, action |
onBeforeRender | app, presenter, action |
Webhook Events
These events are exposed specifically by WebhookPresenter.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onWebhookReceived | app, method, headers, content, payload |
onWebhookCompleted | app, method, headers, content, payload |
Form Events
These events are exposed by the shared form trigger resource App\Canvas\BaseForm.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onAnchor | app, form, context |
onReload | app, form, values, reloadInitiator, context |
onValidate | app, form, values, context |
onSubmit | app, form, context |
onSuccess | app, form, values, httpData, context |
afterSuccess | app, form, object, context |
onError | app, form, context |
Scheduler Events
These events are exposed by App\Model\Scheduler.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onScheduledTaskRun | app, args |
Common Caller Events
These events are exposed by App\Automations\CommonEvents.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onCalledByButton | app, callerObject, parameters |
onCalledFromAutomation | app, callerObject, parameters |
onCalledFromCanvas | app, callerObject, parameters |
Activity Events
These events are exposed by App\Model\Activities.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onTypeCreated | app, callerObject, data |
onTypeUpdated | app, callerObject, data, dataFinal |
Data-Display Events
These events are exposed by App\Model\ViewControl and App\Model\QueryResultControl.
| Event | Trigger parameters available through trigger("...") |
|---|---|
onDataLoaded | app, callerObject |
onViewActionAutomationRun | app, dataQuery |
How The Most Important Selector Families Work
Custom object selectors
SoopioObject and SoopioObjects use selectors for the custom type system name.
Example:
- resource:
App\Model\SoopioObject - selector:
client - event:
onUpdateFields
This means “listen to the custom object resource, but only for the client type.”
Presenter action selectors
Presenter resources use selectors based on action method names such as actionDefault, actionCreate, or actionEdit.
This lets you scope presenter lifecycle hooks to one action instead of the whole presenter.
Module selectors
ModulePresenter adds module selectors such as module_15.
This means you can narrow hooks both by:
- the module being rendered
- the presenter action
Webhook selectors
WebhookPresenter emits the webhook identifier from the request URL, meaning the selector is the path segment that follows /webhook/.
Example:
- request path:
/webhook/invoice-status - selector:
invoice-status
This is how one automation can listen only to one webhook entry point while another listens to a different one.
Data-display selectors
ViewControl and QueryResultControl emit runtime selectors such as:
view=<view id>type=<type id>
These selectors are emitted by the runtime even though the builder does not pre-fill them as known selectors.
Auto-Driven Versus Caller-Driven In Practice
Auto-driven in the current codebase
- manager events
- active-resource field-update events
- presenter lifecycle events
- webhook events
- activity events
- data-display
onDataLoaded
These are discovered from active automations and registered into the request-level automation hook map.
Caller-driven in the current codebase
- button-triggered automations
- form-triggered automations
- automation-to-automation calls
- canvas-triggered automations
- scheduler-triggered automations
- view-action automations
These need to be configured from the caller side as well. The trigger definition on the automation side describes the intended contract, but the caller must still point to that automation.
Practical Design Guidance
- Use direct resources where the platform has a dedicated resource class, such as
UserorUsers. - Use
SoopioObjectandSoopioObjectsonly for custom tenant object types. - Add selectors when you want a narrower trigger than the whole resource family.
- Treat webhook selectors and data-display selectors as contextual values rather than globally enumerable values.
- When designing caller-driven automations, keep the trigger definition aligned with the caller that will invoke it, so the available
trigger()parameters match reality.