Execution Execution protocol schemas
Automation Execution Protocol
Defines schemas for execution logging, error tracking, checkpointing,
concurrency control, and scheduled execution persistence.
Industry alignment: Salesforce Flow Interviews, Temporal Workflow History,
AWS Step Functions execution logs.
Source: packages/spec/src/automation/execution.zod.ts
import { CheckpointSchema, ConcurrencyPolicySchema, ExecutionErrorSchema, ExecutionErrorSeverity, ExecutionLogSchema, ExecutionStatus, ExecutionStepLogSchema, ExecutionStepMetricsSchema, ExecutionStepSkipReasonSchema, FlowRunGateSummarySchema, FlowRunNodeSummarySchema, FlowRunSummarySchema, ScheduleStateSchema } from '@objectstack/spec/automation' ; import type { Checkpoint, ConcurrencyPolicy, ExecutionError, ExecutionErrorSeverity, ExecutionLog, ExecutionStatus, ExecutionStepLog, ExecutionStepMetrics, ExecutionStepSkipReason, FlowRunGateSummary, FlowRunNodeSummary, FlowRunSummary, ScheduleState } from '@objectstack/spec/automation' ; // Validate data const result = CheckpointSchema. parse (data); Property Type Required Description id string✅ Checkpoint ID executionId string✅ Parent execution ID flowName string✅ Flow machine name currentNodeId string✅ Node ID where execution is paused variables Record<string, any>✅ Flow variable state at checkpoint completedNodeIds string[]✅ List of node IDs already executed createdAt string✅ Checkpoint creation timestamp expiresAt stringoptional Checkpoint expiration (auto-cleanup) reason Enum<'wait' | 'screen_input' | 'approval' | 'error' | 'manual_pause' | 'parallel_join' | 'boundary_event'>✅ Why the execution was checkpointed
Property Type Required Description maxConcurrent integer✅ Maximum number of concurrent executions allowed onConflict Enum<'queue' | 'reject' | 'cancel_existing'>✅ queue = enqueue for later, reject = fail immediately, cancel_existing = stop running instance lockScope Enum<'global' | 'per_record' | 'per_user'>✅ Scope of the concurrency lock queueTimeoutMs integeroptional Maximum time to wait in queue before timing out (ms)
Property Type Required Description id string✅ Error record ID executionId string✅ Parent execution ID nodeId stringoptional Node where the error occurred severity Enum<'warning' | 'error' | 'critical'>✅ Error severity level code string✅ Machine-readable error code message string✅ Human-readable error message stack stringoptional Stack trace for debugging context Record<string, any>optional Additional diagnostic context (input data, config snapshot) timestamp string✅ When the error occurred retryable boolean✅ Whether this error can be retried resolvedAt stringoptional When the error was resolved (e.g., after successful retry)
Property Type Required Description id string✅ Execution instance ID flowName string✅ Machine name of the executed flow flowVersion integeroptional Version of the flow that was executed status Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'retrying'>✅ Current execution status trigger { type: string; recordId?: string; object?: string; userId?: string; … }✅ What triggered this execution steps { nodeId: string; nodeType: string; nodeLabel?: string; status: Enum<'success' | 'failure' | 'skipped'>; … }[]✅ Ordered list of executed steps summary { selected: integer; acted: integer; skipped: integer; unmeasured?: integer; … }optional Per-run rollup: records selected / acted on, gate skips, per-node status variables Record<string, any>optional Final state of flow variables startedAt string✅ Execution start timestamp completedAt stringoptional Execution completion timestamp durationMs integeroptional Total execution duration in milliseconds runAs Enum<'system' | 'user'>optional Execution context identity tenantId stringoptional Tenant ID for multi-tenant isolation
pendingrunningpausedcompletedfailedcancelledtimed_outretrying
Property Type Required Description nodeId string✅ Node ID that was executed nodeType string✅ Node action type (e.g., "decision", "http") nodeLabel stringoptional Human-readable node label status Enum<'success' | 'failure' | 'skipped'>✅ Step execution result startedAt string✅ When the step started completedAt stringoptional When the step completed durationMs integeroptional Step execution duration in milliseconds input Record<string, any>optional Input data passed to the node output Record<string, any>optional Output data produced by the node error { code: string; message: string; stack?: string }optional Error details if step failed retryAttempt integeroptional Retry attempt number (0 = first try) parentNodeId stringoptional Enclosing structured-region container node ID (loop/parallel/try_catch) iteration integeroptional Zero-based loop iteration or parallel branch index of the enclosing region regionKind stringoptional Region kind the step ran in: loop-body | parallel-branch | try | catch metrics { selected?: integer; acted?: integer; unmeasuredEffect?: boolean }optional Records this step selected / acted on, as reported by the node executor skippedBy { nodeId: string; edgeId?: string; label?: string }optional The gate that closed, when status is skipped
Property Type Required Description selected integeroptional Records this node READ or matched (a get_record query, a lookup) acted integeroptional Records this node WROTE (created / updated / deleted) or effects it dispatched (notifications delivered) unmeasuredEffect booleanoptional This execution may have caused an effect the platform cannot count (an external write through a connector). NOT interchangeable with acted: 0 — it says the count is unknown, not that it is zero.
Property Type Required Description nodeId string✅ Node whose out-edge did not open (the gate) edgeId stringoptional Edge whose condition evaluated false label stringoptional Edge label, when the flow names its branches
Property Type Required Description nodeId string✅ Node whose out-edge did not open (the gate) targetNodeId string✅ Node the closed edge would have run edgeId stringoptional Edge whose condition evaluated false label stringoptional Edge label, when the flow names its branches skipped integer✅ Times this gate evaluated false (once per loop iteration)
Property Type Required Description nodeId string✅ Node ID nodeType string✅ Node action type (e.g., "get_record", "decision") nodeLabel stringoptional Human-readable node label status Enum<'success' | 'failure' | 'skipped'>✅ Terminal status of the node across the run — failure if any execution failed, else success if any succeeded, else skipped runs integer✅ Times the node executed (loop iterations and parallel branches each count) failures integer✅ Executions that failed skipped integer✅ Times a closed gate kept this node from running at all selected integeroptional Records read across every execution — omitted for a node that reads none acted integeroptional Records written / effects dispatched across every execution — omitted for a node that writes none unmeasured integeroptional Executions that may have caused an effect the platform cannot count (see ExecutionStepMetrics.unmeasuredEffect)
Property Type Required Description selected integer✅ Total records read by the run acted integer✅ Total records written / effects dispatched by the run skipped integer✅ Total node executions a closed gate prevented unmeasured integeroptional Total executions that may have caused an effect the platform cannot count. Absent = not tracked (an older run), which is not the same as zero. nodes { nodeId: string; nodeType: string; nodeLabel?: string; status: Enum<'success' | 'failure' | 'skipped'>; … }[]✅ Per-node breakdown, in first-execution order gates { nodeId: string; targetNodeId: string; edgeId?: string; label?: string; … }[]✅ Gates that closed during the run, most-skipped first detailOmitted booleanoptional Set when persistence dropped nodes/gates to keep the stored row bounded — the totals are still exact. Declared so empty arrays are never mistaken for "nothing ran".
Property Type Required Description id string✅ Schedule instance ID flowName string✅ Flow machine name cronExpression string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }✅ Cron expression — cron0 9 * * MON-FRI timezone stringoptional IANA timezone for cron evaluation status Enum<'active' | 'paused' | 'disabled' | 'expired'>optional Current schedule status nextRunAt stringoptional Next scheduled execution timestamp lastRunAt stringoptional Last execution timestamp lastExecutionId stringoptional Execution ID of the last run lastRunStatus Enum<'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled' | 'timed_out' | 'retrying'>optional Status of the last run totalRuns integeroptional Total number of executions consecutiveFailures integeroptional Consecutive failed executions startDate stringoptional Schedule effective start date endDate stringoptional Schedule expiration date maxRuns integeroptional Maximum total executions before auto-disable createdAt string✅ Schedule creation timestamp updatedAt stringoptional Last update timestamp createdBy stringoptional User who created the schedule
ObjectStack