Class Trigger

The entry point for every workflow graph. Each graph must have exactly one trigger activity, which executes when the graph's subscribes topic receives a message (via hotMesh.pub or hotMesh.pubsub).

The trigger initializes the job, sets its unique ID and key, binds the incoming payload as the trigger's output data, and transitions to adjacent activities defined in the transitions section.

YAML Configuration

app:
  id: myapp
  version: '1'
  graphs:
    - subscribes: order.placed       # the trigger fires when this topic receives a message
      publishes: order.processed     # emitted when the graph completes
      expire: 120

      activities:
        t1:
          type: trigger
          entity: '{$self.input.data.entityType}'
          job:
            maps:
              myField: '{$self.output.data.inputField}'
          stats:
            id: '{$self.input.data.workflowId}'
            key: '{$self.input.data.parentId}'
            parent: '{$self.input.data.originJobId}'
            adjacent: '{$self.input.data.parentJobId}'

        process:
          type: worker
          topic: order.process

      transitions:
        t1:
          - to: process

Key Behaviors

Job ID Resolution: If stats.id is provided, it resolves via @pipe expressions against the input data. Otherwise a UUID is generated.
Duplicate Detection: If a job with the same ID already exists, a DuplicateJobError is thrown (unless it's a crash-recovery scenario).
Pending Mode: When invoked with { pending: <seconds> }, the trigger creates the job but does not transition to children until resumed.
Crash Recovery: Uses a 3-step inception protocol with GUID ledger to ensure atomic job creation survives process crashes.

See

TriggerActivity for the TypeScript interface

Hierarchy (view full)

Activity
- Trigger

Index

Constructors

constructor

Properties

adjacencyList adjacentIndex code config context data engine guidLedger hook leg logger metadata status

Constructors

constructor

new Trigger(config, data, metadata, hook, engine, context?): Trigger
Parameters
- config: ActivityType
- data: ActivityData
- metadata: ActivityMetadata
- hook: ActivityData
- engine: EngineService
- Optionalcontext: JobState
Returns Trigger
Overrides Activity.constructor
- Defined in services/activities/trigger.ts:87

Properties

adjacencyList

adjacencyList: StreamData[]

adjacentIndex

adjacentIndex: number = 0

code

code: number = 200

config

config: TriggerActivity

context

context: JobState

data

data: ActivityData

engine

engine: EngineService

guidLedger

guidLedger: number = 0

hook

hook: ActivityData

leg

leg: ActivityLeg

logger

logger: ILogger

metadata

metadata: ActivityMetadata

status

status: StreamStatus = StreamStatus.SUCCESS

Methods

assertGenerationalId

assertGenerationalId(jobGID, msgGID?): void
if the job is created/deleted/created with the same key, the 'gid' ensures no stale messages (such as sleep delays) enter the workstream. Any message with a mismatched gid belongs to a prior job and can safely be ignored/dropped.
Parameters
- jobGID: string
- OptionalmsgGID: string
Returns void
Inherited from Activity.assertGenerationalId
- Defined in services/activities/activity.ts:858

authorizeEntry

authorizeEntry(_state): string[]
Parameters
- _state: StringAnyType
Returns string[]
Inherited from Activity.authorizeEntry
- Defined in services/activities/activity.ts:692

bindActivityData

bindActivityData(type): void
Parameters
- type: "hook" | "output"
Returns void
Inherited from Activity.bindActivityData
- Defined in services/activities/activity.ts:911

bindActivityError

bindActivityError(data): void
Any StreamMessage with a status of ERROR is bound to the activity
Parameters
- data: Record<string, unknown>
Returns void
Inherited from Activity.bindActivityError
- Defined in services/activities/activity.ts:650

bindActivityMetadata

bindActivityMetadata(): void
Returns void
Inherited from Activity.bindActivityMetadata
- Defined in services/activities/activity.ts:737

bindActivityMetadataPaths

bindActivityMetadataPaths(): string[]
Returns string[]
Overrides Activity.bindActivityMetadataPaths
- Defined in services/activities/trigger.ts:378

bindActivityState

bindActivityState(state): void
Parameters
- state: StringAnyType
Returns void
Inherited from Activity.bindActivityState
- Defined in services/activities/activity.ts:775

bindDimensionalAddress

bindDimensionalAddress(state): void
Parameters
- state: StringAnyType
Returns void
Inherited from Activity.bindDimensionalAddress
- Defined in services/activities/activity.ts:698

bindJobError

bindJobError(data): void
unhandled activity errors (activities that return an ERROR StreamMessage status and have no adjacent children to transition to) are bound to the job
Parameters
- data: Record<string, unknown>
Returns void
Inherited from Activity.bindJobError
- Defined in services/activities/activity.ts:661

bindJobMetadata

bindJobMetadata(): void
Returns void
Inherited from Activity.bindJobMetadata
- Defined in services/activities/activity.ts:732

bindJobMetadataPaths

bindJobMetadataPaths(): string[]
Returns string[]
Overrides Activity.bindJobMetadataPaths
- Defined in services/activities/trigger.ts:374

bindJobState

bindJobState(state): Promise<void>
Parameters
- state: StringAnyType
Returns Promise<void>
Inherited from Activity.bindJobState
- Defined in services/activities/activity.ts:755

bindMarkerData

bindMarkerData(options?): void
Parameters
- Optionaloptions: ExtensionType
Returns void
- Defined in services/activities/trigger.ts:269

bindSearchData

bindSearchData(options?): void
Parameters
- Optionaloptions: ExtensionType
Returns void
- Defined in services/activities/trigger.ts:261

createInputContext

createInputContext(): Partial<JobState>
Returns Partial<JobState>
- Defined in services/activities/trigger.ts:305

execAdjacentParent

execAdjacentParent(): Promise<void>
if the parent (spawner) chose not to await, emit the job_id as the data payload { job_id }

Returns Promise<void>
- Defined in services/activities/trigger.ts:287

executeLeg1StepProtocol

executeLeg1StepProtocol(delta): Promise<boolean>
Executes the 3-step Leg1 protocol for Category B activities (Leg1-only with children, e.g., Hook passthrough, Signal, Interrupt-another). Uses the incoming Leg1 message GUID as the GUID ledger key.

Step A: setState + notarizeLeg1Completion + step1 markers (transaction 1) Step B: publish children + step2 markers + setStatusAndCollateGuid (transaction 2) Step C: if edge → runJobCompletionTasks + step3 markers + finalize (transaction 3)
Parameters
- delta: number
Returns Promise<boolean>
true if this transition caused the job to complete
Inherited from Activity.executeLeg1StepProtocol
- Defined in services/activities/activity.ts:514

executeStepProtocol

executeStepProtocol(delta, shouldFinalize): Promise<boolean>
Executes the 3-step Leg2 protocol using GUID ledger for crash-safe resume. Each step bundles durable writes with its concluding digit update in a single transaction.
Parameters
- delta: number
- shouldFinalize: boolean
Returns Promise<boolean>
true if this transition caused the job to complete
Inherited from Activity.executeStepProtocol
- Defined in services/activities/activity.ts:332

filterAdjacent

filterAdjacent(): Promise<StreamData[]>
Returns Promise<StreamData[]>
Inherited from Activity.filterAdjacent
- Defined in services/activities/activity.ts:929

getJobStatus

getJobStatus(): number
Returns number
Overrides Activity.getJobStatus
- Defined in services/activities/trigger.ts:388

getState

getState(): Promise<void>
Returns Promise<void>
Overrides Activity.getState
- Defined in services/activities/trigger.ts:318

getTriggerConfig

getTriggerConfig(): Promise<ActivityType>
Returns Promise<ActivityType>
Inherited from Activity.getTriggerConfig
- Defined in services/activities/activity.ts:668

initDimensionalAddress

initDimensionalAddress(dad): void
Parameters
- dad: string
Returns void
Inherited from Activity.initDimensionalAddress
- Defined in services/activities/activity.ts:870

initPolicies

initPolicies(context): void
Parameters
- context: JobState
Returns void
Inherited from Activity.initPolicies
- Defined in services/activities/activity.ts:899

initSelf

initSelf(context): JobState
Parameters
- context: StringAnyType
Returns JobState
Inherited from Activity.initSelf
- Defined in services/activities/activity.ts:874

initStatus

initStatus(options?, count): number
pending flows will not transition from the trigger to adjacent children until resumed
Parameters
- options: ExtensionType = {}
- count: number
Returns number
- Defined in services/activities/trigger.ts:246

isJobComplete

isJobComplete(jobStatus): boolean
Parameters
- jobStatus: number
Returns boolean
Inherited from Activity.isJobComplete
- Defined in services/activities/activity.ts:961

jobWasInterrupted

jobWasInterrupted(jobStatus): boolean
A job with a vale < -100_000_000 is considered interrupted, as the interruption event decrements the job status by 1billion.
Parameters
- jobStatus: number
Returns boolean
Inherited from Activity.jobWasInterrupted
- Defined in services/activities/activity.ts:988

mapInputData

mapInputData(): void
Returns void
Inherited from Activity.mapInputData
- Defined in services/activities/activity.ts:619

mapJobData

mapJobData(): void
Returns void
Inherited from Activity.mapJobData
- Defined in services/activities/activity.ts:586

mapOutputData

mapOutputData(): void
Returns void
Inherited from Activity.mapOutputData
- Defined in services/activities/activity.ts:629

mapStatusThreshold

mapStatusThreshold(): number
A job is assumed to be complete when its status (a semaphore) reaches 0. A different threshold can be set in the activity YAML, in support of Dynamic Activation Control.

Returns number
Inherited from Activity.mapStatusThreshold
- Defined in services/activities/activity.ts:150

process

process(options?): Promise<string>
Parameters
- Optionaloptions: ExtensionType
Returns Promise<string>
- Defined in services/activities/trigger.ts:98

processEvent

processEvent(status?, code?, type?): Promise<void>
Parameters
- status: StreamStatus = StreamStatus.SUCCESS
- code: number = 200
- type: "hook" | "output" = 'output'
Returns Promise<void>
Inherited from Activity.processEvent
- Defined in services/activities/activity.ts:217

registerTimeout

registerTimeout(): Promise<void>
Returns Promise<void>
Inherited from Activity.registerTimeout
- Defined in services/activities/activity.ts:643

resolveAdjacentDad

resolveAdjacentDad(): string
Returns string
Inherited from Activity.resolveAdjacentDad
- Defined in services/activities/activity.ts:924

resolveDad

resolveDad(): string
Returns string
Inherited from Activity.resolveDad
- Defined in services/activities/activity.ts:915

resolveGranularity

resolveGranularity(): string
Returns string
- Defined in services/activities/trigger.ts:382

resolveJobId

resolveJobId(context): string
Parameters
- context: Partial<JobState>
Returns string
- Defined in services/activities/trigger.ts:392

resolveJobKey

resolveJobKey(context): string
Parameters
- context: Partial<JobState>
Returns string
- Defined in services/activities/trigger.ts:397

resolveStatus

resolveStatus(multiResponse): number
Extracts the job status from the last result of a transaction. Used by subclass Leg1 process methods for telemetry.
Parameters
- multiResponse: TransactionResultList
Returns number
Inherited from Activity.resolveStatus
- Defined in services/activities/activity.ts:433

resolveThresholdHit

resolveThresholdHit(results): boolean
Extracts the thresholdHit value from transaction results. The setStatusAndCollateGuid result is the last item.
Parameters
- results: TransactionResultList
Returns boolean
Inherited from Activity.resolveThresholdHit
- Defined in services/activities/activity.ts:423

safeKey

safeKey(key): string
Parameters
- key: string
Returns string
- Defined in services/activities/trigger.ts:257

setExpired

setExpired(seconds, transaction): Promise<void>
Parameters
- seconds: number
- transaction: ProviderTransaction
Returns Promise<void>
- Defined in services/activities/trigger.ts:253

setLeg

setLeg(leg): void
Parameters
- leg: ActivityLeg
Returns void
Inherited from Activity.setLeg
- Defined in services/activities/activity.ts:141

setState

setState(transaction?): Promise<string>
Parameters
- Optionaltransaction: ProviderTransaction
Returns Promise<string>
Inherited from Activity.setState
- Defined in services/activities/activity.ts:703

setStats

setStats(transaction?): Promise<void>
Parameters
- Optionaltransaction: ProviderTransaction
Returns Promise<void>
- Defined in services/activities/trigger.ts:402

setStatus

setStatus(amount): Promise<void>
Parameters
- amount: number
Returns Promise<void>
Overrides Activity.setStatus
- Defined in services/activities/trigger.ts:279

shouldEmit

shouldEmit(): boolean
Returns boolean
Inherited from Activity.shouldEmit
- Defined in services/activities/activity.ts:965

verifyEntry

verifyEntry(): Promise<void>
Upon entering leg 1 of a duplexed activity

Returns Promise<void>
Inherited from Activity.verifyEntry
- Defined in services/activities/activity.ts:163

verifyLeg1Entry

verifyLeg1Entry(): Promise<boolean>
Leg1 entry verification for Category B activities (Leg1-only with children). Returns true if this is a resume (Leg1 already completed on a prior attempt). On resume, loads the GUID ledger for step-level resume decisions.

Returns Promise<boolean>
Inherited from Activity.verifyLeg1Entry
- Defined in services/activities/activity.ts:447

verifyReentry

verifyReentry(): Promise<number>
Upon entering leg 2 of a duplexed activity. Increments both the activity ledger (+1) and GUID ledger (+1). Stores the GUID ledger value for step-level resume decisions.

Returns Promise<number>
Inherited from Activity.verifyReentry
- Defined in services/activities/activity.ts:200

Class Trigger

YAML Configuration

Key Behaviors

See

Hierarchy (view full)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Trigger

Properties

adjacencyList

adjacentIndex

code

config

context

data

engine

guidLedger

hook

leg

logger

metadata

status

Methods

assertGenerationalId

Parameters

Returns void

authorizeEntry

Parameters

Returns string[]

bindActivityData

Parameters

Returns void

bindActivityError

Parameters

Returns void

bindActivityMetadata

Returns void

bindActivityMetadataPaths

Returns string[]

bindActivityState

Parameters

Returns void

bindDimensionalAddress

Parameters

Returns void

bindJobError

Parameters

Returns void

bindJobMetadata

Returns void

bindJobMetadataPaths

Returns string[]

bindJobState

Parameters

Returns Promise<void>

bindMarkerData

Parameters

Returns void

bindSearchData

Parameters

Returns void

createInputContext

Returns Partial<JobState>

execAdjacentParent

Returns Promise<void>

executeLeg1StepProtocol

Parameters

Returns Promise<boolean>

executeStepProtocol

Parameters

Returns Promise<boolean>

filterAdjacent

Returns Promise<StreamData[]>

getJobStatus

Returns number