You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.

Class: AWS::SimpleWorkflow

Inherits:
Object
  • Object
show all
Includes:
Core::ServiceInterface
Defined in:
lib/aws/simple_workflow.rb,
lib/aws/simple_workflow/type.rb,
lib/aws/simple_workflow/count.rb,
lib/aws/simple_workflow/client.rb,
lib/aws/simple_workflow/errors.rb,
lib/aws/simple_workflow/domain.rb,
lib/aws/simple_workflow/resource.rb,
lib/aws/simple_workflow/decision_task.rb,
lib/aws/simple_workflow/activity_type.rb,
lib/aws/simple_workflow/activity_task.rb,
lib/aws/simple_workflow/workflow_type.rb,
lib/aws/simple_workflow/history_event.rb,
lib/aws/simple_workflow/type_collection.rb,
lib/aws/simple_workflow/option_formatters.rb,
lib/aws/simple_workflow/domain_collection.rb,
lib/aws/simple_workflow/workflow_execution.rb,
lib/aws/simple_workflow/activity_task_collection.rb,
lib/aws/simple_workflow/activity_type_collection.rb,
lib/aws/simple_workflow/workflow_type_collection.rb,
lib/aws/simple_workflow/decision_task_collection.rb,
lib/aws/simple_workflow/history_event_collection.rb,
lib/aws/simple_workflow/workflow_execution_collection.rb

Overview

This is the starting point for working with Amazon Simple Workflow Service.

Domains

To get started, you need to first create a domain. Domains are used to organize related tasks and activities.

swf = AWS::SimpleWorkflow.new

# name the domain and specify the retention period (in days)
domain = swf.domains.create('my-domain', 10)

You can reference existing domains as well.

domain = swf.domains['my-domain']

Workflow and Activity Types

Once you have a domain you can create a workflow and activity types. Both types (workflow and activity) are templates that can be used to start workflow executions or schedule activity tasks.

Workflow and Activity types both have a number of default values (e.g. default task list, timeouts, etc). If you do not specify these optional default values when creating the type, you MUST specify the actual values when starting a workflow execution or scheduling an activity task.

Sample Workflow type and activity type

# register an workflow type with the version id '1'
workflow_type = domain.workflow_types.create('my-long-processes', '1',
  :default_task_list => 'my-task-list',
  :default_child_policy => :request_cancel,
  :default_task_start_to_close_timeout => 3600,
  :default_execution_start_to_close_timeout => 24 * 3600)

# register an activity type, with the version id '1'
activity_type = domain.activity_types.create('do-something', '1',
  :default_task_list => 'my-task-list',
  :default_task_heartbeat_timeout => 900,
  :default_task_schedule_to_start_timeout => 60,
  :default_task_schedule_to_close_timeout => 3660,
  :default_task_start_to_close_timeout => 3600)

Starting a Workflow Execution

Once you have a domain and at least one workflow type you can start a workflow execution. You may provide a workflow id, or a random one will be generated. You may also provide optional input and override any of the defaults registered with the workflow type.

workflow_execution = workflow_type.start_execution :input => '...'

workflow_execution.workflow_id #=> "5abbdd75-70c7-4af3-a324-742cd29267c2"
workflow_execution.run_id #=> "325a8c34-d133-479e-9ecf-5a61286d165f"

Decision Tasks

Once a workflow execution has been started, it will start to generate decision tasks. You poll for decision tasks from a task list. Yielded decision tasks provide access to the history of events for the workflow execution. You can also enumerate only new events since the last decision.

To make decisions you call methods from the list below. You can call any number of decision methods any number of times.

  • schedule_activity_task
  • request_cancel_activity_task
  • complete_workflow_execution
  • fail_workflow_execution
  • cancel_workflow_execution
  • continue_as_new_workflow_execution
  • record_marker
  • start_timer
  • cancel_timer
  • signal_external_workflow_execution
  • request_cancel_external_workflow_execution workflow_execution, options = {}
  • start_child_workflow_execution workflow_type, options = {}

This sample gets a decision task and responds based on the events by scheduling an activity task or completing the workflow execution.

# poll for decision tasks from 'my-task-list'
domain.decision_tasks.poll('my-task-list') do |task|

  # investigate new events and make decisions
  task.new_events.each do |event|
    case event.event_type
    when 'WorkflowExecutionStarted'
      task.schedule_activity_task 'do-something', :input => 'abc xyz'
    when 'ActivityTaskCompleted'
      task.complete_workflow_execution :result => event.attributes.result
    end
  end

end # decision task is completed here

When you are done calling decision methods, you need to complete the decision task. This is done by default if you pass a block to poll or poll_for_single_task.

Activity Tasks

The only way to spawn activity tasks is to call schedule_activity_task on a decision task. Scheduled activity tasks are returned when you poll for activity tasks.

# poll 'my-task-list' for activities
domain.activity_tasks.poll('my-task-list') do |activity_task|

  case activity_task.activity_type.name
  when 'do-something'
    # ...
  else
    activity_task.fail! :reason => 'unknown activity task type'
  end

end

Activity Task Heartbeats

When you receive an activity task, you need to update the service with status messages. This is called recording a heartbeat.# To record a heartbeat, just call ActivityTask#record_heartbeat!. When you call record_heartbeat you should rescue ActivityTask::CancelRequestedError. These are thrown when a task should be canceled. You can cleanup the task and then call cancel! when you are finished.

# poll 'my-task-list' for activities
domain.activity_tasks.poll('my-task-list') do |activity_task|
  begin

    # do stuff ...

    activity_task.record_heartbeat! :details => '25%'

    # do more stuff ...

    activity_task.record_heartbeat! :details => '50%'

    # do more stuff ...

    activity_task.record_heartbeat! :details => '75%'

    # do more stuff ...

  rescue ActivityTask::CancelRequestedError
    # cleanup after ourselves
    activity_task.cancel!
  end
end

Like decision tasks, activity tasks are auto-completed at the end of a poll block.

History Events

You might want to view the event history for a running workflow execution. You can get a workflow execution by its workflow id (you may optionally provide the run id as well).

execution = domain.workflow_executions['workflow-id', 'run-id']
execution.events.each do |event|
  puts event.attributes.to_h.inspect
end

See HistoryEvent and HistoryEvent::Attributes for more information.

Defined Under Namespace

Modules: Errors Classes: ActivityTask, ActivityTaskCollection, ActivityType, ActivityTypeCollection, Client, Count, DecisionTask, DecisionTaskCollection, Domain, DomainCollection, HistoryEvent, HistoryEventCollection, Type, WorkflowExecution, WorkflowExecutionCollection, WorkflowType, WorkflowTypeCollection

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Core::ServiceInterface

included, #initialize, #inspect

Instance Attribute Details

#clientClient (readonly)

Returns the low-level SimpleWorkflow client object

Returns:

  • (Client)

    the low-level SimpleWorkflow client object



193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
# File 'lib/aws/simple_workflow.rb', line 193

class SimpleWorkflow

  autoload :ActivityType, 'aws/simple_workflow/activity_type'
  autoload :ActivityTypeCollection, 'aws/simple_workflow/activity_type_collection'
  autoload :ActivityTask, 'aws/simple_workflow/activity_task'
  autoload :ActivityTaskCollection, 'aws/simple_workflow/activity_task_collection'
  autoload :Client, 'aws/simple_workflow/client'
  autoload :Count, 'aws/simple_workflow/count'
  autoload :DecisionTask, 'aws/simple_workflow/decision_task'
  autoload :DecisionTaskCollection, 'aws/simple_workflow/decision_task_collection'
  autoload :Domain, 'aws/simple_workflow/domain'
  autoload :DomainCollection, 'aws/simple_workflow/domain_collection'
  autoload :Errors, 'aws/simple_workflow/errors'
  autoload :HistoryEvent, 'aws/simple_workflow/history_event'
  autoload :HistoryEventCollection, 'aws/simple_workflow/history_event_collection'
  autoload :OptionFormatters, 'aws/simple_workflow/option_formatters'
  autoload :Resource, 'aws/simple_workflow/resource'
  autoload :Type, 'aws/simple_workflow/type'
  autoload :TypeCollection, 'aws/simple_workflow/type_collection'
  autoload :WorkflowExecution, 'aws/simple_workflow/workflow_execution'
  autoload :WorkflowExecutionCollection, 'aws/simple_workflow/workflow_execution_collection'
  autoload :WorkflowType, 'aws/simple_workflow/workflow_type'
  autoload :WorkflowTypeCollection, 'aws/simple_workflow/workflow_type_collection'

  include Core::ServiceInterface

  endpoint_prefix 'swf'

  # @return [DomainCollection]
  def domains
    DomainCollection.new(:config => config)
  end

end

Instance Method Details

#domainsDomainCollection

Returns:



222
223
224
# File 'lib/aws/simple_workflow.rb', line 222

def domains
  DomainCollection.new(:config => config)
end