Workflow basics - Ruby SDK

View Markdown

Develop a Workflow

Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a Workflow Definition.

In the Temporal Ruby SDK programming model, Workflows are defined as classes.

Have the Workflow class extend Temporalio::Workflow::Definition to define a Workflow.

The entrypoint is the execute method.

class MyWorkflow < Temporalio::Workflow::Definition
  def execute(name)
    Temporalio::Workflow.execute_activity(
      MyActivity,
      { greeting: 'Hello', name: },
      start_to_close_timeout: 100
    )
  end
end

Temporal Workflows may have any number of custom parameters. However, we strongly recommend that hashes or objects are used as parameters, so that the object's individual fields may be altered without breaking the signature of the Workflow.

Customize Workflow Type

Workflows have a Type that are referred to as the Workflow name.

The following examples demonstrate how to set a custom name for your Workflow Type.

You can customize the Workflow name with a custom name in a workflow_name class method call on the class. The Workflow name defaults to the unqualified class name.

class MyWorkflow < Temporalio::Workflow::Definition
  # Customize the name
  workflow_name :MyDifferentWorkflowName

  def execute(name)
    Temporalio::Workflow.execute_activity(
      MyActivity,
      { greeting: 'Hello', name: },
      start_to_close_timeout: 100
    )
  end
end

Use Workflow constructors

Workflow constructors are useful if you have message handlers that need access to Workflow input: see Initializing the Workflow first. The workflow_init class method above initialize gives it access to Workflow input. When you use the workflow_init on your constructor, you give the constructor the same Workflow parameters as your execute method.

The SDK will then ensure that your constructor receives the Workflow input arguments that the Client sent. The Workflow input arguments are also passed to your execute method. That always happens, whether or not you use the workflow_init class method above initialize.

Here's an example. The constructor and execute must have the same parameters with the same types:

class WorkflowInitWorkflow < Temporalio::Workflow::Definition
  workflow_init
  def initialize(input)
    @name_with_title = "Knight #{input['name']}"
  end

  def execute(input)
    Temporalio::Workflow.wait_condition { @title_has_been_checked }
    "Hello, #{@name_with_title}"
  end
end

Workflow logic requirements

Temporal Workflows must be deterministic, which includes Ruby Workflows. This means there are several things Workflows cannot do such as:

• Perform IO (network, disk, stdio, etc)
• Access/alter external mutable state
• Do any threading
• Do anything using the system clock (e.g. Time.Now)
• Make any random calls
• Make any not-guaranteed-deterministic calls

To prevent illegal Workflow calls, a call tracer is put on the Workflow thread that raises an exception if any illegal calls are made. Which calls are illegal is configurable in the Worker options.