Automations Platform API

The shared Automations platform is the runtime and storage layer for event-driven workflows in BricksMembers. It owns workflow definitions, action definitions, queue orchestration, provider connections, provider adapters, and the migration of older BRM email automations into the shared model.

Primary Boundaries

• Automation core owns workflow persistence, runtime orchestration, queueing, and connection management
• Module trigger/action packs expose triggers and actions only when their modules are active
• Provider adapters own external HTTP calls and provider-specific payload rules
• Emails module remains the owner of template rendering and email transport
• LevelAutomationRuleService remains separate and is not part of the shared workflow engine

Core Services

• AutomationSchemaService — owns shared automation table creation and verification
• AutomationWorkflowService — canonical workflow and action persistence owner
• AutomationQueueService — shared workflow queue ownership, claiming, retries, stale-claim release, and totals
• AutomationRuntimeService — event matching, enqueue rules, and claimed-job execution
• AutomationConnectionService — provider connection CRUD, verification, masking, and target refresh
• AutomationSecretService — encrypted credential serialization/deserialization
• AutomationTriggerRegistryService — curated trigger catalog and trigger lookup
• AutomationActionRegistryService — action definition catalog
• AutomationConditionEvaluator — workflow condition matching
• AutomationContextResolver — normalized runtime context builder
• AutomationJobLogService — redacted provider/job log persistence
• AutomationHttpClient — shared outbound HTTP wrapper with HTTPS and redaction safeguards
• EmailAutomationMigrationService — imports legacy BRM email automations into the shared workflow store and enables cutover
• EmailAutomationCleanupService — post-cutover verification and optional legacy table cleanup

Shared Tables

• brm_automation_workflows
• brm_automation_actions
• brm_automation_jobs
• brm_automation_connections
• brm_automation_job_logs

These tables are separate from the Emails transport queue. Email job delivery still uses brm_email_jobs.

Action-Step Storage Contract

The canonical workflow-step contract now lives on brm_automation_actions. Each action row stores the action identity, order, timing, conditions, and provider-specific config for exactly one upcoming step.

• action_order remains the canonical persisted order
• timing_mode and timing_config_json now belong to the action row and define any delay before that action runs
• conditions_json now belongs to the action row and defines any gating checks that must pass before that action runs
• action_config_json remains the canonical provider-specific payload/config store behind the guided admin UI

The older workflow-level timing_mode, timing_config_json, and conditions_json fields remain compatibility summaries only. They are no longer the canonical source for multi-step delays or step-level gating.

Trigger and Action Registration

The trigger and action catalogs are intentionally modular. Core loads the registry services, but modules register their own trigger or action packs only when active.

• EmailAutomationActionPack
• PaymentsAutomationTriggerPack
• ProgressAutomationTriggerPack
• DripAutomationTriggerPack
• EnrollmentAutomationTriggerPack
• GroupAutomationTriggerPack
• SubmissionAutomationTriggerPack
• QuizAutomationTriggerPack
• CertificateAutomationTriggerPack

Native Analytics Relationship

Native analytics now reuses the semantic trigger catalog and automation context vocabulary, but it does not run through workflow storage, automation connections, or the automation jobs queue.

• Shared with analytics: semantic trigger aliases from AutomationTriggerRegistryService and normalized event context
• Not shared with analytics: workflow matching, queue orchestration, provider connection CRUD, and workflow action execution

This boundary matters because analytics is measurement, not automation. Do not route analytics events through AutomationRuntimeService or automation jobs just because both systems now speak the same event language.

Provider Adapters

External HTTP integration stays behind provider adapters under src/Integrations/Automations/. That keeps the admin layer and module packs free of transport logic.

• MailchimpProviderAdapter
• MailerLiteProviderAdapter
• KitProviderAdapter
• OutboundWebhookProviderAdapter

Current Provider Action Families

The shared workflow catalog now includes first-party provider actions for the currently supported automation connections. These action definitions are registered centrally and then configured from the Builder tab after a compatible connection has been saved.

• mailchimp_upsert_member
• mailchimp_update_member_tags
• mailerlite_upsert_subscriber
• mailerlite_add_groups
• mailerlite_remove_groups
• kit_upsert_subscriber
• kit_add_tags
• kit_remove_tags
• outbound_webhook_send

Admin Surface

• AutomationsPage — canonical route shell for Workflows, Connections, Builder, Jobs, and the conditional Email Upgrade tab

Admin pages validate and delegate only. They do not own workflow writes, queue writes, provider writes, or HTTP transport.

The visible tabs on the canonical route are Workflows, Connections, Builder, and Jobs. The Email Upgrade tab is conditional and only appears when the Emails module is active and the legacy email automation migration is in a failed state. Healthy installs do not keep a permanent migration tab visible.

The Builder tab is now a visual flow editor. Trigger, timing, condition, and action steps are rendered as node cards in the admin adapter layer, but the save payload still posts directly into AutomationWorkflowActions and AutomationWorkflowService without creating a second storage path.

Normal action setup is also guided from the builder sidebar. The UI exposes fetched provider targets, context-path selectors, and field-mapping controls instead of asking the operator to write raw action JSON for routine cases. The underlying canonical persisted config remains action_config_json.

That same simplification now applies to step conditions and trigger setup. In the normal builder UI, conditions are authored as guided path/operator/value rows on the upcoming action step, with operators such as equals, not_equals, in, not_in, exists, and not_exists. Legacy trigger-match compatibility fields remain hidden compatibility data instead of a parallel user-facing setup path.

Sidebar help in the visual builder uses the shared BRM tooltip runtime. Dynamic builder panels emit standard help-text nodes and then rebind them into compact eye-icon tooltips after each sidebar render, so the admin adapter stays consistent with the shared help system instead of inventing a second tooltip implementation.

Security Rules

• all admin and AJAX entry points require manage_options plus nonce validation
• provider credentials are encrypted before persistence
• shared logs store only redacted payloads and responses
• the shared HTTP client rejects unsafe URLs and enforces HTTPS outside development
• provider-specific secrets never appear in localized admin JS or log views

Migration Contract

Older email automations are migrated from the legacy email automation store into the shared workflow tables. The migration is resumable and idempotent. Cutover only happens after verification succeeds, and cleanup is handled separately.

During and after migration, the Emails module still owns templates and transport. Only the storage and runtime orchestration for event-based email automations moves into the shared platform.

Extension Points

• brm_register_automation_triggers
• brm_register_automation_actions
• brm_automation_context
• brm_automation_webhook_payload

Cross-Reference

• docs/feature-maps/automations.md
• docs/ui/automations-admin.md
• docs/dev-posts/24-emails-api.html