Class: Temporalio::Client::WorkflowHandle

Inherits:
Object
  • Object
show all
Defined in:
lib/temporalio/client/workflow_handle.rb

Overview

Handle for interacting with a workflow.

This is usually created via #workflow_handle or returned from #start_workflow.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client_impl, id, run_id: nil, result_run_id: nil, first_execution_run_id: nil) ⇒ WorkflowHandle

Returns a new instance of WorkflowHandle.



52
53
54
55
56
57
58
 
# File 'lib/temporalio/client/workflow_handle.rb', line 52

def initialize(client_impl, id, run_id: nil, result_run_id: nil, first_execution_run_id: nil)
  @client_impl = client_impl
  @id = id
  @run_id = run_id
  @result_run_id = result_run_id
  @first_execution_run_id = first_execution_run_id
end

Instance Attribute Details

#first_execution_run_id ⇒ String (readonly)

Run ID used for #cancel and #terminate calls if present to ensure the cancel and terminate happen for a workflow ID started with this run ID.

This can be set when using Temporalio::Client#workflow_handle. When Temporalio::Client#start_workflow is called without a start signal, this is set to the resulting run.

This cannot be mutated. If a different first execution run ID is needed, Temporalio::Client#workflow_handle must be used instead.

Returns:

  • (String) 


50
51
52
 
# File 'lib/temporalio/client/workflow_handle.rb', line 50

def first_execution_run_id
  @first_execution_run_id
end

#id ⇒ String (readonly)

Returns ID for the workflow.

Returns:

  • (String) —

    ID for the workflow.



12
13
14
 
# File 'lib/temporalio/client/workflow_handle.rb', line 12

def id
  @id
end

#result_run_id ⇒ String (readonly)

Run ID used for #result calls if present to ensure result is for a workflow starting from this run.

When this handle is created via Temporalio::Client#workflow_handle, this is the same as ‘:run_id`. When this handle is created via Temporalio::Client#start_workflow, this value will be the resulting run ID.

This cannot be mutated. If a different run ID is needed, Temporalio::Client#workflow_handle must be used instead.

Returns:

  • (String) 


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

def result_run_id
  @result_run_id
end

#run_id ⇒ String (readonly)

Run ID used for #signal and #query calls if present to ensure the query or signal happen on this exact run.

This is only set on handles created via Temporalio::Client#workflow_handle with a ‘run_id` parameter. Temporalio::Client#start_workflow does not set this value.

This cannot be mutated. If a different run ID is needed, Temporalio::Client#workflow_handle must be used instead.

Returns:

  • (String) 


24
25
26
 
# File 'lib/temporalio/client/workflow_handle.rb', line 24

def run_id
  @run_id
end

Instance Method Details

#cancel(reason = nil, rpc_metadata: {}, rpc_timeout: nil) ⇒ Object

Note:

Handles created as a result of Temporalio::Client#start_workflow with a start signal will cancel the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Cancel the workflow.

This will issue a cancellation for #run_id if present. This call will make sure to use the run chain starting from #first_execution_run_id if present. To create handles with these values, use Temporalio::Client#workflow_handle.

Parameters:

  • reason (String) (defaults to: nil) —

    A reason for workflow cancellation.

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers used on the RPC call. Keys here override client-level RPC metadata keys.

  • rpc_timeout (Integer) (defaults to: nil) —

    Optional RPC deadline to set for each RPC call.

Raises:



124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/temporalio/client/workflow_handle.rb', line 124

def cancel(reason = nil, rpc_metadata: {}, rpc_timeout: nil)
  input = Interceptor::Client::CancelWorkflowInput.new(
    id: id,
    run_id: run_id,
    first_execution_run_id: first_execution_run_id,
    reason: reason,
    rpc_metadata: rpc_metadata,
    rpc_timeout: rpc_timeout,
  )

  client_impl.cancel_workflow(input)
end

#describe(rpc_metadata: {}, rpc_timeout: nil) ⇒ Temporalio::Workflow::ExecutionInfo

Note:

Handles created as a result of Temporalio::Client#start_workflow will describe the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Get workflow details.

This will get details for #run_id if present. To use a different run ID, create a new handle with via Temporalio::Client#workflow_handle.

Parameters:

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers used on the RPC call. Keys here override client-level RPC metadata keys.

  • rpc_timeout (Integer) (defaults to: nil) —

    Optional RPC deadline to set for each RPC call. Note, this is the timeout for each history RPC call not this overall function.

Returns:

Raises:



97
98
99
100
101
102
103
104
105
106
 
# File 'lib/temporalio/client/workflow_handle.rb', line 97

def describe(rpc_metadata: {}, rpc_timeout: nil)
  input = Interceptor::Client::DescribeWorkflowInput.new(
    id: id,
    run_id: run_id,
    rpc_metadata: rpc_metadata,
    rpc_timeout: rpc_timeout,
  )

  client_impl.describe_workflow(input)
end

#query(query, *args, reject_condition: Workflow::QueryRejectCondition::NONE, rpc_metadata: {}, rpc_timeout: nil) ⇒ any

Note:

Handles created as a result of Temporalio::Client#start_workflow will query the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Query the workflow.

This will query for #run_id if present. To use a different run ID, create a new handle with via Temporalio::Client#workflow_handle.

Parameters:

  • query (String, Symbol) —

    Query function or name on the workflow.

  • args (any) —

    Arguments to the query.

  • reject_condition (Symbol) (defaults to: Workflow::QueryRejectCondition::NONE) —

    Condition for rejecting the query. Refer to Workflow::QueryRejectCondition for the list of allowed values.

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers used on the RPC call. Keys here override client-level RPC metadata keys.

  • rpc_timeout (Integer) (defaults to: nil) —

    Optional RPC deadline to set for each RPC call.

Returns:

  • (any) —

    Result of the query.

Raises:



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/temporalio/client/workflow_handle.rb', line 157

def query(
  query,
  *args,
  reject_condition: Workflow::QueryRejectCondition::NONE,
  rpc_metadata: {},
  rpc_timeout: nil
)
  input = Interceptor::Client::QueryWorkflowInput.new(
    id: id,
    run_id: run_id,
    query: query,
    args: args,
    reject_condition: reject_condition,
    headers: {},
    rpc_metadata: rpc_metadata,
    rpc_timeout: rpc_timeout,
  )

  client_impl.query_workflow(input)
end

#result(follow_runs: true, rpc_metadata: {}, rpc_timeout: nil) ⇒ any

Wait for result of the workflow.

This will use #result_run_id if present to base the result on. To use another run ID, a new handle must be created via Temporalio::Client#workflow_handle.

Parameters:

  • follow_runs (Bool) (defaults to: true) —

    If true (default), workflow runs will be continually fetched, until the most recent one is found. If false, the first result is used.

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers used on the RPC call. Keys here override client-level RPC metadata keys.

  • rpc_timeout (Integer) (defaults to: nil) —

    Optional RPC deadline to set for each RPC call. Note, this is the timeout for each history RPC call not this overall function.

Returns:

  • (any) —

    Result of the workflow after being converted by the data converter.

Raises:



77
78
79
 
# File 'lib/temporalio/client/workflow_handle.rb', line 77

def result(follow_runs: true, rpc_metadata: {}, rpc_timeout: nil)
  client_impl.await_workflow_result(id, result_run_id, follow_runs, rpc_metadata, rpc_timeout)
end

#signal(signal, *args, rpc_metadata: {}, rpc_timeout: nil) ⇒ Temporalio::Error::RPCError

Note:

Handles created as a result of Temporalio::Client#start_workflow will signal the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Send a signal to the workflow.

This will signal for #run_id if present. To use a different run ID, create a new handle with via Temporalio::Client#workflow_handle.

Parameters:

  • signal (String, Symbol) —

    Signal function or name on the workflow.

  • args (any) —

    Arguments to the signal.

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers used on the RPC call. Keys here override client-level RPC metadata keys.

  • rpc_timeout (Integer) (defaults to: nil) —

    Optional RPC deadline to set for each RPC call.

Returns:



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/temporalio/client/workflow_handle.rb', line 193

def signal(signal, *args, rpc_metadata: {}, rpc_timeout: nil)
  input = Interceptor::Client::SignalWorkflowInput.new(
    id: id,
    run_id: run_id,
    signal: signal,
    args: args,
    headers: {},
    rpc_metadata: rpc_metadata,
    rpc_timeout: rpc_timeout,
  )

  client_impl.signal_workflow(input)
end

#terminate(reason = nil, args = nil, rpc_metadata: {}, rpc_timeout: nil) ⇒ Object

Note:

Handles created as a result of Temporalio::Client#start_workflow with a start signal will terminate the latest workflow with the same workflow ID even if it is unrelated to the started workflow.

Parameters:

  • reason (String) (defaults to: nil) —

    A reason for workflow termination.

  • args (any) (defaults to: nil) —

    Details to store on the termination.

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers used on the RPC call. Keys here override client-level RPC metadata keys.

  • rpc_timeout (Integer) (defaults to: nil) —

    Optional RPC deadline to set for each RPC call.

Raises:



224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/temporalio/client/workflow_handle.rb', line 224

def terminate(reason = nil, args = nil, rpc_metadata: {}, rpc_timeout: nil)
  input = Interceptor::Client::TerminateWorkflowInput.new(
    id: id,
    run_id: run_id,
    first_execution_run_id: first_execution_run_id,
    reason: reason,
    args: args,
    rpc_metadata: rpc_metadata,
    rpc_timeout: rpc_timeout,
  )

  client_impl.terminate_workflow(input)
end