Hello World

To introduce you to programming with the AWS Flow Framework for Ruby, we'll begin with a variant of the famous "Hello, World" application. This version of Hello World will use Amazon SWF to schedule and run an activity, which implements some work to be done.

The complete code for the example is presented in this topic, but you will also find it in the awslabs/aws-flow-ruby-samples repository on GitHub along with many other examples of programming with the AWS Flow Framework for Ruby.

Prerequisites#

This example assumes that you meet the following prerequisites:

  • Ruby and the AWS Flow Framework for Ruby (at least version 2.4.0) are installed as described in Setting Up.
  • Your AWS credentials are configured as described in Providing AWS Credentials.

Create an Activity#

An activity represents a single unit of work. At its most basic, an activity is a simple Ruby method that is housed within a class. For this example, we'll create a single activity called hello.

To create the "hello" activity:

  1. Open a command-line (terminal) window and create a new file, hello.rb.

  2. Add the following code:

    class HelloWorld
      def hello(input)
        "Hello #{input[:name]}!"
      end
    end
    

The method hello is our activity implementation—it prints a greeting customized by the value of the input parameter, which is provided to the activity by Amazon SWF when the activity is run.

Generate the Application#

You can use the aws-flow-utils command to automatically generate an application skeleton for you based on the activity you just created. For this tutorial, we will create a locally-run application, but you can also create application skeletons ready for use with Elastic Beanstalk. For more information, see Deploying Workflows with Elastic Beanstalk.

To create an Amazon SWF application with aws-flow-utils:

  • Open a command-line (terminal) window and type:

    aws-flow-utils -c local -n HelloWorld -a hello.rb -A HelloWorld
    

An Amazon SWF application configured to use the AWS Flow Framework for Ruby will be created for you in the local directory, called HelloWorld. Here is the layout of the project that will be created:

HelloWorld/
 |-- Gemfile
 |-- flow/
 |   |-- activities.rb
 |   |-- hello.rb
 |   `-- workflows.rb
 `-- worker.json

This is a standard layout for AWS Flow Framework for Ruby applications: a flow directory that contains your activity and workflow classes and methods, and a worker.json configuration file used to spawn workers.

Start an Activity Worker#

To run the hello activity and provide it with its necessary input data, we need to start at least one activity worker to receive activity tasks from Amazon SWF. You can start the activity worker right now, and it will begin polling for tasks.

To start the worker:

  • Starting within the HelloWorld directory, run the aws-flow-ruby utility and specify the name of your configuration file:

    aws-flow-ruby -f worker.json
    

The output of this command lists the process IDs of your worker threads:

waiting on workers [10972, 10975] to complete

Your worker is now polling for tasks, but to provide it with tasks to process, you need to start a workflow execution.

Starting a Workflow Execution#

Now that your workers are running, you can start your activity by initiating a workflow execution. This signals to Amazon SWF to begin running your workflow (or in this case, a single activity). You can do this from anywhere: Amazon SWF will communicate with the workers you started to run the HelloWorld.hello activity.

For example, you can use the following script (call it starter.rb) to start the activity:

require 'aws/decider'
AWS::Flow::start("HelloWorld.hello", { name: "AWS Flow Framework!" })

To run this script, open a new command-line window and run it using Ruby:

ruby starter.rb

This will begin executing the hello activity in the background on the worker.

Viewing your Execution with the AWS Management Console#

The application didn't provide any output—how do you know that it ran? When you use the start method to run an activity, Amazon SWF runs it as a workflow execution. Since Amazon SWF keeps a history of all workflow executions that you've started, you can view your activity's progress using the AWS Management Console.

To view your activity's execution history:

  1. Sign in to the AWS Management Console.

  2. Go to the SWF console and select the domain: FlowDefault.

  3. Click Workflow Executions. By default, only active workflow executions are listed.

  4. Perform one of the following actions:

    • If your workflow execution has finished, select an Execution Status of Closed in the Workflow Execution List Parameters view, then click List Executions to refresh the list.
    • If your workflow execution is still running, leave the Execution Status as Active.
  5. Click the Workflow Execution ID associated with your workflow execution to see the details of the workflow execution.

  6. Click the Events tab to see a view of individual workflow events, listed in order from most recent to oldest. Once your workflow execution is complete, you will see a WorkflowExecutionCompleted event at the top of the history.

  7. Click on the date that's associated with the WorkflowExecutionCompleted event to view the event details, which include the result of the workflow execution:

    _images/hello_world-execution_completed.png

Congratulations, you've run your first Amazon SWF workflow using the AWS Flow Framework for Ruby!

Next Steps#

This topic is meant to be only a simple introduction to the way you create workflows with AWS Flow Framework for Ruby. Use the following topics and resources to learn more about the framework:

  • To learn how to create a workflow with multiple activities, see Basic Workflow Example.
  • To learn more about the AWS Flow Framework for Ruby and about how Amazon SWF applications work, see Flow Concepts.
  • For more information about and examples of programming with the AWS Flow Framework for Ruby, see Basic Workflow Programming and Advanced Topics.
  • For information about how you can use the AWS Flow Framework for Ruby with other AWS products, see Working with Other AWS Products.
  • To view and download working examples that demonstrate many of the features and techniques described in this documentation, see the aws-flow-ruby-samples repository on GitHub.