Developer Guide: Activities, Triggers & Gateways
saccharine/bpmn separates visual process orchestration from your application's business logic. Rather than embedding PHP code inside XML files, diagrams reference string aliases that resolve to standard Laravel classes, Eloquent traits, and sandboxed routing expressions.
1. Service Tasks & Durable Activities
A Service Task (<bpmn:serviceTask>) executes automated background work on your Laravel queue workers. When an execution token reaches a Service Task, ServiceTaskHandler looks up the node's implementation key (camunda:class) in config/saccharine-bpmn.php and dispatches the corresponding Activity class.
Scaffolding an Activity
Generate a new Activity class and auto-register its alias in config/saccharine-bpmn.php using Artisan:
php artisan bpmn:make-activity VerifyFraudScoreActivity
In durable-workflow/workflow v2, activities extend Workflow\V2\Activity and implement a synchronous handle(array $userData): array method:
namespace App\Workflows\Activities;
use Illuminate\Support\Facades\Http;
use Workflow\V2\Activity;
class VerifyFraudScoreActivity extends Activity
{
/**
* Executes the task on a queue worker.
* Receives the merged node input parameters and current process state ($userData).
* Returns an associative array of mutations to merge back into $userData.
*/
public function handle(array $userData): array
{
$response = Http::post('https://fraud-service.internal/check', [
'email' => $userData['customer_email'],
'amount' => $userData['total'],
]);
return [
'fraud_score' => $response->json('score'),
'fraud_verified_at' => now()->toIso8601String(),
];
}
}
Configuration Registry & Input Merging
Activities are mapped in config/saccharine-bpmn.php:
// config/saccharine-bpmn.php
'activities' => [
'verify_fraud' => \App\Workflows\Activities\VerifyFraudScoreActivity::class,
],
Before invoking handle(), ServiceTaskHandler merges any static <camunda:inputParameter> values compiled from the diagram with the active process $userData (array_merge($inputParameters, $userData)), ensuring runtime payload keys take precedence over static template defaults.
Built-in Notification Activity
The package registers Saccharine\Bpmn\Workflows\Activities\SendNotificationActivity under the key bpmn_send_notification. It supports mail, webhook (HTTP POST), and log channels with {{ key }} mustache interpolation against $userData (including nested dot-notation keys via data_get()).
2. Starting Processes (Model Hooks & Custom Events)
Processes start automatically when ProcessTriggerListener intercepts an event implementing Saccharine\Bpmn\Contracts\BpmnTriggerableEvent whose alias matches an active process version's Message Start Event (<bpmn:startEvent> with <bpmn:messageEventDefinition>).
Option A: Eloquent Model Lifecycle Hooks
Attach the TriggersBpmnProcesses trait to any Eloquent model:
namespace App\Models;
use Illuminate\Database\Eloquent\Model;
use Saccharine\Bpmn\Traits\TriggersBpmnProcesses;
class Order extends Model
{
use TriggersBpmnProcesses;
}
When an Order is created, updated, or deleted, the trait dispatches ModelEventTrigger, which automatically matches Message Start Events configured with {model_snake}_{action} (e.g., order_created, order_updated, order_deleted) or a custom alias mapped in config/saccharine-bpmn.php as App\Models\Order::class . '@created'.
The model's attributes and lifecycle metadata are injected into $userData:
{
"id": 42,
"total": 1500.00,
"_model_class": "App\\Models\\Order",
"_model_id": 42,
"_action": "created",
"_dirty": []
}
Option B: Custom Domain Events
Generate a custom triggerable event class and register its alias:
php artisan bpmn:make-trigger OrderPlacedEvent
Implement getBusinessKey() and getProcessPayload():
namespace App\Events;
use Illuminate\Foundation\Events\Dispatchable;
use Saccharine\Bpmn\Contracts\BpmnTriggerableEvent;
class OrderPlacedEvent implements BpmnTriggerableEvent
{
use Dispatchable;
public function __construct(
public string $orderId,
public float $amount,
public string $customerEmail
) {}
public function getBusinessKey(): string
{
return 'order_placed_' . $this->orderId;
}
public function getProcessPayload(): array
{
return [
'order_id' => $this->orderId,
'amount' => $this->amount,
'customer_email' => $this->customerEmail,
];
}
}
Register the alias in config/saccharine-bpmn.php:
'triggers' => [
'order_placed' => \App\Events\OrderPlacedEvent::class,
],
Database-Enforced Idempotency
ProcessTriggerListener wraps workflow creation inside a database transaction checked against process_triggers_log, which enforces a composite unique index on ['process_version_id', 'business_key']. If the same domain event fires twice for the same business key and process version, duplicate launches are prevented automatically.
3. Gateways & Sandboxed Routing
Exclusive Gateways (XOR)
Exclusive Gateways evaluate <bpmn:conditionExpression> rules on outgoing <bpmn:sequenceFlow> edges using Symfony ExpressionLanguage inside ExpressionEvaluator—avoiding raw PHP eval().
<bpmn:sequenceFlow id="Flow_HighValue" sourceRef="Gateway_VIP" targetRef="Task_ManualReview">
<bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">
total >= 1000 and customer_tier in ['vip', 'enterprise']
</bpmn:conditionExpression>
</bpmn:sequenceFlow>
- Evaluation Order: Outgoing edges with condition expressions are evaluated sequentially; the first branch evaluating to
truewins. - Default Fallback Flows: An outgoing edge without a
conditionExpressionserves as the default route if no conditional branches match. - Safe Error Handling: Invalid expression syntax is caught, logged via
Log::error(), and evaluates tofalsewithout crashing the queue worker. If no conditional branch or default route matches,GatewayRouterthrows aRuntimeExceptionto stall the broken instance visibly.
Parallel Gateways (AND Splits & Joins)
Parallel Gateways (<bpmn:parallelGateway>) execute multiple branches concurrently:
- Fork (Split): When an outgoing gateway has multiple edges,
ParallelGatewayHandlerbuilds an array of deferred closures calling$workflow->makeChildWorkflow(...)for each branch target and passes them toWorkflow\V2\all($parallelTasks). - Synchronize (Join): Each branch runs independently across queue workers until reaching the converging join gateway (
return [null, $userData]). Once all child workflows resolve,ParallelGatewayHandlermerges each branch's returned$userDataarray back into the parent payload and advances past the join gateway.
4. Human-in-the-Loop User Tasks
When an execution token arrives at a <bpmn:userTask>:
UserTaskHandlerdispatchesSaccharine\Bpmn\Events\UserTaskPendingwith theworkflowId, task name, and current$userData.- The Fiber suspends via
$workflow->awaitPromise(...)(or$workflow->awaitWithTimeoutPromise(...)if a Timer Boundary Event is attached), committing the active node toprocess_tokensand releasing the queue worker immediately. - When an operator submits input via the Live Cockpit or
POST /bpmn/processes/instances/{id}/tasks/{elementId}/submit,ProcessInstanceControllercalls$workflow->submitUpdate('submitUserTask', $payload). - The Fiber wakes up, pops the payload from
$pendingUserTaskPayloads, merges the submitted fields into$userData, and advances to the next node.
5. Sub-Processes, Call Activities & Boundary Events
Modular Composition
- Call Activities (
<bpmn:callActivity>): Uses thecalledElementattribute (e.g.,calledElement="order-processing") to look up the activeProcessVersionof anotherProcessDefinitionand invoke it viamakeChildWorkflow(), merging its final$userDataback into the caller. - Inline Sub-Processes (
<bpmn:subProcess>): Groups nested elements scoped byparent_element_id.SubProcessHandlerexecutes the bounded sub-graph viamakeScopedChildWorkflow()starting from the sub-process's internalstartEvent.
Boundary Events & Intermediate Timers
- Error Boundary Events (
<bpmn:errorEventDefinition>): Attached to aserviceTask,callActivity, orsubProcess. When an unhandledThrowableoccurs,EvaluatesBoundaryEvents::handleErrorBoundary()catches the exception, injects_error_caughtwith the exception message into$userData, and routes the token down the boundary edge instead of triggering queue retries. - Timer Boundary Events (
<bpmn:timerEventDefinition>): Attached to auserTaskwith an ISO 8601<bpmn:timeDuration>(e.g.,PT24H). If the duration elapses before human input arrives (and the process is not suspended or halted),UserTaskHandlersets_timer_expired = truein$userDataand routes along the timer boundary path. - Intermediate Timer Catch Events (
<bpmn:intermediateCatchEvent>): Pauses sequential flow mid-process for an ISO 8601<bpmn:timeDuration>(e.g.,PT30MorP2D) via$workflow->timerPromise($duration)without holding a queue worker thread.