Class: AWS::SimpleWorkflow::DecisionTask

Inherits:
Object
  • Object
show all
Defined in:
lib/aws/simple_workflow/decision_task.rb

Overview

Getting Decision Tasks

You can use #poll or #poll_for_single_task on DecisionTaskCollection to grab a decision task:

# get a single task
if task = domain.decision_tasks.poll_for_single_task('task-list')
  # make decisions
  task.complete!
end

See DecisionTaskCollection for more information on getting and counting decision tasks.

Exploring Event History

Once you have a decision task you can examine the event history. This can give you the information you need to make decisions. The #events and #new_events methods enumerate through all events or events since the last decision.

decision_task.new_events.each do |event|
  # inspect the #event_type and #attributes
end

Check out HistoryEvent for more information on working with events.

Making Decisions

Based on the history of events, you should make decisions by calling methods listed below. You can call each method as many times as you wish, until you have completed the decision task.

* {#schedule_activity_task}
* {#request_cancel_activity_task}

* {#complete_workflow_execution}
* {#cancel_workflow_execution}
* {#fail_workflow_execution}
* {#continue_as_new_workflow_execution}

* {#record_marker}
* {#start_timer}
* {#cancel_timer}

* {#signal_external_workflow_execution}
* {#request_cancel_external_workflow_execution}
* {#start_child_workflow_execution}

The decision methods are grouped above by concern.

Completing the Decision Task

Once you have finished adding decisions to the task, you need to complete it. If you called AWS::SimpleWorkflow::DecisionTaskCollection#poll or AWS::SimpleWorkflow::DecisionTaskCollection#poll_for_single_task with a block argument then the decision will be completed automatically at the end of the block.

domain.decision_tasks.poll do |decision_task|
  # ...
end #=> the decision task is closed here

If you get a task from AWS::SimpleWorkflow::DecisionTaskCollection#poll_for_single_task without a block, then it is your responsibility to call #complete! on the decision task. If you fail to do this before the task start to close timeout, then a decisionTaskTimedOut event will be added to the workflow execution history.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#domain ⇒ Domain (readonly)

Returns:



127
128
129
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 127

def domain
  @domain
end

#next_token ⇒ String? (readonly)

Returns a value if the results are paginated. Normally you do not need this value, as #events will enumerate all events, making requests as necessary to get more.

Returns:

  • (String, nil) —

    Returns a value if the results are paginated. Normally you do not need this value, as #events will enumerate all events, making requests as necessary to get more.



149
150
151
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 149

def next_token
  @next_token
end

#previous_started_event_id ⇒ Integer (readonly)

Returns The id of the DecisionTaskStarted event of the previous decision task of this workflow execution that was processed by the decider. This can be used to determine the new events in the history new since the last decision task received by the decider.

Returns:

  • (Integer) —

    The id of the DecisionTaskStarted event of the previous decision task of this workflow execution that was processed by the decider. This can be used to determine the new events in the history new since the last decision task received by the decider.



140
141
142
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 140

def previous_started_event_id
  @previous_started_event_id
end

#started_event_id ⇒ Integer (readonly)

Returns The id of the DecisionTaskStarted event recorded in the history.

Returns:

  • (Integer) —

    The id of the DecisionTaskStarted event recorded in the history.



144
145
146
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 144

def started_event_id
  @started_event_id
end

#task_token ⇒ String (readonly)

Returns The decision task identifier.

Returns:

  • (String) —

    The decision task identifier.



124
125
126
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 124

def task_token
  @task_token
end

#workflow_execution ⇒ WorkflowExecution (readonly)

Returns:



130
131
132
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 130

def workflow_execution
  @workflow_execution
end

#workflow_type ⇒ WorkflowType (readonly)

Returns:



133
134
135
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 133

def workflow_type
  @workflow_type
end

Instance Method Details

#cancel_timer(timer_id) ⇒ nil

Cancels a previously scheduled timer and records a TimerCanceled event in the history.

Parameters:

  • timer_id (String) —

    The id of the timer to cancel.

Returns:

  • (nil) 


465
466
467
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 465

def cancel_timer timer_id
  add_decision :cancel_timer, { :timer_id => timer_id }
end

#cancel_workflow_execution(options = {}) ⇒ nil

Closes the workflow execution and records a WorkflowExecutionCanceled event in the history.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :details (String) — default: nil —

    Optional details of the cancellation.

Returns:

  • (nil) 


353
354
355
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 353

def cancel_workflow_execution options = {}
  add_decision :cancel_workflow_execution, options
end

#complete!(options = {}) ⇒ nil

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

Returns:

  • (nil) 


171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 171

def complete! options = {}

  raise 'already responded' if responded?

  options[:task_token] = task_token
  options[:decisions] = @decisions unless @decisions.empty?

  client.respond_decision_task_completed(options)

  @responded = true

  nil

end

#complete_workflow_execution(options = {}) ⇒ nil

Closes the workflow execution and records a WorkflowExecutionCompleted event in the history.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :result (String) — default: nil —

    The results of the workflow execution.

Returns:

  • (nil) 


324
325
326
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 324

def complete_workflow_execution options = {}
  add_decision :complete_workflow_execution, options
end

#continue_as_new_workflow_execution(options = {}) ⇒ nil

Closes the workflow execution and starts a new workflow execution of the same type using the same workflow id and a unique run Id. A WorkflowExecutionContinuedAsNew event is recorded in the history.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :input (String) — default: nil —

    The input for the workflow execution. This is a free form string which should be meaningful to the workflow you are starting. This input is made available to the new workflow execution in the WorkflowExecutionStarted history event.

  • :tag_list (Array<string>) — default: [] —

    A list of tags (strings) to associate with the workflow execution. You can specify a maximum of 5 tags.

  • :child_policy (Symbol) — default: nil —

    Specifies the policy to use for the child workflow executions of this workflow execution if it is terminated explicitly or due to an expired timeout. This policy overrides the default child policy specified when registering the workflow type. The supported child policies are:

    • :terminate - the child executions will be terminated.

    • :request_cancel - a request to cancel will be attempted for each child execution by recording a WorkflowExecutionCancelRequested event in its history. It is up to the decider to take appropriate actions when it receives an execution history with this event.

    • :abandon - no action will be taken. The child executions will continue to run.

  • :execution_start_to_close_timeout (Integer, :none) — default: nil —

    The total duration for this workflow execution. This overrides the default specified when registering the workflow type.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

  • :task_list (String) — default: nil —

    The task list to use for the decision tasks generated for this workflow execution. This overrides the default task list specified when registering the workflow type.

  • :task_start_to_close_timeout (Integer, :none) — default: nil —

    Specifies the maximum duration of decision tasks for this workflow execution. This parameter overrides the default specified when the workflow type was registered.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

Returns:

  • (nil) 


410
411
412
413
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 410

def continue_as_new_workflow_execution options = {}
  start_execution_opts(options)
  add_decision :continue_as_new_workflow_execution, options
end

#events ⇒ Enumerable

Returns an enumerable collection of all events for the workflow execution.

Returns:

  • (Enumerable) —

    Returns an enumerable collection of all events for the workflow execution.



153
154
155
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 153

def events
  enum_for(:_events)
end

#fail_workflow_execution(options = {}) ⇒ nil

Closes the workflow execution and records a WorkflowExecutionFailed event in the history.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :reason (String) — default: nil —

    Reason for the failure.

  • :details (String) — default: nil —

    Optional details of the failure.

Returns:

  • (nil) 


339
340
341
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 339

def fail_workflow_execution options = {}
  add_decision :fail_workflow_execution, options
end

#new_events ⇒ Enumerable

Returns an enumerable collection of only the new events for workflow execution (since the last decision).

Returns:

  • (Enumerable) —

    Returns an enumerable collection of only the new events for workflow execution (since the last decision).



159
160
161
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 159

def new_events  
  enum_for(:_new_events)
end

#record_marker(marker_name, options = {}) ⇒ nil

Records a MarkerRecorded event in the history. Markers can be used for adding custom information in the history for instance to let deciders know that they do not need to look at the history beyond the marker event.

Parameters:

  • marker_name (String) —

    The name of the marker.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :details (String) — default: nil —

    Optional details of the marker.

Returns:

  • (nil) 


428
429
430
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 428

def record_marker marker_name, options = {}
  add_decision :record_marker, options.merge(:marker_name => marker_name)
end

#request_cancel_activity_task(activity_or_activity_id) ⇒ nil

Attempts to cancel a previously scheduled activity task. If the activity task was scheduled but has not been assigned to a worker, then it will be canceled. If the activity task was already assigned to a worker, then the worker will be informed that cancellation has been requested when recording the activity task heartbeat.

Parameters:

  • activity_or_activity_id (ActivityTask, String) —

    An ActivityTask object or the activity_id of an activity task to request cancellation for.

Returns:

  • (nil) 


304
305
306
307
308
309
310
311
312
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 304

def request_cancel_activity_task activity_or_activity_id

  id = activity_or_activity_id.is_a?(ActivityTask) ?
    activity_or_activity_id.activity_id :
    activity_or_activity_id

  add_decision :request_cancel_activity_task, { :activity_id => id }

end

#request_cancel_external_workflow_execution(workflow_execution, options = {}) ⇒ nil

Requests that a request be made to cancel the specified external workflow execution and records a RequestCancelExternalWorkflowExecutionRequested event in the history.

Returns:

  • (nil) 


502
503
504
505
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 502

def request_cancel_external_workflow_execution workflow_execution, options = {}
  workflow_execution_opts(options, workflow_execution)
  add_decision :request_cancel_external_workflow_execution, options
end

#responded? ⇒ Boolean

Returns true if #complete! has been called on this decision task.

Returns:

  • (Boolean) —

    Returns true if #complete! has been called on this decision task.



188
189
190
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 188

def responded?
  !!@responded
end

#schedule_activity_task(activity_type, options = {}) ⇒ nil

Note:

This adds a decision to this task that is finalized when you call #complete!.

Schedules an activity task.

Parameters:

  • activity_type (ActivityType, Hash) —

    The type of activity to schedule. activity_type must be an ActivityType object or a hash with :name and :version.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :control (String) — default: nil —

    Optional data attached to the event that can be used by the decider in subsequent workflow tasks. This data is not sent to the activity.

  • :heartbeat_timeout (Integer, :none) — default: nil —

    The maximum time before which a worker processing a task of this type must report progress. If the timeout is exceeded, the activity task is automatically timed out. If the worker subsequently attempts to record a heartbeat or returns a result, it will be ignored. This default can be overridden when scheduling an activity task.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

  • :input (String) — default: nil —

    Input provided to the activity task.

  • :schedule_to_close_timeout (Integer, :none) — default: nil —

    The maximum duration that a task of this activity type can wait before being assigned to a worker.

    A schedule-to-close timeout for this activity task must be specified either as a default for the activity type or through this option. If neither this field is set nor a default was specified at registration time then a fault will be returned.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

  • :schedule_to_start_timeout (Integer, :none) — default: nil —

    The maximum duration that a task of this activity type can wait before being assigned to a worker. This overrides the default timeout specified when registering the activity type.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

  • :start_to_close_timeout (Integer, :none) — default: nil —

    The maximum duration that a worker can take to process tasks of this activity type. This overrides the default timeout specified when registering the activity type.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

  • :task_list (String) — default: nil —

    If set, specifies the name of the task list in which to schedule the activity task. If not specified, the default task list registered with the activity type will be used.

Returns:

  • (nil) 


256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 256

def schedule_activity_task activity_type, options = {}

  options[:activity_id] ||= UUIDTools::UUID.random_create.to_s

  options[:activity_type] = case activity_type
  when Hash 
    unless 
      activity_type[:name].is_a?(String) and
      activity_type[:version].is_a?(String) and
      activity_type.keys.length == 2
    then
      msg = 'activity_type hash must have :name and :version strings'
      raise ArgumentError, msg
    end
    activity_type
  when ActivityType
    { :name => activity_type.name, :version => activity_type.version }
  else
    msg = 'expected activity_type to be an ActivityType object or a hash'
    raise ArgumentError, msg 
  end

  duration_opts(options, 
    :heartbeat_timeout,
    :schedule_to_close_timeout,
    :schedule_to_start_timeout,
    :start_to_close_timeout)

  if task_list = options[:task_list]
    options[:task_list] = { :name => task_list }
  end

  add_decision :schedule_activity_task, options
  
end

#signal_external_workflow_execution(workflow_execution, signal_name, options = {}) ⇒ nil

Requests a signal to be delivered to the specified external workflow execution and records a SignalExternalWorkflowExecutionRequested event in the history.

Parameters:

  • workflow_execution (WorkflowExecution, String)
  • signal_name (String)
  • options (Hash) (defaults to: {})

Options Hash (options):

  • :control (String) — default: nil —

    Optional data attached to the event that can be used by the decider in subsequent decision tasks.

  • :input (String) — default: nil —

    Optional input to be provided with the signal. The target workflow execution will use the signal name and input to process the signal.

Returns:

  • (nil) 


489
490
491
492
493
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 489

def signal_external_workflow_execution workflow_execution, signal_name, options = {}
  workflow_execution_opts(options, workflow_execution)
  options[:signal_name] = signal_name
  add_decision :signal_external_workflow_execution, options
end

#start_child_workflow_execution(workflow_type, options = {}) ⇒ String

Requests that a child workflow execution be started and records a StartChildWorkflowExecutionRequested event in the history. The child workflow execution is a separate workflow execution with its own history.

Parameters:

  • workflow_type (WorkflowType, Hash) —

    (nil) The type of workflow execution to start. This should be a WorkflowType object or a hash with the keys :name and :version.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :control (String) — default: nil —

    Optional data attached to the event that can be used by the decider in subsequent workflow tasks.

  • :workflow_id (String) —

    A user defined identifier associated with the workflow execution. You can use this to associate a custom identifier with the workflow execution. You may specify the same identifier if a workflow execution is logically a restart of a previous execution. You cannot have two open workflow executions with the same :workflow_id at the same time.

    If you do not provide :workflow_id a random UUID will be generated.

  • :input (String) — default: nil —

    The input for the workflow execution. This is a free form string which should be meaningful to the workflow you are starting. This input is made available to the new workflow execution in the WorkflowExecutionStarted history event.

  • :tag_list (Array<string>) — default: [] —

    A list of tags (strings) to associate with the workflow execution. You can specify a maximum of 5 tags.

  • :child_policy (Symbol) — default: nil —

    Specifies the policy to use for the child workflow executions of this workflow execution if it is terminated explicitly or due to an expired timeout. This policy overrides the default child policy specified when registering the workflow type. The supported child policies are:

    • :terminate - the child executions will be terminated.

    • :request_cancel - a request to cancel will be attempted for each child execution by recording a WorkflowExecutionCancelRequested event in its history. It is up to the decider to take appropriate actions when it receives an execution history with this event.

    • :abandon - no action will be taken. The child executions will continue to run.

  • :execution_start_to_close_timeout (Integer, :none) — default: nil —

    The total duration for this workflow execution. This overrides the default specified when registering the workflow type.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

  • :task_list (String) — default: nil —

    The task list to use for the decision tasks generated for this workflow execution. This overrides the default task list specified when registering the workflow type.

  • :task_start_to_close_timeout (Integer, :none) — default: nil —

    Specifies the maximum duration of decision tasks for this workflow execution. This parameter overrides the default specified when the workflow type was registered.

    The value should be a number of seconds (integer) or the symbol :none (implying no timeout).

Returns:

  • (String) —

    Returns the workflow id of the new execution.



526
527
528
529
530
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 526

def start_child_workflow_execution workflow_type, options = {}
  start_execution_opts(options, workflow_type)
  add_decision :start_child_workflow_execution, options
  options[:workflow_id]
end

#start_timer(start_to_fire_timeout, options = {}) ⇒ String

Schedules a timer for this workflow execution and records a TimerScheduled event in the history. This timer will fire after the specified delay and record a TimerFired event.

Parameters:

  • start_to_fire_timeout (Integer) —

    (nil) The duration to wait before firing the timer.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :control (String) — default: nil —

    Optional data attached to the event that can be used by the decider in subsequent workflow tasks.

  • :timer_id (String) — default: nil —

    Unique id for the timer. If you do not pass this option, a UUID will be generated.

Returns:

  • (String) —

    Returns the id of the timer.



450
451
452
453
454
455
456
 
# File 'lib/aws/simple_workflow/decision_task.rb', line 450

def start_timer start_to_fire_timeout, options = {}
  options[:timer_id] ||= UUIDTools::UUID.random_create.to_s
  options[:start_to_fire_timeout] = start_to_fire_timeout
  duration_opts(options, :start_to_fire_timeout)
  add_decision :start_timer, options
  options[:timer_id]
end