aws-flow-utils"> <strong class="command">aws-flow-ruby</strong> - AWS Flow Framework for Ruby

aws-flow-ruby

aws-flow-ruby (also referred to as the runner) is a command-line utility that you can use to spawn workflow and activity workers according to a specification that you provide in a JSON configuration file. It is provided with the AWS Flow Framework for Ruby beginning with version 1.3.0.

Note

While aws-flow-ruby will start activity and workflow workers, it is not designed to start the workflow execution itself. See Starting a Workflow Execution for more information.

Starting workers with aws-flow-ruby#

To use aws-flow-ruby to launch your activity and workflow workers, provide it with the JSON configuration file as its sole argument:

aws-flow-ruby -f runnerspec.json

The JSON file that you provide must adhere to the format specified in Runner specification file.

Note

The runner will start the workflow and activity workers that are defined in the file, and they'll start polling for tasks. It does not start a workflow execution. You must perform that step separately. For more information, see Tutorial: Hello AWS OpsWorks!.

The runner is configured by passing it a JSON-formatted configuration file. Here is a minimal example, providing only the required fields:

{
  "domain": { "name": "ExampleDomain" },
  "activity_workers": [
    { "task_list": "example_activity_tasklist" }
  ],
  "workflow_workers": [
    { "task_list": "example_workflow_tasklist" }
  ]
}

You do not need to specify either the workflow or activity classes using this minimal setup. The runner will automatically look for the presence of the activities.rb and workflows.rb files in the flow subdirectory in the location that you start aws-flow-ruby, and will use those as the activity and workflow classes, respectively.

If the activities within the activities.rb file are not based on the Activities class, then an Activities class will be generated for you. However, in this case you must explicitly list the class names in the activity_classes option.

Tip

You don't need to implement your activities and workflows in the activities.rb and workflows.rb files. You can use these files to simply require activity and workflow code that is located elsewhere.

If you want to override the use of these files, specify the activity_paths, workflow_paths, and related activity_classes and workflow_classes fields in the runner configuration file.

Runner specification file#

Here is a complete list of the sections and fields that can be set in the runner configuration file.

domain

Provides the domain name that will be used (or registered, if necessary) by aws-flow-ruby, and optionally, the domain retention period. If domain is not provided, then the domain FlowDefault will be used by default.

Parameter Description
name Required. The domain name to register. This domain name must be unique to your account and region (Two domains in different regions that share the same name are still considered to be wholly different domains).
retention_in_days Optional. The number of days for which the workflow history will be preserved. If this is not specified, a default retention period of 7 days is used.

Example

"domain": {
  "name": "MyExampleDomain",
  "retention_in_days": 10
}
activity_paths

Optional. Specifies a list of paths to Ruby source files containing activity classes based on the Activities class.

If not specified, aws-flow-ruby will attempt to load the file flow/activities.rb, which will typically contain require lines that load the activity source files. For example:

require 'lib/helloworld_activity.rb'

The paths that are specified should be relative to the location of the configuration file (where the runner is executed).

Example

"activity_paths": [
  "aws-flow-ruby-samples/Samples/hello_world/lib/helloworld_activity.rb"
]
activity_workers

Specifies a list of activity worker groups to spawn. Each worker takes the following options:

Parameter Description
activity_classes

Optional. A list of activity class names that the activity worker will run.

If not provided, then the activity classes to be run will be auto-discovered by looking in the files specified in the activity_paths member (or, alternatively, flow/activities.rb) for classes that are based on Activities.

Note

Any activities that are not based on AWS::Flow::Activities must be listed here, or they will not be used.
number_of_forks_per_worker

Required on Windows; Optional on other platforms. The number of forked processes that are spawned per activity worker. This sets the number of activity tasks that an activity worker can work on in parallel. If not specified, a default value of 20 will be used.

You can set this to zero (0) to turn forking off, which is required on Windows. See Using the Framework on Microsoft Windows for more information.

number_of_workers Optional. The number of activity workers (AWS::Flow::ActivityWorker) to spawn. For each activity worker spawned, a default workflow implementation (decider) will be generated, as well. If not specified, a default value of 1 will be used. you can override this value in the default_deciders section.
task_list Optional. The task list to use for the activity execution. If this is not specified, then a task list name will be generated for you, based on the name of the first activity class found.

Example

"activity_workers": {
  "number_of_workers": 1,
  "number_of_forks_per_worker": 10,
  "activity_classes": ["HelloWorldActivity"],
  "task_list": "activity_tasklist"
}
default_deciders

Optional. Specifies behavior when the AWS Flow Framework for Ruby automatically generates a workflow implementation for your activities.

A single option can be set, number_of_workers, which sets how many workers are launched. This can be used to override the value set in the activity_workers section.

Example

"default_deciders": {
  "number_of_workers" : 3,
}

Note

Generated workflows and workers use the task list "flow_default_ruby".
workflow_paths

Optional. Specifies a list of paths to Ruby source files containing workflow classes based on the Workflows class.

If not specified, aws-flow-ruby will attempt to load the file flow/workflows.rb, which will typically contain require lines that load the workflow source files. For example:

require 'lib/helloworld_workflow.rb'

The paths that are specified should be relative to the location of the configuration file (where aws-flow-ruby is executed).

Example

"workflow_paths": [
  "aws-flow-ruby-samples/Samples/hello_world/lib/helloworld_workflow.rb"
]
workflow_workers

Required. Specifies a list of workflow worker groups to spawn. These take the following options:

Parameter Description
number_of_workers Optional. The number of workflow workers (AWS::Flow::WorkflowWorker) to spawn. If not specified, a default value of 1 will be used.
task_list Required. The task list to use for the workflow execution.
workflow_classes

Optional. The list of workflow class names that the workflow worker will run.

If not provided, then the workflow classes to be run will be auto-discovered by looking in the files specified in the workflow_paths member (or, alternatively, flow/workflows.rb) for classes that are based on Workflows.

Note

Any workflows that are not based on AWS::Flow::Workflows must be listed here, or they will not be used.

Example

"workflow_workers": {
  "number_of_workers": 1,
  "workflow_classes": ["HelloWorldWorkflow"],
  "task_list": "workflow_tasklist"
}