Skip to main content

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.

The SDK provides replay-safe alternatives for common needs.

Logging​

Use Temporalio::Workflow.logger instead of puts or a Logger you create yourself. The Logger class is on the default illegal call list, and the SDK logger appends Workflow details to every log and skips logging during replay:

class MyWorkflow < Temporalio::Workflow::Definition
  def execute(name)
    Temporalio::Workflow.logger.info("Starting workflow for #{name}")
    # ...
  end
end

For logger configuration, see Observability: Log from a Workflow.

Random numbers and UUIDs​

Use Temporalio::Workflow.random to get a Random instance seeded per Workflow Execution. The SDK requires random/formatter, so this instance also has the standard library's Random::Formatter#uuid method. Use it instead of SecureRandom.uuid:

value = Temporalio::Workflow.random.rand(1..100)
unique_id = Temporalio::Workflow.random.uuid

Don't use SecureRandom, Kernel#rand, Kernel#srand, or Random.new in Workflow code. They're on the default illegal call list, and the call tracer raises a Temporalio::Workflow::NondeterminismError when it detects them.

Access the instance each time you need it rather than storing it in an instance variable. The SDK may recreate it with a different seed, such as after a Workflow reset.

Current time​

Use Temporalio::Workflow.now instead of Time.now. It returns the UTC time of the last Workflow Task, which is consistent across replays:

current_time = Temporalio::Workflow.now

To wait, use Temporalio::Workflow.sleep instead of Kernel#sleep.

Detecting replay (advanced)​

Use Temporalio::Workflow::Unsafe.replaying? to guard code that should only run on the first execution, such as emitting metrics or sending external notifications from an Interceptor.

caution

Never use this to affect Workflow business logic. Branching on replay status breaks determinism.

unless Temporalio::Workflow::Unsafe.replaying?
  emit_metric('workflow_started', 1)
end

If your goal is to always take action when something new is happening, check that Temporalio::Workflow::Unsafe.replaying_history_events? is false instead. That is false during read-only operations like Queries and Update validators. This is what the SDK's built-in logger uses internally.