TemporalEx.WorkflowHandle (temporal_ex v0.2.1)

A handle to a running or completed workflow execution.

Carries the client reference, workflow ID, run ID, and namespace so that callers never need to pass the client or IDs again after obtaining a handle from TemporalEx.start_workflow/4 or TemporalEx.get_workflow_handle/3.

Summary

Types

t()

Functions

cancel(handle, opts \\ [])

Requests cancellation of the workflow execution.

delete(handle, opts \\ [])

Deletes the workflow execution from visibility.

describe(handle, opts \\ [])

Describes the workflow execution.

get_history(handle, opts \\ [])

Fetches the workflow execution history.

query(handle, query_type, args \\ [], opts \\ [])

Queries the workflow execution.

reset(handle, opts \\ [])

Resets the workflow execution to a specific point.

result(handle, opts \\ [])

Long-polls for the workflow result by watching for close events in history.

signal(handle, signal_name, args \\ [], opts \\ [])

Sends a signal to the workflow execution.

terminate(handle, opts \\ [])

Terminates the workflow execution.

Types

t()

@type t() :: %TemporalEx.WorkflowHandle{
  client: GenServer.server(),
  first_execution_run_id: String.t() | nil,
  namespace: String.t() | nil,
  run_id: String.t() | nil,
  workflow_id: String.t()
}

Functions

cancel(handle, opts \\ [])

@spec cancel(
  t(),
  keyword()
) :: :ok | {:error, TemporalEx.Error.t()}

Requests cancellation of the workflow execution.

Options

:identity — Caller identity
:request_id — Idempotency key

delete(handle, opts \\ [])

@spec delete(
  t(),
  keyword()
) :: :ok | {:error, TemporalEx.Error.t()}

Deletes the workflow execution from visibility.

describe(handle, opts \\ [])

@spec describe(
  t(),
  keyword()
) :: {:ok, struct()} | {:error, TemporalEx.Error.t()}

Describes the workflow execution.

Returns info including status, start time, close time, type, task queue, etc.

get_history(handle, opts \\ [])

@spec get_history(
  t(),
  keyword()
) :: {:ok, map()} | {:error, TemporalEx.Error.t()}

Fetches the workflow execution history.

Options

:reverse — If true, returns events in reverse chronological order (default: false)
:page_size — Maximum number of events per page (default: 1000)
:next_page_token — Token for pagination
:wait_new_event — If true, long-polls for new events (default: false)
:filter_type — Event filter type atom

query(handle, query_type, args \\ [], opts \\ [])

@spec query(t(), String.t(), list(), keyword()) ::
  {:ok, term()} | {:error, TemporalEx.Error.t()}

Queries the workflow execution.

Options

:reject_condition — When to reject the query (e.g., :not_open, :not_completed_cleanly)

reset(handle, opts \\ [])

@spec reset(
  t(),
  keyword()
) :: {:ok, String.t()} | {:error, TemporalEx.Error.t()}

Resets the workflow execution to a specific point.

Options

:workflow_task_finish_event_id — Event ID to reset to (required)
:reason — Reset reason
:request_id — Idempotency key
:reset_reapply_type — How to reapply signals (default: :RESET_REAPPLY_TYPE_SIGNAL)

result(handle, opts \\ [])

@spec result(
  t(),
  keyword()
) :: {:ok, term()} | {:error, TemporalEx.Error.t() | term()}

Long-polls for the workflow result by watching for close events in history.

Options

:timeout — Maximum time to wait in milliseconds
:follow_runs — If true, follows continue-as-new chains (default: true)

signal(handle, signal_name, args \\ [], opts \\ [])

@spec signal(t(), String.t(), list(), keyword()) ::
  :ok | {:error, TemporalEx.Error.t()}

Sends a signal to the workflow execution.

Options

:identity — Caller identity
:request_id — Idempotency key

terminate(handle, opts \\ [])

@spec terminate(
  t(),
  keyword()
) :: :ok | {:error, TemporalEx.Error.t()}

Terminates the workflow execution.

Options

:reason — Human-readable termination reason
:details — Additional data to record with the termination
:identity — Caller identity