Module: Temporalio::Workflow

Defined in:
lib/temporalio/workflow.rb,
lib/temporalio/workflow/info.rb,
lib/temporalio/workflow/future.rb,
lib/temporalio/workflow/definition.rb,
lib/temporalio/workflow/event_group.rb,
lib/temporalio/workflow/update_info.rb,
lib/temporalio/workflow/nexus_client.rb,
lib/temporalio/workflow/parent_close_policy.rb,
lib/temporalio/workflow/child_workflow_handle.rb,
lib/temporalio/workflow/nexus_operation_handle.rb,
lib/temporalio/workflow/external_workflow_handle.rb,
lib/temporalio/workflow/handler_unfinished_policy.rb,
lib/temporalio/workflow/activity_cancellation_type.rb,
lib/temporalio/workflow/child_workflow_cancellation_type.rb,
lib/temporalio/workflow/nexus_operation_cancellation_type.rb

Overview

Module with all class-methods that can be made from a workflow. Methods on this module cannot be used outside of a workflow with the obvious exception of Workflow.in_workflow?. This module is not meant to be included or mixed in.

Defined Under Namespace

Modules: ActivityCancellationType, ChildWorkflowCancellationType, HandlerUnfinishedPolicy, NexusOperationCancellationType, ParentClosePolicy, Unsafe Classes: ChildWorkflowHandle, ContinueAsNewError, Definition, DefinitionOptions, EventGroup, ExternalWorkflowHandle, Future, Info, InvalidWorkflowStateError, NexusClient, NexusOperationHandle, NondeterminismError, UpdateInfo

Constant Summary collapse

Mutex =

Mutex is a workflow-safe wrapper around Mutex.

As of this writing, all methods on Mutex are safe for workflow use and are implicitly made deterministic by the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of Mutex by non-workflow-safe code. However, users may prefer to use the more powerful wait_condition approach as a mutex (e.g. wait until a certain attribute is set to false then set it to true before continuing).

Unsafe._wrap_ruby_class_as_legal(::Mutex)
Queue =

Queue is a workflow-safe wrapper around Queue.

As of this writing, all methods on Queue are safe for workflow use and are implicitly made deterministic by the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of Queue by non-workflow-safe code. However, users may prefer to use the more powerful wait_condition approach as a queue (e.g. wait until an array is non-empty before continuing).

Unsafe._wrap_ruby_class_as_legal(::Queue)
SizedQueue =

SizedQueue is a workflow-safe wrapper around SizedQueue.

As of this writing, all methods on SizedQueue are safe for workflow use and are implicitly made deterministic by the Fiber scheduler. The primary reason this is wrapped as safe is to be able to catch unintentional uses of SizedQueue by non-workflow-safe code. However, users may prefer to use the more powerful wait_condition approach as a queue (e.g. wait until an array is non-empty before continuing).

Unsafe._wrap_ruby_class_as_legal(::SizedQueue)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#attempt ⇒ Integer

Returns Current workflow attempt.

Returns:

  • (Integer) —

    Current workflow attempt.




# File 'lib/temporalio/workflow/info.rb', line 30

#continued_run_id ⇒ String?

Returns Run ID if this was continued.

Returns:

  • (String, nil) —

    Run ID if this was continued.




# File 'lib/temporalio/workflow/info.rb', line 30

#cron_schedule ⇒ String?

Returns Cron schedule if applicable.

Returns:

  • (String, nil) —

    Cron schedule if applicable.




# File 'lib/temporalio/workflow/info.rb', line 30

#execution_timeout ⇒ Float?

Returns Execution timeout for the workflow.

Returns:

  • (Float, nil) —

    Execution timeout for the workflow.




# File 'lib/temporalio/workflow/info.rb', line 30

#first_execution_run_id ⇒ String

Returns The very first run ID the workflow ever had, following continuation chains.

Returns:

  • (String) —

    The very first run ID the workflow ever had, following continuation chains.




# File 'lib/temporalio/workflow/info.rb', line 30

#has_last_result? ⇒ Boolean

Returns Successful result if this workflow is a continuation of a success.

Returns:

  • (Boolean) —

    Successful result if this workflow is a continuation of a success.




# File 'lib/temporalio/workflow/info.rb', line 30

#headers ⇒ Hash<String, Api::Common::V1::Payload>

Returns Headers.

Returns:




# File 'lib/temporalio/workflow/info.rb', line 30

#last_failure ⇒ Exception?

Returns Failure if this workflow run is a continuation of a failure.

Returns:

  • (Exception, nil) —

    Failure if this workflow run is a continuation of a failure.




# File 'lib/temporalio/workflow/info.rb', line 30

#last_result ⇒ Object?

Returns Successful result if this workflow is a continuation of a success.

Returns:

  • (Object, nil) —

    Successful result if this workflow is a continuation of a success.




# File 'lib/temporalio/workflow/info.rb', line 30

Class Method Details

.all_handlers_finished? ⇒ Boolean

Whether all update and signal handlers have finished executing. Consider waiting on this condition before workflow return or continue-as-new, to prevent interruption of in-progress handlers by workflow return: `Temporalio::Workflow.wait_condition { Temporalio::Workflow.all_handlers_finished? }``

Returns:

  • (Boolean) —

    Whether all update and signal handlers have finished executing. Consider waiting on this condition before workflow return or continue-as-new, to prevent interruption of in-progress handlers by workflow return: `Temporalio::Workflow.wait_condition { Temporalio::Workflow.all_handlers_finished? }``



31
32
33
 
# File 'lib/temporalio/workflow.rb', line 31

def self.all_handlers_finished?
  _current.all_handlers_finished?
end

.cancellation ⇒ Cancellation

Returns Cancellation for the workflow. This is canceled when a workflow cancellation request is received. This is the default cancellation for most workflow calls.

Returns:

  • (Cancellation) —

    Cancellation for the workflow. This is canceled when a workflow cancellation request is received. This is the default cancellation for most workflow calls.



37
38
39
 
# File 'lib/temporalio/workflow.rb', line 37

def self.cancellation
  _current.cancellation
end

.continue_as_new_suggested ⇒ Boolean

Returns Whether continue as new is suggested. This value is the current continue-as-new suggestion up until the current task. Note, this value may not be up to date when accessed in a query. When continue as new is suggested is based on server-side configuration.

Returns:

  • (Boolean) —

    Whether continue as new is suggested. This value is the current continue-as-new suggestion up until the current task. Note, this value may not be up to date when accessed in a query. When continue as new is suggested is based on server-side configuration.



44
45
46
 
# File 'lib/temporalio/workflow.rb', line 44

def self.continue_as_new_suggested
  _current.continue_as_new_suggested
end

.create_event_group(id, label: nil) ⇒ EventGroup

Create an Event Group that can be attached to commands scheduled by this workflow.

Attach the returned group via command event_groups: options, or via with_event_groups.

WARNING: Event Groups support is experimental.

Parameters:

  • id (String) —

    Non-empty group identity. Commands with the same id belong to the same group. The user-provided ID is stored as plain text in the workflow history and should therefore not contain sensitive information.

  • label (String, nil) (defaults to: nil) —

    Optional non-empty display text for the UI / CLI. If provided, it is persisted to history as a codec-encoded Payload.

Returns:

Raises:

  • (ArgumentError) 


71
72
73
74
75
76
77
 
# File 'lib/temporalio/workflow.rb', line 71

def self.create_event_group(id, label: nil)
  _current
  raise ArgumentError, 'Event group id cannot be empty' if !id.is_a?(String) || id.empty?
  raise ArgumentError, 'Event group label cannot be empty' if !label.nil? && (!label.is_a?(String) || label.empty?)

  EventGroup::Label.new(id, label)
end

.create_nexus_client(endpoint:, service:) ⇒ NexusClient

Create a Nexus client for executing operations.

WARNING: Nexus support is experimental.

Parameters:

  • endpoint (Symbol, String) —

    Endpoint name.

  • service (Symbol, String) —

    Service name.

Returns:

  • (NexusClient) —

    Client for executing Nexus operations.



55
56
57
 
# File 'lib/temporalio/workflow.rb', line 55

def self.create_nexus_client(endpoint:, service:)
  _current.create_nexus_client(endpoint:, service:)
end

.current_deployment_version ⇒ WorkerDeploymentVersion?

Get the deployment version of the worker which executed the current Workflow Task.

May be nil if the task was completed by a worker without a deployment version or build id. If this worker is the one executing this task for the first time and has a deployment version set, then its ID will be used. This value may change over the lifetime of the workflow run, but is deterministic and safe to use for branching. This is currently experimental.

Returns:



134
135
136
 
# File 'lib/temporalio/workflow.rb', line 134

def self.current_deployment_version
  _current.current_deployment_version
end

.current_details ⇒ String

Get current details for this workflow that may appear in UI/CLI. Unlike static details set at start, this value can be updated throughout the life of the workflow. This can be in Temporal markdown format and can span multiple lines.

Returns:

  • (String) —

    Current details. Default is empty string.



113
114
115
 
# File 'lib/temporalio/workflow.rb', line 113

def self.current_details
  _current.current_details
end

.current_details=(details) ⇒ Object

Set current details for this workflow that may appear in UI/CLI. Unlike static details set at start, this value can be updated throughout the life of the workflow. This can be in Temporal markdown format and can span multiple lines.

Parameters:

  • details (String) —

    Current details. Can use empty string to unset.



122
123
124
 
# File 'lib/temporalio/workflow.rb', line 122

def self.current_details=(details)
  _current.current_details = details
end

.current_history_length ⇒ Integer

Returns Current number of events in history. This value is the current history event count up until the current task. Note, this value may not be up to date when accessed in a query.

Returns:

  • (Integer) —

    Current number of events in history. This value is the current history event count up until the current task. Note, this value may not be up to date when accessed in a query.



140
141
142
 
# File 'lib/temporalio/workflow.rb', line 140

def self.current_history_length
  _current.current_history_length
end

.current_history_size ⇒ Integer

Returns Current history size in bytes. This value is the current history size up until the current task. Note, this value may not be up to date when accessed in a query.

Returns:

  • (Integer) —

    Current history size in bytes. This value is the current history size up until the current task. Note, this value may not be up to date when accessed in a query.



146
147
148
 
# File 'lib/temporalio/workflow.rb', line 146

def self.current_history_size
  _current.current_history_size
end

.current_update_info ⇒ UpdateInfo

Returns Current update info if this code is running inside an update. This is set via a Fiber-local storage so it is only visible to the current handler fiber.

Returns:

  • (UpdateInfo) —

    Current update info if this code is running inside an update. This is set via a Fiber-local storage so it is only visible to the current handler fiber.



152
153
154
 
# File 'lib/temporalio/workflow.rb', line 152

def self.current_update_info
  _current.current_update_info
end

.deprecate_patch(patch_id, event_groups: nil) ⇒ Object

Mark a patch as deprecated.

This marks a workflow that had patched in a previous version of the code as no longer applicable because all workflows that use the old code path are done and will never be queried again. Therefore the old code path is removed as well.

Parameters:

  • patch_id (Symbol, String) —

    Patch ID.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the patch marker command. WARNING: This option is experimental.



165
166
167
 
# File 'lib/temporalio/workflow.rb', line 165

def self.deprecate_patch(patch_id, event_groups: nil)
  _current.deprecate_patch(patch_id, event_groups:)
end

.execute_activity(activity, *args, task_queue: info.task_queue, summary: nil, schedule_to_close_timeout: nil, schedule_to_start_timeout: nil, start_to_close_timeout: nil, heartbeat_timeout: nil, retry_policy: nil, cancellation: Workflow.cancellation, cancellation_type: ActivityCancellationType::TRY_CANCEL, activity_id: nil, disable_eager_execution: false, priority: Priority.default, arg_hints: nil, result_hint: nil, event_groups: nil) ⇒ Object

Note:

Using an already-canceled cancellation may give a different exception than canceling after started. Use Error.canceled? to check if the exception is a cancellation either way.

Execute an activity and return its result. Either start_to_close_timeout or schedule_to_close_timeout must be set. The heartbeat_timeout should be set for any non-immediately-completing activity so it can receive cancellation. To run an activity in the background, use a Future.

Parameters:

  • activity (Class<Activity::Definition>, Symbol, String) —

    Activity definition class or activity name.

  • args (Array<Object>) —

    Arguments to the activity.

  • task_queue (String) (defaults to: info.task_queue) —

    Task queue to run the activity on. Defaults to the current workflow's task queue.

  • summary (String, nil) (defaults to: nil) —

    Single-line summary for this activity that may appear in CLI/UI. This can be in single-line Temporal markdown format.

  • schedule_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take from first being scheduled to being completed before it times out. This is inclusive of all retries.

  • schedule_to_start_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take to be started from first being scheduled.

  • start_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time a single activity run can take from when it starts to when it completes. This is per retry.

  • heartbeat_timeout (Float, nil) (defaults to: nil) —

    How frequently an activity must invoke heartbeat while running before it is considered timed out. This also affects how heartbeats are throttled, see general heartbeating documentation.

  • retry_policy (RetryPolicy) (defaults to: nil) —

    How an activity is retried on failure. If unset, a server-defined default is used. Set maximum attempts to 1 to disable retries.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation to apply to the activity. How cancellation is treated is based on cancellation_type. This defaults to the workflow's cancellation, but may need to be overridden with a new/detached one if an activity is being run in an ensure after workflow cancellation.

  • cancellation_type (ActivityCancellationType) (defaults to: ActivityCancellationType::TRY_CANCEL) —

    How the activity is treated when it is canceled from the workflow.

  • activity_id (String, nil) (defaults to: nil) —

    Optional unique identifier for the activity. This is an advanced setting that should not be set unless users are sure they need to. Contact Temporal before setting this value.

  • disable_eager_execution (Boolean) (defaults to: false) —

    Whether eager execution is disabled. Eager activity execution is an optimization on some servers that sends activities back to the same worker as the calling workflow if they can run there. If false (the default), eager execution may still be disabled at the worker level or may not be requested due to lack of available slots.

  • priority (Priority) (defaults to: Priority.default) —

    Priority of the activity.

  • arg_hints (Array<Object>, nil) (defaults to: nil) —

    Overrides converter hints for arguments if any. If unset/nil and the activity definition has arg hints, those are used by default.

  • result_hint (Object, nil) (defaults to: nil) —

    Overrides converter hint for result if any. If unset/nil and the activity definition has result hint, it is used by default.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the activity command, in addition to any groups from enclosing with_event_groups scopes. WARNING: This option is experimental.

Returns:

  • (Object) —

    Result of the activity.

Raises:



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/temporalio/workflow.rb', line 215

def self.execute_activity(
  activity,
  *args,
  task_queue: info.task_queue,
  summary: nil,
  schedule_to_close_timeout: nil,
  schedule_to_start_timeout: nil,
  start_to_close_timeout: nil,
  heartbeat_timeout: nil,
  retry_policy: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ActivityCancellationType::TRY_CANCEL,
  activity_id: nil,
  disable_eager_execution: false,
  priority: Priority.default,
  arg_hints: nil,
  result_hint: nil,
  event_groups: nil
)
  _current.execute_activity(
    activity, *args,
    task_queue:, summary:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
    heartbeat_timeout:, retry_policy:, cancellation:, cancellation_type:, activity_id:, disable_eager_execution:,
    priority:, arg_hints:, result_hint:, event_groups:
  )
end

.execute_child_workflow(workflow, *args, id: random.uuid, task_queue: info.task_queue, static_summary: nil, static_details: nil, cancellation: Workflow.cancellation, cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED, parent_close_policy: ParentClosePolicy::TERMINATE, execution_timeout: nil, run_timeout: nil, task_timeout: nil, id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE, retry_policy: nil, cron_schedule: nil, memo: nil, search_attributes: nil, priority: Priority.default, versioning_override: nil, arg_hints: nil, result_hint: nil, event_groups: nil) ⇒ Object

Shortcut for start_child_workflow + Temporalio::Workflow::ChildWorkflowHandle#result. See those two calls for more details.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/temporalio/workflow.rb', line 243

def self.execute_child_workflow(
  workflow,
  *args,
  id: random.uuid,
  task_queue: info.task_queue,
  static_summary: nil,
  static_details: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED,
  parent_close_policy: ParentClosePolicy::TERMINATE,
  execution_timeout: nil,
  run_timeout: nil,
  task_timeout: nil,
  id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE,
  retry_policy: nil,
  cron_schedule: nil,
  memo: nil,
  search_attributes: nil,
  priority: Priority.default,
  versioning_override: nil,
  arg_hints: nil,
  result_hint: nil,
  event_groups: nil
)
  start_child_workflow(
    workflow, *args,
    id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
    parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
    retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, versioning_override:,
    arg_hints:, result_hint:, event_groups:
  ).result
end

.execute_local_activity(activity, *args, summary: nil, schedule_to_close_timeout: nil, schedule_to_start_timeout: nil, start_to_close_timeout: nil, retry_policy: nil, local_retry_threshold: nil, cancellation: Workflow.cancellation, cancellation_type: ActivityCancellationType::TRY_CANCEL, activity_id: nil, arg_hints: nil, result_hint: nil, event_groups: nil) ⇒ Object

Note:

Using an already-canceled cancellation may give a different exception than canceling after started. Use Error.canceled? to check if the exception is a cancellation either way.

Execute an activity locally in this same workflow task and return its result. This should usually only be used for short/simple activities where the result performance matters. Either start_to_close_timeout or schedule_to_close_timeout must be set. To run an activity in the background, use a Future.

Parameters:

  • activity (Class<Activity::Definition>, Symbol, String) —

    Activity definition class or name.

  • args (Array<Object>) —

    Arguments to the activity.

  • summary (String, nil) (defaults to: nil) —

    Single-line summary for this activity that may appear in CLI/UI. This can be in single-line Temporal markdown format.

  • schedule_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take from first being scheduled to being completed before it times out. This is inclusive of all retries.

  • schedule_to_start_timeout (Float, nil) (defaults to: nil) —

    Max amount of time the activity can take to be started from first being scheduled.

  • start_to_close_timeout (Float, nil) (defaults to: nil) —

    Max amount of time a single activity run can take from when it starts to when it completes. This is per retry.

  • retry_policy (RetryPolicy, nil) (defaults to: nil) —

    How an activity is retried on failure. If unset, a default policy is used. Set maximum attempts to 1 to disable retries.

  • local_retry_threshold (Float, nil) (defaults to: nil) —

    If the activity is retrying and backoff would exceed this value, a timer is scheduled and the activity is retried after. Otherwise, backoff will happen internally within the task. Defaults to 1 minute.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation to apply to the activity. How cancellation is treated is based on cancellation_type. This defaults to the workflow's cancellation, but may need to be overridden with a new/detached one if an activity is being run in an ensure after workflow cancellation.

  • cancellation_type (ActivityCancellationType) (defaults to: ActivityCancellationType::TRY_CANCEL) —

    How the activity is treated when it is canceled from the workflow.

  • activity_id (String, nil) (defaults to: nil) —

    Optional unique identifier for the activity. This is an advanced setting that should not be set unless users are sure they need to. Contact Temporal before setting this value.

  • arg_hints (Array<Object>, nil) (defaults to: nil) —

    Overrides converter hints for arguments if any. If unset/nil and the activity definition has arg hints, those are used by default.

  • result_hint (Object, nil) (defaults to: nil) —

    Overrides converter hint for result if any. If unset/nil and the activity definition has result hint, it is used by default.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the activity command, in addition to any groups from enclosing with_event_groups scopes. WARNING: This option is experimental.

Returns:

  • (Object) —

    Result of the activity.

Raises:



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/temporalio/workflow.rb', line 317

def self.execute_local_activity(
  activity,
  *args,
  summary: nil,
  schedule_to_close_timeout: nil,
  schedule_to_start_timeout: nil,
  start_to_close_timeout: nil,
  retry_policy: nil,
  local_retry_threshold: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ActivityCancellationType::TRY_CANCEL,
  activity_id: nil,
  arg_hints: nil,
  result_hint: nil,
  event_groups: nil
)
  _current.execute_local_activity(
    activity, *args,
    summary:, schedule_to_close_timeout:, schedule_to_start_timeout:, start_to_close_timeout:,
    retry_policy:, local_retry_threshold:, cancellation:, cancellation_type:,
    activity_id:, arg_hints:, result_hint:, event_groups:
  )
end

.external_workflow_handle(workflow_id, run_id: nil) ⇒ ExternalWorkflowHandle

Get a handle to an external workflow for canceling and issuing signals.

Parameters:

  • workflow_id (String) —

    Workflow ID.

  • run_id (String, nil) (defaults to: nil) —

    Optional, specific run ID.

Returns:



347
348
349
 
# File 'lib/temporalio/workflow.rb', line 347

def self.external_workflow_handle(workflow_id, run_id: nil)
  _current.external_workflow_handle(workflow_id, run_id:)
end

.in_workflow? ⇒ Boolean

Returns Whether the current code is executing in a workflow.

Returns:

  • (Boolean) —

    Whether the current code is executing in a workflow.



352
353
354
 
# File 'lib/temporalio/workflow.rb', line 352

def self.in_workflow?
  _current_or_nil != nil
end

.info ⇒ Info

Returns Information about the current workflow.

Returns:

  • (Info) —

    Information about the current workflow.



357
358
359
 
# File 'lib/temporalio/workflow.rb', line 357

def self.info
  _current.info
end

.instance ⇒ Definition?

Returns Workflow class instance. This should always be present except in Temporalio::Worker::Interceptor::Workflow::Inbound#init where it will be nil.

Returns:



363
364
365
 
# File 'lib/temporalio/workflow.rb', line 363

def self.instance
  _current.instance
end

.logger ⇒ Logger

Returns Logger for the workflow. This is a scoped logger that automatically appends workflow details to every log and takes care not to log during replay.

Returns:

  • (Logger) —

    Logger for the workflow. This is a scoped logger that automatically appends workflow details to every log and takes care not to log during replay.



369
370
371
 
# File 'lib/temporalio/workflow.rb', line 369

def self.logger
  _current.logger
end

.memo ⇒ Hash{String, Symbol => Object}

Returns Memo for the workflow. This is a read-only view of the memo. To update the memo, use upsert_memo. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.

Returns:

  • (Hash{String, Symbol => Object}) —

    Memo for the workflow. This is a read-only view of the memo. To update the memo, use upsert_memo. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.



376
377
378
 
# File 'lib/temporalio/workflow.rb', line 376

def self.memo
  _current.memo
end

.metric_meter ⇒ Metric::Meter

Returns Metric meter to create metrics on. This metric meter already contains some workflow-specific attributes and takes care not to apply metrics during replay.

Returns:

  • (Metric::Meter) —

    Metric meter to create metrics on. This metric meter already contains some workflow-specific attributes and takes care not to apply metrics during replay.



382
383
384
 
# File 'lib/temporalio/workflow.rb', line 382

def self.metric_meter
  _current.metric_meter
end

.now ⇒ Time

Returns Current UTC time for this workflow. This creates and returns a new Time instance every time it is invoked, it is not the same instance continually mutated.

Returns:

  • (Time) —

    Current UTC time for this workflow. This creates and returns a new Time instance every time it is invoked, it is not the same instance continually mutated.



388
389
390
 
# File 'lib/temporalio/workflow.rb', line 388

def self.now
  _current.now
end

.patched(patch_id, event_groups: nil) ⇒ Boolean

Patch a workflow.

When called, this will only return true if code should take the newer path which means this is either not replaying or is replaying and has seen this patch before. Results for successive calls to this function for the same ID and workflow are memoized. Use deprecate_patch when all workflows are done and will never be queried again. The old code path can be removed at that time too.

Workers can set patch_activation_callback: to delay activating a newly introduced patch during rolling deployments. That callback is only used when the patch marker would otherwise be created for the first time.

Parameters:

  • patch_id (Symbol, String) —

    Patch ID.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the patch marker command. WARNING: This option is experimental.

Returns:

  • (Boolean) —

    True if this should take the newer patch, false if it should take the old path.



406
407
408
 
# File 'lib/temporalio/workflow.rb', line 406

def self.patched(patch_id, event_groups: nil)
  _current.patched(patch_id, event_groups:)
end

.payload_converter ⇒ Converters::PayloadConverter

Returns Payload converter for the workflow.

Returns:



411
412
413
 
# File 'lib/temporalio/workflow.rb', line 411

def self.payload_converter
  _current.payload_converter
end

.query_handlers ⇒ Hash<String, Definition::Query>

Returns Query handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_query method is best.

Returns:

  • (Hash<String, Definition::Query>) —

    Query handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_query method is best.



418
419
420
 
# File 'lib/temporalio/workflow.rb', line 418

def self.query_handlers
  _current.query_handlers
end

.random ⇒ Random

Returns Deterministic instance of Random for use in a workflow. This instance should be accessed each time needed, not stored. This instance may be recreated with a different seed in special cases (e.g. workflow reset). Do not use any other randomization inside workflow code.

Returns:

  • (Random) —

    Deterministic instance of Random for use in a workflow. This instance should be accessed each time needed, not stored. This instance may be recreated with a different seed in special cases (e.g. workflow reset). Do not use any other randomization inside workflow code.



425
426
427
 
# File 'lib/temporalio/workflow.rb', line 425

def self.random
  _current.random
end

.search_attributes ⇒ SearchAttributes

Returns Search attributes for the workflow. This is a read-only view of the attributes. To update the attributes, use upsert_search_attributes. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.

Returns:

  • (SearchAttributes) —

    Search attributes for the workflow. This is a read-only view of the attributes. To update the attributes, use upsert_search_attributes. This always returns the same instance and updates are reflected on the returned instance, so it is not technically frozen.



432
433
434
 
# File 'lib/temporalio/workflow.rb', line 432

def self.search_attributes
  _current.search_attributes
end

.signal_handlers ⇒ Hash<String, Definition::Signal>

Returns Signal handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_signal method is best.

Returns:

  • (Hash<String, Definition::Signal>) —

    Signal handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_signal method is best.



439
440
441
 
# File 'lib/temporalio/workflow.rb', line 439

def self.signal_handlers
  _current.signal_handlers
end

.sleep(duration, summary: nil, cancellation: Workflow.cancellation, event_groups: nil) ⇒ Object

Sleep in a workflow for the given time.

Parameters:

  • duration (Float, nil) —

    Time to sleep in seconds. nil represents infinite, which does not start a timer and just waits for cancellation. 0 is assumed to be 1 millisecond and still results in a server-side timer. This value cannot be negative. Since Temporal timers are server-side, timer resolution may not end up as precise as system timers.

  • summary (String, nil) (defaults to: nil) —

    A simple string identifying this timer that may be visible in UI/CLI. While it can be normal text, it is best to treat as a timer ID.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation for this timer.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the timer command, in addition to any groups from enclosing with_event_groups scopes. WARNING: This option is experimental.

Raises:



456
457
458
 
# File 'lib/temporalio/workflow.rb', line 456

def self.sleep(duration, summary: nil, cancellation: Workflow.cancellation, event_groups: nil)
  _current.sleep(duration, summary:, cancellation:, event_groups:)
end

.start_child_workflow(workflow, *args, id: random.uuid, task_queue: info.task_queue, static_summary: nil, static_details: nil, cancellation: Workflow.cancellation, cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED, parent_close_policy: ParentClosePolicy::TERMINATE, execution_timeout: nil, run_timeout: nil, task_timeout: nil, id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE, retry_policy: nil, cron_schedule: nil, memo: nil, search_attributes: nil, priority: Priority.default, versioning_override: nil, arg_hints: nil, result_hint: nil, event_groups: nil) ⇒ ChildWorkflowHandle

Start a child workflow and return the handle.

Parameters:

  • workflow (Class<Workflow::Definition>, Symbol, String) —

    Workflow definition class or workflow name.

  • args (Array<Object>) —

    Arguments to the workflow.

  • id (String) (defaults to: random.uuid) —

    Unique identifier for the workflow execution. Defaults to a new UUID from random.

  • task_queue (String) (defaults to: info.task_queue) —

    Task queue to run the workflow on. Defaults to the current workflow's task queue.

  • static_summary (String, nil) (defaults to: nil) —

    Fixed single-line summary for this workflow execution that may appear in CLI/UI. This can be in single-line Temporal markdown format.

  • static_details (String, nil) (defaults to: nil) —

    Fixed details for this workflow execution that may appear in CLI/UI. This can be in Temporal markdown format and can be multiple lines. This is a fixed value on the workflow that cannot be updated. For details that can be updated, use current_details= within the workflow.

  • cancellation (Cancellation) (defaults to: Workflow.cancellation) —

    Cancellation to apply to the child workflow. How cancellation is treated is based on cancellation_type. This defaults to the workflow's cancellation.

  • cancellation_type (ChildWorkflowCancellationType) (defaults to: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED) —

    How the child workflow will react to cancellation.

  • parent_close_policy (ParentClosePolicy) (defaults to: ParentClosePolicy::TERMINATE) —

    How to handle the child workflow when the parent workflow closes.

  • execution_timeout (Float, nil) (defaults to: nil) —

    Total workflow execution timeout in seconds including retries and continue as new.

  • run_timeout (Float, nil) (defaults to: nil) —

    Timeout of a single workflow run inseconds.

  • task_timeout (Float, nil) (defaults to: nil) —

    Timeout of a single workflow task in seconds.

  • id_reuse_policy (WorkflowIDReusePolicy) (defaults to: WorkflowIDReusePolicy::ALLOW_DUPLICATE) —

    How already-existing IDs are treated.

  • retry_policy (RetryPolicy, nil) (defaults to: nil) —

    Retry policy for the workflow.

  • cron_schedule (String, nil) (defaults to: nil) —

    Cron schedule. Users should use schedules instead of this.

  • memo (Hash{String, Symbol => Object}, nil) (defaults to: nil) —

    Memo for the workflow.

  • search_attributes (SearchAttributes, nil) (defaults to: nil) —

    Search attributes for the workflow.

  • priority (Priority) (defaults to: Priority.default) —

    Priority of the workflow.

  • versioning_override (VersioningOverride, nil) (defaults to: nil) —

    Override the child's versioning independently of its parent. If unset, normal versioning inheritance applies. Requires Temporal Server 1.32.0 or later. WARNING: This option is experimental.

  • arg_hints (Array<Object>, nil) (defaults to: nil) —

    Overrides converter hints for arguments if any. If unset/nil and the workflow definition has arg hints, those are used by default.

  • result_hint (Object, nil) (defaults to: nil) —

    Overrides converter hint for result if any. If unset/nil and the workflow definition has result hint, it is used by default.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the start-child command, in addition to any groups from enclosing with_event_groups scopes. WARNING: This option is experimental.

Returns:

Raises:



501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
 
# File 'lib/temporalio/workflow.rb', line 501

def self.start_child_workflow(
  workflow,
  *args,
  id: random.uuid,
  task_queue: info.task_queue,
  static_summary: nil,
  static_details: nil,
  cancellation: Workflow.cancellation,
  cancellation_type: ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED,
  parent_close_policy: ParentClosePolicy::TERMINATE,
  execution_timeout: nil,
  run_timeout: nil,
  task_timeout: nil,
  id_reuse_policy: WorkflowIDReusePolicy::ALLOW_DUPLICATE,
  retry_policy: nil,
  cron_schedule: nil,
  memo: nil,
  search_attributes: nil,
  priority: Priority.default,
  versioning_override: nil,
  arg_hints: nil,
  result_hint: nil,
  event_groups: nil
)
  _current.start_child_workflow(
    workflow, *args,
    id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
    parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
    retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, versioning_override:,
    arg_hints:, result_hint:, event_groups:
  )
end

.storage ⇒ Hash<Object, Object>

Returns General in-workflow storage. Most users will store state on the workflow class instance instead, this is only for utilities without access to the class instance.

Returns:

  • (Hash<Object, Object>) —

    General in-workflow storage. Most users will store state on the workflow class instance instead, this is only for utilities without access to the class instance.



536
537
538
 
# File 'lib/temporalio/workflow.rb', line 536

def self.storage
  _current.storage
end

.suggest_continue_as_new_reasons ⇒ Array<SuggestContinueAsNewReason::enum>

Returns Reasons the server suggests continue-as-new. Empty if no suggestion. This is currently experimental.

Returns:

  • (Array<SuggestContinueAsNewReason::enum>) —

    Reasons the server suggests continue-as-new. Empty if no suggestion. This is currently experimental.



98
99
100
 
# File 'lib/temporalio/workflow.rb', line 98

def self.suggest_continue_as_new_reasons
  _current.suggest_continue_as_new_reasons
end

.target_worker_deployment_version_changed? ⇒ Boolean

Returns Whether the target worker deployment version has changed from the one this workflow is running on. This is currently experimental.

Returns:

  • (Boolean) —

    Whether the target worker deployment version has changed from the one this workflow is running on. This is currently experimental.



104
105
106
 
# File 'lib/temporalio/workflow.rb', line 104

def self.target_worker_deployment_version_changed?
  _current.target_worker_deployment_version_changed?
end

.timeout(duration, exception_class = Timeout::Error, message = 'execution expired', summary: 'Timeout timer', event_groups: nil) { ... } ⇒ Object

Run the block until the timeout is reached. This is backed by sleep. This does not accept cancellation because it is expected the block within will properly handle/bubble cancellation.

Parameters:

  • duration (Float, nil) —

    Duration for the timeout. This is backed by sleep so see that method for details.

  • exception_class (Class<Exception>) (defaults to: Timeout::Error) —

    Exception to raise on timeout. Defaults to Timeout::Error like Timeout.timeout. Note that Timeout::Error is considered a workflow failure exception, not a task failure exception.

  • message (String) (defaults to: 'execution expired') —

    Message to use for timeout exception. Defaults to "execution expired" like Timeout.timeout.

  • summary (String) (defaults to: 'Timeout timer') —

    Timer summary for the timer created by this timeout. This is backed by sleep so see that method for details.

  • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

    Event Groups to attach to the timeout timer, in addition to any groups from enclosing with_event_groups scopes. Prefer this over wait_condition for wait-with-timeout. WARNING: This option is experimental.

Yields:

  • Block to run with a timeout.

Returns:

  • (Object) —

    The result of the block.

Raises:

  • (Exception) —

    Upon timeout, raises whichever class is set in exception_class with the message of message.



559
560
561
562
563
564
565
566
567
568
 
# File 'lib/temporalio/workflow.rb', line 559

def self.timeout(
  duration,
  exception_class = Timeout::Error,
  message = 'execution expired',
  summary: 'Timeout timer',
  event_groups: nil,
  &
)
  _current.timeout(duration, exception_class, message, summary:, event_groups:, &)
end

.update_handlers ⇒ Hash<String, Definition::Update>

Returns Update handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_update method is best.

Returns:

  • (Hash<String, Definition::Update>) —

    Update handlers for this workflow. This hash is mostly immutable except for []= (and store) which can be used to set a new handler, or can be set with nil to remove a handler. For most use cases, defining a handler as a workflow_update method is best.



573
574
575
 
# File 'lib/temporalio/workflow.rb', line 573

def self.update_handlers
  _current.update_handlers
end

.upsert_memo(hash, event_groups: nil) ⇒ Object .upsert_memo(event_groups: nil, **memo) ⇒ Object

Issue updates to the workflow memo.

Overloads:

  • .upsert_memo(hash, event_groups: nil) ⇒ Object

    Parameters:

    • hash (Hash{String, Symbol => Object, nil}) —

      Updates to apply. Value can be nil to effectively remove the memo value.

    • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

      Event Groups to attach to the modify-properties command. WARNING: This option is experimental.

  • .upsert_memo(event_groups: nil, **memo) ⇒ Object

    Parameters:

    • memo (Hash{String, Symbol => Object, nil}) —

      Updates to apply. Value can be nil to effectively remove the memo value.

    • event_groups (Array<EventGroup>, nil) (defaults to: nil) —

      Event Groups to attach to the modify-properties command. WARNING: This option is experimental.



589
590
591
592
593
594
595
596
597
598
599
 
# File 'lib/temporalio/workflow.rb', line 589

def self.upsert_memo(hash = nil, event_groups: nil, **memo)
  if hash
    unless memo.empty?
      raise ArgumentError, 'Memo updates must be passed either as a hash or as keyword arguments, not both'
    end
  else
    hash = memo
  end

  _current.upsert_memo(hash, event_groups:)
end

.upsert_search_attributes(*updates, event_groups: nil) ⇒ Object

Issue updates to the workflow search attributes.

Parameters:



608
609
610
 
# File 'lib/temporalio/workflow.rb', line 608

def self.upsert_search_attributes(*updates, event_groups: nil)
  _current.upsert_search_attributes(*updates, event_groups:)
end

.wait_condition(cancellation: Workflow.cancellation) { ... } ⇒ Object

Wait for the given block to return a "truthy" value (i.e. any value other than false or nil). The block must be side-effect free since it may be invoked frequently during event loop iteration. To timeout a wait, timeout can be used. This cannot be used in side-effect-free contexts such as initialize, queries, or update validators.

This is very commonly used to wait on a value to be set by a handler, e.g. Temporalio::Workflow.wait_condition { @some_value }. Special care was taken to only wake up a single wait condition when it evaluates to true. Therefore if multiple wait conditions are waiting on the same thing, only one is awoken at a time, which means the code immediately following that wait condition can change the variable before other wait conditions are evaluated. This is a useful property for building mutexes/semaphores.

Parameters:

  • cancellation (Cancellation, nil) (defaults to: Workflow.cancellation) —

    Cancellation to cancel the wait. This defaults to the workflow's cancellation.

Yields:

  • Block that is run many times to test for truthiness.

Yield Returns:

  • (Object) —

    Value to check whether truthy or falsy.

Returns:

  • (Object) —

    Truthy value returned from the block.

Raises:



629
630
631
632
633
 
# File 'lib/temporalio/workflow.rb', line 629

def self.wait_condition(cancellation: Workflow.cancellation, &)
  raise 'Block required' unless block_given?

  _current.wait_condition(cancellation:, &)
end

.with_event_groups(*groups) { ... } ⇒ Object

Run the given block with one or more Event Groups attached to every command produced inside it.

Nested scopes compose: a command produced inside an inner scope carries the Event Groups of all enclosing scopes. Fibers started within a scope inherit it, since they capture Fiber storage at creation.

WARNING: Event Groups support is experimental.

Parameters:

Yields:

  • Block to run with the given Event Groups in scope.

Returns:

  • (Object) —

    Result of the block.

Raises:

  • (ArgumentError) 


89
90
91
92
93
94
 
# File 'lib/temporalio/workflow.rb', line 89

def self.with_event_groups(*groups, &)
  raise ArgumentError, 'Block required' unless block_given?

  _current
  EventGroup._with_event_groups(*groups, &)
end