Specifying Workflow and Activity Options

The AWS Flow Framework for Ruby allows you to set options that affect how your workflows and activities are run. This topic lists each of the options that you can set, as well as providing detail about how, and when, you can set them.

Activity Registration Options#

The following registration options can be set only when declaring an activity type. Workers will use these values to register the type with Amazon SWF. Once these values are set, you must set a different version (essentially declaring a new type) if you want to change any of the registration options.

default_task_heartbeat_timeout

The time, in seconds, within which an activity must record a heartbeat progress notification (by calling record_activity_heartbeat in the ActivityExecutionContext class).

Optional. The default value is "NONE", which will allow tasks to run indefinitely before reporting progress.

default_task_list

The name of the task list used for this activity type.

Optional. The default value is "USE_WORKER_TASK_LIST", a restricted string that, when used, will cause the activity to use the same task list that the activity worker is polling on.

default_task_priority

The task priority to set, from -2147483647 to 2147483647, where higher numbers indicate higher priority. Higher-priority tasks are delivered before lower-priority tasks on the same task list. Tasks that are not assigned a priority are given the default value of 0. For more information, see Setting Task Priority.

Optional. The default value is 0.

default_task_schedule_to_close_timeout

The maximum duration, in seconds, of an activity execution from the time it is scheduled to when it is marked as complete.

Optional. The default value is "NONE"; the activity has no restriction on when it must complete after being scheduled.

default_task_schedule_to_start_timeout

The maximum duration, in seconds, from the time when the activity is scheduled to when it starts.

Optional. The default value is "NONE"; the activity has no restriction on when it must start after being scheduled.

default_task_start_to_close_timeout

The maximum duration, in seconds, of the activity execution from the time it starts to when it is marked as complete.

Optional. The default value is "NONE"; the activity has no restriction on when it must complete after being started.

version

The activity version to use. This value can be set only when declaring a activity type.

Required. You must always set version when you register a activity type, or when changing any activity registration options.

Workflow Registration Options#

The following registration options can be set only when declaring a workflow type. Workers will use these values to register the type with Amazon SWF. Once these values are set, you must set a different version (essentially declaring a new type) if you want to change any of the registration options.

default_child_policy

The optional policy to use for the child workflow executions when a workflow execution of this type is terminated.

Optional. The default value is "TERMINATE", which will automatically terminate all child executions when the parent workflow is terminated.

default_execution_start_to_close_timeout

The maximum duration, in seconds, of a workflow execution from the time it starts to when it is marked as complete.

Required. There is no default value. You must set this value either during registration or when executing the workflow.

default_task_list

The name of the default task list used for this workflow type.

Optional. The default value is "USE_WORKER_TASK_LIST", a restricted string that, when used, will cause the workflow to use the same task list that the workflow worker is polling on.

default_task_priority

The task priority to set, from -2147483647 to 2147483647, where higher numbers indicate higher priority. Higher-priority tasks are delivered before lower-priority tasks on the same task list. Tasks that are not assigned a priority are given the default value of 0. For more information, see Setting Task Priority.

Optional. The default value is 0.

default_task_start_to_close_timeout

The maximum duration, in seconds, of a workflow task from the time it starts to when it is complete.

Optional. The default value is 30.

version

The workflow version to use. This value can be set only when declaring a workflow type.

Required. You must always set version when you register a workflow type, or when changing any workflow registration options.

Activity Runtime Options#

These options can be set when declaring an activity, initializing a new activity client or when scheduling an activity. They will override any default options with the same name.

data_converter
The data converter class to use to interpret data delivered from Amazon SWF. If not specified, then YAMLDataConverter will be used by default.
heartbeat_timeout
The time, in seconds, within which an activity must record a heartbeat progress notification (by calling record_activity_heartbeat in the ActivityExecutionContext class).
input
Input data that will be passed to the activity when it starts. You can also pass input directly as a parameter when scheduling the activity.
manual_completion
Set to true when you have a human task (an activity that will be completed manually). In this case, the activity will return immediately after starting, but it will not complete automatically when it returns.
schedule_to_close_timeout
The maximum duration, in seconds, of an activity execution from the time it is scheduled to when it is marked as complete.
schedule_to_start_timeout
The maximum duration, in seconds, from the time when the activity is scheduled to when it starts.
start_to_close_timeout
The maximum duration, in seconds, of the activity execution from the time it starts to when it is marked as complete.
task_list
The name of the task list used for this activity.
task_priority
The task priority to set, from -2147483647 to 2147483647, where higher numbers indicate higher priority. Higher-priority tasks are delivered before lower-priority tasks on the same task list. Tasks that are not assigned a priority are given the default value of 0. For more information, see Setting Task Priority.

Workflow Runtime Options#

These options can be set when declaring a workflow type, initializing a new workflow client or when starting the workflow. They will override default options with the same name.

child_policy
The optional policy to use for the child workflow executions when a workflow execution of this type is terminated.
data_converter
The data converter class to use to interpret data delivered from Amazon SWF. If not specified, then YAMLDataConverter will be used by default.
execution_method

The workflow method to call when the workflow begins executing. By default, this method is defined when you use the workflow method in the Workflows class to register your workflows.

This option is not required; it is used only if you start a workflow using the start_execution method on the client in your workflow class. By default, the client will select the first defined workflow in that class.

This will not be used if you start a workflow execution by calling the workflow method directly from the client (for example, workflow_client.workflow_a) or by calling send (for example, workflow_client.send(:workflow_a)).

execution_start_to_close_timeout
The maximum duration, in seconds, of a workflow execution from the time it starts to when it is marked as complete.
input
Input data that will be passed to the workflow upon execution. You can also pass input directly as a parameter when starting the workflow.
tag_list
A list of tags to associate with the workflow. This is an empty list by default.
task_list
The name of the default task list used for this workflow.
task_priority
The task priority to set, from -2147483647 to 2147483647, where higher numbers indicate higher priority. Higher-priority tasks are delivered before lower-priority tasks on the same task list. Tasks that are not assigned a priority are given the default value of 0. For more information, see Setting Task Priority.
task_start_to_close_timeout
The maximum duration, in seconds, of a workflow task from the time it starts to when it is complete.
workflow_id
An optional workflow ID. If you don't set it, the AWS Flow Framework for Ruby will choose one for you.

How to Set Options#

You can set options for activities and workflows at the following times:

  • At type declaration – when you declare a new type, you can specify default options that will be used for all activities/workflows of that type unless options are overridden on the client or at scheduling.
  • On an activity/workflow client – if you set activity options on an activity client, then any activities that are scheduled and launched with that client will inherit the options that it holds. These will act as overrides for any options set at type declaration.
  • At scheduling – when you schedule a workflow or activity for execution, you can specify options that will override any that were set at type declaration or on the client.

Setting Registration (Type) Options#

To set options in activity or workflow declarations that will be used when the type is registered with Amazon SWF, pass them as a block when you declare the activity or workflow using the activity or workflow methods in Activities or Workflows, respectively.

Using this method, you can send the same block of options to activities that share settings. For example, to set activity registration options:

class BookingActivity
  extend AWS::Flow::Activities

  activity :reserve_car, :reserve_air, :send_confirmation do
    {
      version: "1.0",
      default_task_list: "activity_tasklist",
      default_task_schedule_to_start_timeout: 30,
      default_task_start_to_close_timeout: 30
    }
  end

Workflow registration options are set the same way:

class BookingWorkflow
  extend AWS::Flow::Workflows

  workflow :make_booking do
    {
      version: "1.0",
      default_task_list: "workflow_tasklist",
      default_execution_start_to_close_timeout: 120
    }
  end

Important

Once an activity or workflow type is registered, its default (registration) options cannot be changed. If you need to change the default options of a registered activity or workflow type, you will need to register a new type with either a different name or different version to differentiate it from other activity types.

Setting Both Registration and Runtime Options at Declaration#

You can set both registration and runtime options during declaration. If you do this, then the registration options will be set as the defaults for that type (you will see them if you view the type in the console, and they will be used as defaults for any other clients that use the type).

Any runtime options that you set at declaration, however, will immediately override these type-defining default options, and will be automatically used when scheduling an activity or workflow of that type in your code, unless they are subsequently overridden on the client or when scheduling. You can freely modify runtime options at type declaration without any need to update the version value for the type.

In effect, you can declare a type with different runtime options in different parts of your code, as long as you don't change any of the type's registration options. If you do, you will need to also specify a new version.

Setting Options on the Client#

If you set options when creating your workflow or activity clients, they will override any options set at type declaration. For example:

activity_client(:my_activity_client) {
  {
    heartbeat_timeout: 30,
    start_to_close_timeout: 300
  }
}

The same technique is used to set workflow client options:

swf = AWS::SimpleWorkflow.new
domain = swf.domains['MyDomain']

workflow_client = AWS::Flow::workflow_client(swf, domain) {
  {
    task_list: 'workflow_task_list',
    execution_start_to_close_timeout: 3600
  }
}

You can also use the from_class: attribute to copy options from another class. Any options that are set by the class you specify will override those set when the activity was declared (default options).

activity_client(:client) { { from_class: "BookingActivity" } }

Copying Client Options Using with_opts#

You can use the with_opts method available in the GenericClient class to create a new client that copies options from an existing client, overriding them with options that are passed to the with_opts method in a hash.

Setting Options at Scheduling#

If you set options when an activity is scheduled or when starting a workflow, the values will override those that are set on the client and any that were set at type declaration.

To set options during activity scheduling, pass the options block to the activity client's schedule_activity method or when calling the activity method directly from the client:

file_client.process_file(local_source, local_target) do
  { task_list: "new_activity_task_list" }
end

Setting workflow options when starting a workflow is similar:

workflow_client.start_execution() {
  {
    task_list: "new_workflow_task_list",
    tag_list: [ "orderinfo", "web" ]
  }
}

Setting Other Types of Options#

While this topic has focused on options that you can set on workflows and activities, there are options for other classes in the AWS Flow Framework for Ruby. For information about setting these options, refer to the sections in which they are discussed: