Class: AWS::SimpleWorkflow::WorkflowExecutionCollection

Inherits:
Object
  • Object
show all
Includes:
Core::Collection::Limitable, OptionFormatters
Defined in:
lib/aws/simple_workflow/workflow_execution_collection.rb

Overview

A collection that enumerates workflow executions.

domain.workflow_executions.each do |execution|
  # ...
end

Filtering Executions

By default, all open workflow executions are enumerated.

Constant Summary collapse

FILTERS =
[
  :status,
  :workflow_type,
  :workflow_id,
  :tagged,          
  :started_before,
  :started_after,
  :closed_before,
  :closed_after,
]

Instance Attribute Summary collapse

Attributes included from Core::Model

#config

Instance Method Summary collapse

Methods included from Core::Collection::Limitable

#each_batch

Methods included from Core::Collection

#each_batch, #enum, #first, #in_groups_of, #page

Methods included from Core::Model

#client, #config_prefix, #inspect

Constructor Details

#initialize(domain, options = {}) ⇒ WorkflowExecutionCollection

Returns a new instance of WorkflowExecutionCollection.



47
48
49
50
51
52
53
54
55
56
57
58
59
60
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 47

def initialize domain, options = {}

  @domain = domain

  @reverse_order = !!options[:reverse_order]

  @defaults = FILTERS.inject({}) do |defaults,opt|
    defaults[opt] = options[opt] if options.has_key?(opt)
    defaults
  end

  super

end

Instance Attribute Details

#domainDomain (readonly)

Returns the domain this execution was started in.

Returns:

  • (Domain)

    Returns the domain this execution was started in.



63
64
65
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 63

def domain
  @domain
end

Instance Method Details

#at(workflow_id, run_id) ⇒ WorkflowExecution Also known as: []

Returns the workflow execution with the given workflow_id and run_id.

# get a reference to a single workflow execution
domain.workflow_executions['workflow-id', 'run-id']
domain.workflow_executions.at('workflow-id', 'run-id')

Parameters:

  • workflow_id (String)

    The workflow execution id.

  • run_id (String)

    The workflow execution run id.

Returns:



78
79
80
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 78

def at workflow_id, run_id
  WorkflowExecution.new(domain, workflow_id, run_id)
end

#closed_after(time) ⇒ WorkflowExecutionCollection

Note:

It is not possible to filter by both start time and close time.

Filters workflow executions by their close date.

# executions that closed within the last hour
domain.workflow_executions.closed_after(Time.now - 3600)

Parameters:

  • time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

Returns:

  • (WorkflowExecutionCollection)

    Returns a colleciton that will only enumerate or count executions that closed after the given time.



373
374
375
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 373

def closed_after time
  collection_with(:closed_after => time)
end

#closed_before(time) ⇒ WorkflowExecutionCollection

Note:

It is not possible to filter by both start time and close time.

Filters workflow executions by their close date.

# executions that closed more than an hour ago
domain.workflow_executions.closed_before(Time.now - 3600)

Parameters:

  • time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

Returns:

  • (WorkflowExecutionCollection)

    Returns a colleciton that will only enumerate or count executions that closed before the given time.



354
355
356
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 354

def closed_before time
  collection_with(:closed_before => time)
end

#closed_between(oldest_time, latest_time) ⇒ WorkflowExecutionCollection

Note:

It is not possible to filter by both start time and close time.

Filters workflow executions by their close date.

Parameters:

  • oldest_time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

  • latest_time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

Returns:

  • (WorkflowExecutionCollection)

    Returns a colleciton that will only enumerate or count executions that closed between the given times.



335
336
337
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 335

def closed_between oldest_time, latest_time
  closed_after(oldest_time).closed_before(latest_time)
end

#count(options = {}) ⇒ Count

Note:

You may only pass one of the following options: :workflow_id, :workflow_type, :tagged or :status with a “closed” value (:status with :open is okay).

Note:

This operation is eventually consistent. The results are best effort and may not exactly reflect recent updates and changes.

Returns the number of workflow executions within the domain that meet the specified filtering criteria. Counts can be truncated so you should check the return value.

count = domain.workflow_executions.count
puts(count.truncated? ? "#{count.to_i}+" : count.to_i)

Parameters:

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

Options Hash (options):

  • :status (Symbol)

    Filters workflow executions by the given status. If status is not provided then it defaults to :open unless you pass :closed_between (then it defaults to :closed).

    If :status is anything besides :open or :closed then it may not be passed with :workflow_id, :workflow_type or :tagged.

    Accepted values for :status include:

    • :open

    • :closed

    • :completed

    • :failed

    • :canceled

    • :terminated

    • :continued

    • :timed_out

  • :started_after (Time)

    Filters workflow executions down to those started after the given time.

    You may pass :started_after with :started_before, but not with :closed_after or :closed_before.

  • :started_before (Time)

    Filters workflow executions down to those started before the given time.

    You may pass :started_after with :started_before, but not with :closed_after or :closed_before.

  • :closed_after (Time)

    Filters workflow executions to those closed after the given time.

    • You may pass :closed_after with :closed_before, but not with :started_after or :started_before.

    • This option is invalid when counting or listing open executions.

  • :closed_before (Time)

    Filters workflow executions to those closed before the given time.

    • You may pass :closed_after with :closed_before, but not with :started_after or :started_before.

    • This option is invalid when counting or listing open executions.

  • :workflow_id (String) — default: nil

    If specified, workflow executions are filtered by the provided workflow id.

  • :tagged (String) — default: nil

    Filters workflow executions by the given tag.

  • :workflow_type (WorkflowType, Hash) — default: nil

    Filters workflow executions with the given workflow type. :workflow_type can be a AWS::SimpleWorkflow::WorkflowType object or a hash with a workflow type :name and :version.

Returns:

  • (Count)

    Returns a possibly truncated count of workflow executions.



470
471
472
473
474
475
476
477
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 470

def count options = {}

  open_or_closed, client_opts = handle_options(options)

  client_method = :"count_#{open_or_closed}_workflow_executions"
  response = client.send(client_method, client_opts)
  Count.new(response.data['count'], response.data['truncated'])
end

#each(options = {}) ⇒ nil_or_next_token

Note:

You may only pass one of the following options: :workflow_id, :workflow_type, :tagged or :status with a “closed” value (:status with :open is okay).

Note:

This operation is eventually consistent. The results are best effort and may not exactly reflect recent updates and changes.

Enumerates workflow executions.

Parameters:

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

Options Hash (options):

  • :reverse_order (Boolean)

    Enumerates the workflow execution in reverse chronoloical order if true. The date used will be the execution start time unless filtering by closed before/after (then it will sort by the closed time).

  • :status (Symbol)

    Filters workflow executions by the given status. If status is not provided then it defaults to :open unless you pass :closed_between (then it defaults to :closed).

    If :status is anything besides :open or :closed then it may not be passed with :workflow_id, :workflow_type or :tagged.

    Accepted values for :status include:

    • :open

    • :closed

    • :completed

    • :failed

    • :canceled

    • :terminated

    • :continued

    • :timed_out

  • :started_after (Time)

    Filters workflow executions down to those started after the given time.

    You may pass :started_after with :started_before, but not with :closed_after or :closed_before.

  • :started_before (Time)

    Filters workflow executions down to those started before the given time.

    You may pass :started_after with :started_before, but not with :closed_after or :closed_before.

  • :closed_after (Time)

    Filters workflow executions to those closed after the given time.

    • You may pass :closed_after with :closed_before, but not with :started_after or :started_before.

    • This option is invalid when counting or listing open executions.

  • :closed_before (Time)

    Filters workflow executions to those closed before the given time.

    • You may pass :closed_after with :closed_before, but not with :started_after or :started_before.

    • This option is invalid when counting or listing open executions.

  • :workflow_id (String) — default: nil

    If specified, workflow executions are filtered by the provided workflow id.

  • :tagged (String) — default: nil

    Filters workflow executions by the given tag.

  • :workflow_type (WorkflowType, Hash) — default: nil

    Filters workflow executions with the given workflow type. :workflow_type can be a AWS::SimpleWorkflow::WorkflowType object or a hash with a workflow type :name and :version.

  • :limit (Integer) — default: nil

    The maximum number of items to enumerate from this collection.

  • :next_token (next_token) — default: nil

    Acts as an offset. :next_token may be returned by #each and Core::Collection::Limitable#each_batch when a :limit is provided.

Returns:

  • (nil_or_next_token)

    Returns nil if all items were enumerated. If some items were excluded because of a :limit option then a next_token is returned. Calling an enumerable method on the same collection with the next_token acts like an offset.



489
490
491
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 489

def each options = {}
  super
end

#request_cancel(workflow_id, options = {}) ⇒ nil

Note:

If the :run_id is not specified, the WorkflowExecutionCancelRequested event is recorded in the history of the current open workflow execution with the specified workflow_id in the domain.

Note:

Because this action allows the workflow to properly clean up and gracefully close, it should be used instead of #terminate when possible.

Records a WorkflowExecutionCancelRequested event in the currently running workflow execution identified. This logically requests the cancellation of the workflow execution as a whole. It is up to the decider to take appropriate actions when it receives an execution history with this event.

Parameters:

  • workflow_id (String)

    The id of the workflow execution to cancel.

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

Options Hash (options):

  • :run_id (String) — default: nil

    The run id of the workflow execution to cancel.

Returns:

  • (nil)


140
141
142
143
144
145
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 140

def request_cancel workflow_id, options = {}
  options[:domain] = domain.name
  options[:workflow_id] = workflow_id
  client.request_cancel_workflow_execution(options)
  nil
end

#reverse_orderWorkflowExecutionCollection

Returns a collection that enumerates workflow executions in reverse chronological order. By default exeuctions are enumerated in ascending order of their start or close time (ordered by close time when filtered by #closed_between).

# get the latest execution
execution = domain.workflow_executions.reverse_order.first

Returns:



388
389
390
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 388

def reverse_order
  collection_with(:reverse_order => true)
end

#signal(workflow_id, signal_name, options = {}) ⇒ nil

Records a WorkflowExecutionSignaled event in the workflow execution history and creates a decision task for the workflow execution.

domain.signal_workflow_execution('workflowid', 'newdata', :input => '...')

Parameters:

  • workflow_id (String)

    The id of the workflow execution to signal.

  • signal_name (String)

    The name of the signal. This name must be meaningful to the target workflow.

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

Options Hash (options):

  • :input (String) — default: nil

    Data to attach to the WorkflowExecutionSignaled event in the target workflow execution’s history.

  • :run_id (String) — default: nil

    The run id of the workflow execution to signal.

    If :run_id is not specified, then the WorkflowExecutionSignaled event is recorded in the history of the current open workflow with the matching workflow_id in the domain.

Returns:

  • (nil)


108
109
110
111
112
113
114
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 108

def signal workflow_id, signal_name, options = {}
  options[:domain] = domain.name
  options[:workflow_id] = workflow_id
  options[:signal_name] = signal_name
  client.signal_workflow_execution(options)
  nil
end

#started_after(time) ⇒ WorkflowExecutionCollection

Note:

It is not possible to filter by both start time and close time.

Filters workflow executions by their start date.

# executions that started within the last hour
domain.workflow_executions.started_after(Time.now - 3600)

Parameters:

  • time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

Returns:

  • (WorkflowExecutionCollection)

    Returns a colleciton that will only enumerate or count executions that started after the given time.



315
316
317
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 315

def started_after time
  collection_with(:started_after => time)
end

#started_before(time) ⇒ WorkflowExecutionCollection

Note:

It is not possible to filter by both start time and close time.

Filters workflow executions by their start date.

# executions that started at least an hour ago
domain.workflow_executions.started_before(Time.now - 3600)

Parameters:

  • time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

Returns:

  • (WorkflowExecutionCollection)

    Returns a colleciton that will only enumerate or count executions that started before the given time.



296
297
298
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 296

def started_before time
  collection_with(:started_before => time)
end

#started_between(oldest_time, latest_time) ⇒ WorkflowExecutionCollection

Note:

It is not possible to filter by both start time and close time.

Filters workflow executions by their start date.

Parameters:

  • oldest_time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

  • latest_time (Time, DateTime, Date, Integer, String)

    Should be one of the listed types. Integers are treated as timestamps and strings are parsed by DateTime.

Returns:

  • (WorkflowExecutionCollection)

    Returns a colleciton that will only enumerate or count executions that have start times that fall within the given range.



277
278
279
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 277

def started_between oldest_time, latest_time
  started_after(oldest_time).started_before(latest_time)
end

#tagged(tag) ⇒ WorkflowExecutionCollection

Returns a collection that will only enumerate or count executions that have the given tag.

Parameters:

  • tag (String)

    A tag to filter workflow executions with.

Returns:



257
258
259
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 257

def tagged tag
  collection_with(:tagged => tag)
end

#terminate(workflow_id, options = {}) ⇒ nil

Note:

If the workflow execution was in progress, it is terminated immediately.

Note:

If a :run_id is not specified, then the WorkflowExecutionTerminated event is recorded in the history of the current open workflow with the matching workflowId in the domain.

Note:

You should consider canceling the workflow execution instead because it allows the workflow to gracefully close while terminate does not.

Records a WorkflowExecutionTerminated event and forces closure of the workflow execution identified. The child policy, registered with the workflow type or specified when starting this execution, is applied to any open child workflow executions of this workflow execution.

Parameters:

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

Options Hash (options):

  • :child_policy (Symbol) — default: nil

    If set, specifies the policy to use for the child workflow executions of the workflow execution being terminated. This policy overrides the default child policy. Valid policies include:

    • :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.

  • :details (String)

    Optional details for terminating the workflow execution.

  • :reason (String)

    An optional descriptive reason for terminating the workflow execution.

  • :run_id (String)

    The run id of the workflow execution to terminate. If a :run_id is not provided, then a WorkflowExecutionTerminated event is recorded in the history of the current open workflow with the matching workflow id in the domain.

Returns:

  • (nil)


198
199
200
201
202
203
204
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 198

def terminate workflow_id, options = {}
  options[:domain] = domain.name
  options[:workflow_id] = workflow_id
  upcase_opts(options, :child_policy)
  client.terminate_workflow_execution(options)
  nil
end

#with_status(status) ⇒ WorkflowExecutionCollection

Returns a collection that will only enumerate or count executions of the given status.

Parameters:

  • status (Symbol)

    Causes the returned collection to filter executions by the given status. Accepted statuses include:

    • :open

    • :closed

    • :completed

    • :failed

    • :canceled

    • :terminated

    • :continued

    • :timed_out

    If :status is anything besides :open or :closed then it may not be used in combination with workflow_id, workflow_type or tagged.

Returns:



226
227
228
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 226

def with_status status
  collection_with(:status => status)
end

#with_workflow_id(workflow_id) ⇒ WorkflowExecutionCollection

Returns a collection that will only enumerate or count executions that have the given workflow_id.

Parameters:

  • workflow_id (String)

Returns:



236
237
238
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 236

def with_workflow_id workflow_id
  collection_with(:workflow_id => workflow_id)
end

#with_workflow_type(workflow_type) ⇒ WorkflowExecutionCollection

Returns a collection that will only enumerate or count executions that have the given workflow_type.

Parameters:

Returns:

  • (WorkflowExecutionCollection)

    Returns a collection that will only enumerate or count executions that have the given workflow_type.



247
248
249
# File 'lib/aws/simple_workflow/workflow_execution_collection.rb', line 247

def with_workflow_type workflow_type
  collection_with(:workflow_type => workflow_type)
end