Class Hook

A versatile pause/resume activity that supports three distinct patterns: time hook (sleep), web hook (external signal), and passthrough (immediate transition with optional data mapping).

The hook activity is the most flexible activity type. Depending on its YAML configuration, it operates in one of the following modes:

Time Hook (Sleep)

Pauses the flow for a specified duration in seconds. The sleep value can be a literal number or a @pipe expression for dynamic delays (e.g., exponential backoff).

app:
  id: myapp
  version: '1'
  graphs:
    - subscribes: job.start
      expire: 300

      activities:
        t1:
          type: trigger

        delay:
          type: hook
          sleep: 60                        # pause for 60 seconds
          job:
            maps:
              paused_at: '{$self.output.metadata.ac}'

        resume:
          type: hook

      transitions:
        t1:
          - to: delay
        delay:
          - to: resume

Web Hook (External Signal)

Registers a webhook listener on a named topic. The flow pauses until an external signal is sent to the hook's topic. The signal data becomes available as $self.hook.data. The hooks section at the graph level routes incoming signals to the waiting activity.

app:
  id: myapp
  version: '1'
  graphs:
    - subscribes: order.placed
      expire: 3600

      activities:
        t1:
          type: trigger

        wait_for_approval:
          type: hook
          hook:
            type: object
            properties:
              approved: { type: boolean }
          job:
            maps:
              approved: '{$self.hook.data.approved}'

        done:
          type: hook

      transitions:
        t1:
          - to: wait_for_approval
        wait_for_approval:
          - to: done

      hooks:
        order.approval:                    # external topic that delivers the signal
          - to: wait_for_approval
            conditions:
              match:
                - expected: '{t1.output.data.id}'
                  actual: '{$self.hook.data.id}'

Passthrough (No Hook)

When neither sleep nor hook is configured, the hook activity acts as a passthrough: it maps data and immediately transitions to children. This is useful for data transformation, convergence points, or as a cycle pivot (with cycle: true).

app:
  id: myapp
  version: '1'
  graphs:
    - subscribes: job.start

      activities:
        t1:
          type: trigger

        pivot:
          type: hook
          cycle: true                      # enables re-entry from a cycle activity
          output:
            maps:
              retryCount: 0
          job:
            maps:
              counter: '{$self.output.data.retryCount}'

        do_work:
          type: worker
          topic: work.do

      transitions:
        t1:
          - to: pivot
        pivot:
          - to: do_work

Execution Model

  • With sleep or hook: Category A (duplex). Leg 1 registers the hook and saves state. Leg 2 fires when the timer expires or the external signal arrives (via processTimeHookEvent or processWebHookEvent).
  • Without sleep or hook: Category B (passthrough). Uses the crash-safe executeLeg1StepProtocol to map data and transition to adjacent activities.

See

HookActivity for the TypeScript interface

Hierarchy (view full)

Constructors

constructor

Properties

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

Methods

assertGenerationalId authorizeEntry bindActivityData bindActivityError bindActivityMetadata bindActivityMetadataPaths bindActivityState bindDimensionalAddress bindJobError bindJobMetadata bindJobMetadataPaths bindJobState doesHook doHook doPassThrough executeLeg1StepProtocol executeStepProtocol filterAdjacent getHookRule getJobStatus getState getTriggerConfig initDimensionalAddress initPolicies initSelf isConfiguredAsHook isJobComplete jobWasInterrupted mapInputData mapJobData mapOutputData mapStatusThreshold process processEvent processTimeHookEvent processWebHookEvent registerHook registerTimeout resolveAdjacentDad resolveDad resolveStatus resolveThresholdHit setLeg setState setStatus shouldEmit verifyEntry verifyLeg1Entry verifyReentry

Constructors

constructor

Properties

adjacencyList

adjacencyList: StreamData[]

adjacentIndex

adjacentIndex: number = 0

code

code: number = 200

config

config: HookActivity

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

authorizeEntry

bindActivityData

bindActivityError

bindActivityMetadata

bindActivityMetadataPaths

bindActivityState

bindDimensionalAddress

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

bindJobMetadata

bindJobMetadataPaths

bindJobState

doesHook

doHook

doPassThrough

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

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

filterAdjacent

getHookRule

getJobStatus

getState

getTriggerConfig

initDimensionalAddress

initPolicies

initSelf

isConfiguredAsHook

  • isConfiguredAsHook(): boolean

  • Static config check: does this activity have a hook or sleep config? Used for routing before context is loaded.

    Returns boolean

isJobComplete

jobWasInterrupted

mapInputData

mapJobData

mapOutputData

mapStatusThreshold

process

processEvent

processTimeHookEvent

processWebHookEvent

registerHook

registerTimeout

resolveAdjacentDad

resolveDad

resolveStatus

resolveThresholdHit

setLeg

setState

setStatus

shouldEmit

verifyEntry

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>

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>

Settings

Member Visibility

On This Page

Time Hook (Sleep)Web Hook (External Signal)Passthrough (No Hook)Execution Model
Constructors
Properties
Methods