Workflow primitives available from executor-owned workflow processes.
Summary
Functions
Block until a child workflow (started via start_child_workflow/3)
completes. Returns its result tuple — {:ok, value}, {:error, _},
or {:cancelled, _}.
Request cancellation of a child workflow started by this workflow.
Start a child workflow and block until it completes.
Schedule a local activity — runs in-process on this worker rather than via the Temporal task queue, with durability provided by a history marker.
The headers the workflow was started with.
Send a signal to a child workflow that was started by this workflow.
Start a child workflow and return a handle as soon as the child is started by Temporal (does NOT block until completion).
Upserts workflow memo fields.
Functions
Block until a child workflow (started via start_child_workflow/3)
completes. Returns its result tuple — {:ok, value}, {:error, _},
or {:cancelled, _}.
If the child has already completed, returns the cached result immediately. Otherwise blocks the calling thread until the child reaches a terminal state.
Request cancellation of a child workflow started by this workflow.
Accepts either a Temporalex.ChildHandle or a raw workflow id string.
Cancellation is durable and the call blocks until Temporal confirms
the cancel request has been delivered. The child receives the cancel
via its API.cancelled?/0 flag — it's the child's responsibility to
observe and act on it.
Start a child workflow and block until it completes.
workflow may be a module that uses Temporalex.Workflow (its
__workflow_type__/0 is consulted) or a workflow type string.
Options:
:workflow_id(required) — child workflow identifier:task_queue— defaults to the parent's task queue:execution_timeout_ms,:run_timeout_ms,:task_timeout_ms:retry_policy— keyword list, same shape as activity retry policies:parent_close_policy—:terminate(default),:abandon,:request_cancel:workflow_id_reuse_policy—:allow_duplicate(default),:allow_duplicate_failed_only,:reject_duplicate,:terminate_if_running
Returns {:ok, result} on completion, {:error, %Temporalex.Failure.WorkflowExecutionError{...}}
on child failure or start failure, {:cancelled, ...} on cancellation.
Schedule a local activity — runs in-process on this worker rather than via the Temporal task queue, with durability provided by a history marker.
Faster than regular activities for short, deterministic work that doesn't need cross-worker scheduling. The activity body still runs in the activity task supervisor; Temporal Core records a marker so replay is correct.
The headers the workflow was started with.
This is how a workflow reads context a client interceptor injected — trace context, a tenant id, a correlation id. Headers are recorded in history, so reading them is deterministic and safe on replay.
%{"traceparent" => traceparent} = API.headers()Propagating context onward is also safe as long as you copy these values
verbatim onto outbound activity or child-workflow :headers. Deriving a new
value per call — a fresh span id, say — is not: it lands in the command and
differs on replay. See docs/scheduler_and_replay.md.
Continue-as-new drops them
Temporal does not carry a run's headers into its continue-as-new successor,
so this returns %{} from the second run onward unless the chain opts in
with API.continue_as_new!(input, inherit_headers: true) or passes
:headers explicitly. Only start headers are exposed; signal, update, and
query headers are not readable yet.
Send a signal to a child workflow that was started by this workflow.
workflow_id must match the workflow_id you used in
execute_child_workflow/3. The signal is sent durably — the call
blocks until Temporal confirms delivery (or fails).
Returns :ok on successful delivery, {:error, %Temporalex.Failure.ApplicationError{}}
if the target workflow doesn't exist or the signal can't be delivered.
This is a "fire and confirm delivery" primitive: the signal handler in the child runs asynchronously to the parent; success only means Temporal has accepted the signal for delivery.
Start a child workflow and return a handle as soon as the child is started by Temporal (does NOT block until completion).
Use the returned Temporalex.ChildHandle to signal, cancel, or
await_child_workflow/1 for the eventual result.
Returns {:ok, %Temporalex.ChildHandle{}} on successful start, or
{:error, %Temporalex.Failure.WorkflowExecutionError{}} if the start fails.
Upserts workflow memo fields.
Memo is unindexed operator annotation, returned when describing or listing a workflow — use it for context a human reads, not for anything you need to search by. Search attributes are the indexed counterpart, and unlike them memo keys need no namespace registration.
API.upsert_memo(%{"salon_id" => salon_id, "channel" => "marketplace"})Keys are strings; values are converted with the worker's payload codec. Like
upsert_search_attributes/1 this emits a command without waiting for a
result, so it does not yield the caller's scheduler turn.
An empty map is a no-op. The server rejects an empty upsert outright —
BadModifyWorkflowPropertiesAttributes: UpsertedMemo.Fields is not set — and
because that fails the workflow task rather than the workflow, it retries
forever and wedges the execution. Callers that build a memo dynamically
should not have to guard against producing nothing.