temporal.client.core — io.github.manetu/temporal-sdk 1.6.0

Methods for client interaction with Temporal

>! clj

(>! {:keys [stub] :as workflow} signal-name params)

Sends 'params' as a signal 'signal-name' to 'workflow'

(>! workflow ::my-signal {:msg "Hi"})

cancel clj

(cancel {:keys [stub] :as workflow})

Gracefully cancels 'workflow'

(cancel workflow)

create-client clj

(create-client)

(create-client options)

(create-client options timeout)

Creates a new client instance suitable for implementing Temporal workers (See temporal.client.worker/start) or workflow clients (See create-workflow). The caller is blocked while the connection is verified for up to the specified timeout duration, or 5s if not specified.

Arguments:

• options: Options for configuring the WorkflowClient (See temporal.client.options/workflow-client-options and temporal.client.options/stub-options)
• timeout: Optional connection timeout as a Duration (Default: 5s).

create-client-async clj

(create-client-async)

(create-client-async options)

Creates a new client instance suitable for implementing Temporal workers (See temporal.client.worker/start) or workflow clients (See create-workflow). Will not verify the connection before returning.

Arguments:

• options: Options for configuring the WorkflowClient (See temporal.client.options/workflow-client-options and temporal.client.options/stub-options)

create-workflow clj

(create-workflow client workflow-id)

(create-workflow client workflow options)

Create a new workflow-stub instance, suitable for managing and interacting with a workflow through it's lifecycle.

N.B.: The workflow will remain in an uninitialized and idle state until explicitly started with either (start), (signal-with-start), or (update-with-start).

Arguments:

• client: A workflow client created with create-client
• workflow: The workflow definition (defworkflow)
• options: A map of workflow options:

Option	Description
:task-queue	(required) Task queue for the workflow
:workflow-id	Unique workflow identifier (auto-generated if not provided)
:workflow-id-reuse-policy	Policy for reusing IDs of completed workflows
:workflow-id-conflict-policy	Policy when workflow ID is already running (see below)
:workflow-execution-timeout	Total workflow execution timeout (Duration)
:workflow-run-timeout	Single workflow run timeout (Duration)
:workflow-task-timeout	Workflow task processing timeout (Duration)
:retry-options	Retry configuration map
:cron-schedule	Cron expression for scheduled execution
:memo	Arbitrary metadata map
:search-attributes	Indexed attributes for workflow visibility
:start-delay	Delay before starting the workflow (Duration)

Workflow ID Conflict Policies (:workflow-id-conflict-policy):

Policy	Description
:fail	Fail if workflow is already running (default)
:use-existing	Use the existing running workflow
:terminate-existing	Terminate existing workflow and start new one

(let [w (create-workflow client my-workflow {:task-queue ::my-task-queue})]
  ;; do something with the instance 'w')

get-result clj

(get-result {:keys [stub] :as workflow})

Retrieves the final result of 'workflow'. Returns a promise that when derefed will resolve to the evaluation of the defworkflow once the workflow concludes.

(defworkflow my-workflow
  [ctx args]
  ...)

(let [w (create ...)]
   (start w ...)
   @(get-result w))

get-update-handle clj

(get-update-handle {:keys [stub] :as workflow} update-id)

Retrieves a handle to a previously initiated update request using its unique identifier.

Arguments:

• workflow: workflow instance created with create-workflow
• update-id: the unique ID of the update

Returns a map with:

• :id: the update ID
• :execution: the workflow execution
• :result: a promise that resolves to the update result

(let [handle (get-update-handle workflow "my-update-id")]
  @(:result handle))

query clj

(query {:keys [stub] :as workflow} query-type args)

Sends query with 'query-type' and 'args' to 'workflow', returns a value. The query result is computed by a query-handler, registered inside the workflow definition using temporal.workflow/register-query-handler!.

Arguments:

• query-type: keyword (or coerceable into a keyword)
• args: serializable query params

(query workflow ::my-query {:foo "bar"})

signal-with-start clj

(signal-with-start {:keys [stub] :as workflow}
                   signal-name
                   signal-params
                   wf-params)

Signals 'workflow' with 'signal-params' on signal 'signal-name', starting it if not already running.

Arguments:

• workflow: workflow instance created with create-workflow
• signal-name: keyword (or coerceable) identifying the signal
• signal-params: data to send with the signal
• wf-params: arguments passed to the workflow if it needs to be started

By default, this will fail if the workflow is already running. To signal an existing workflow instead, set :workflow-id-conflict-policy to :use-existing when calling create-workflow:

(let [w (create-workflow client my-workflow {:task-queue task-queue
                                              :workflow-id "my-id"
                                              :workflow-id-conflict-policy :use-existing})]
  (signal-with-start w :my-signal {:data "value"} {:initial "args"}))

start clj

(start {:keys [stub] :as workflow} params)

Starts 'worklow' with 'params'

start-update clj

(start-update workflow update-type args)

(start-update {:keys [stub] :as workflow}
              update-type
              args
              {:keys [wait-for-stage update-id] :as options})

Asynchronously sends an update with 'update-type' and 'args' to 'workflow'. Returns an update handle that can be used to get the result later.

The update is processed by an update-handler, registered inside the workflow definition using temporal.workflow/register-update-handler!.

Arguments:

• workflow: workflow instance created with create-workflow
• update-type: keyword (or coerceable into a keyword) identifying the update type
• args: serializable update params
• options: (optional) map with:
  • :wait-for-stage: one of :admitted, :accepted, or :completed (default: :accepted)
  • :update-id: unique ID for idempotency (auto-generated if not provided)

Returns a map with:

• :id: the update ID
• :execution: the workflow execution
• :result: a promise that resolves to the update result

(let [handle (start-update workflow :increment {:amount 5})]
  ;; Do other work...
  @(:result handle))

terminate clj

(terminate {:keys [stub] :as workflow} reason params)

Forcefully terminates 'workflow'

(terminate workflow "unresponsive", {})

update clj

(update {:keys [stub] :as workflow} update-type args)

Sends an update with 'update-type' and 'args' to 'workflow', returns a value. The update is processed by an update-handler, registered inside the workflow definition using temporal.workflow/register-update-handler!.

Unlike queries, updates can:

• Mutate workflow state
• Perform blocking operations (activities, child workflows, sleep, await)
• Return values to the caller

Arguments:

• workflow: workflow instance created with create-workflow
• update-type: keyword (or coerceable into a keyword) identifying the update type
• args: serializable update params

(update workflow :increment {:amount 5})

update-with-start clj

(update-with-start workflow update-type update-args start-args)

(update-with-start {:keys [stub] :as workflow}
                   update-type
                   update-args
                   start-args
                   options)

Sends an update to a workflow, starting it if not already running. This is useful for ensuring a workflow exists before sending an update.

Arguments:

• workflow: workflow instance created with create-workflow
• update-type: keyword (or coerceable into a keyword) identifying the update type
• update-args: serializable update params
• start-args: arguments to pass if the workflow needs to be started
• options: (optional) map with:
  • :wait-for-stage: one of :admitted, :accepted, or :completed (default: :accepted)
  • :update-id: unique ID for idempotency (auto-generated if not provided)

Returns a map with:

• :id: the update ID
• :execution: the workflow execution
• :result: a promise that resolves to the update result

(let [handle (update-with-start workflow :increment {:amount 5} {:initial-value 0})]
  @(:result handle))