Ruby SDK developer guide

Support, stability, and dependency info

The Temporal Ruby SDK is currently in Public Preview.

Ruby SDK RESOURCES

Build Temporal Applications with the Ruby SDK.

Temporal Ruby Technical Resources:

• Ruby SDK Code Samples
• Ruby API Documentation
• Ruby SDK GitHub

Get Connected with the Temporal Ruby Community:

• Temporal Ruby Community Slack
• Ruby SDK Forum

Core Application

Use the essential components of a Temporal Application (Workflows, Activities, and Workers) to build and run a Temporal application.

• Develop a basic Workflow Definition: Workflows are the fundamental unit of a Temporal Application, and it all starts with the development of a Workflow Definition.
• Develop a basic Activity Definition: One of the primary things that Workflows do is orchestrate the execution of Activities.
• Start an Activity from a Workflow: Calls to spawn Activity Executions are written within a Workflow Definition.
• Run a Worker Process: The Worker Process is where Workflow Functions and Activity Functions are executed.
• Set a Dynamic Workflow: Set a Workflow that can be invoked dynamically at runtime.
• Set a Dynamic Activity: Set an Activity that can be invoked dynamically at runtime.

Temporal Client

Connect to a Temporal Service and start a Workflow Execution.

• Create a Temporal Client: Learn to instantiate and configure a client to interact with the Temporal Service.
• Connect to Temporal Cloud: Securely connect to the Temporal Cloud for a fully managed service.
• Start a Workflow: Initiate Workflows seamlessly via the Ruby SDK.
• Get Workflow results: Retrieve and process the results of your Workflows efficiently.

Testing

Set up the testing suite and test Workflows and Activities.

• Test frameworks: Testing provides a framework to facilitate Workflow and integration testing.
• Testing Workflows: Ensure the functionality and reliability of your Workflows.
• Testing Activities: Validate the execution and outcomes of your Activities.
• Replay test: Replay recreates the exact state of a Workflow Execution.

Failure detection

Explore how your application can detect failures using timeouts and automatically attempt to mitigate them with retries.

• Workflow timeouts: Each Workflow timeout controls the maximum duration of a different aspect of a Workflow Execution.
• Workflow retries: A Workflow Retry Policy can be used to retry a Workflow Execution in the event of a failure.
• Activity timeouts: Each Activity timeout controls the maximum duration of a different aspect of an Activity Execution.
• Set an Activity Retry Policy: Define retry logic for Activities to handle failures.
• Heartbeat an Activity: An Activity Heartbeat is a ping from the Worker that is executing the Activity to the Temporal Service.
• Heartbeat Timeout: A Heartbeat Timeout works in conjunction with Activity Heartbeats.

Workflow message passing

Send messages to and read the state of Workflow Executions.

Signals

• Define Signal: A Signal is a message sent to a running Workflow Execution.
• Send a Signal from a Temporal Client: Send a Signal to a Workflow from a Temporal Client.
• Send a Signal from a Workflow: Send a Signal to another Workflow from within a Workflow, this would also be called an External Signal.
• Signal-With-Start: Start a Workflow and send it a Signal in a single operation used from the Client.
• Dynamic Handler: Dynamic Handlers provide flexibility to handle cases where the names of Workflows, Activities, Signals, or Queries aren't known at run time.
• Set a Dynamic Signal: A Dynamic Signal in Temporal is a Signal that is invoked dynamically at runtime if no other Signal with the same input is registered.

Queries

• Define a Query: A Query is a synchronous operation that is used to get the state of a Workflow Execution.
• Send Queries: Queries are sent from the Temporal Client.
• Set a Dynamic Query: A Dynamic Query in Temporal is a Query that is invoked dynamically at runtime if no other Query with the same name is registered.

Updates

• Define an Update: An Update is an operation that can mutate the state of a Workflow Execution and return a response.
• Send an Update: An Update is sent from the Temporal Client.

Interrupt a Workflow

Interrupt a Workflow Execution with a Cancel or Terminate action.

• Cancel a Workflow: Interrupt a Workflow Execution and its Activities through Workflow cancellation.
• Terminate a Workflow: Interrupt a Workflow Execution and its Activities through Workflow termination.

Asynchronous Activity completion

Complete Activities asynchronously.

• Asynchronous Activity: Asynchronous Activity completion enables the Activity Function to return without the Activity Execution completing.

Versioning

Change Workflow Definitions without causing non-deterministic behavior in running Workflows.

• Use the Ruby SDK Patching API: Patching Workflows using the Ruby SDK.

Observability

Configure and use the Temporal Observability APIs.

• Emit Metrics: Each Temporal SDK is capable of emitting an optional set of metrics from either the Client or the Worker process.
• Set up Tracing: Explains how the Go SDK supports tracing and custom context propagation.
• Log from a Workflow: Send logs and errors to a logging service, so that when things go wrong, you can see what happened.
• Use Visibility APIs: The term Visibility, within the Temporal Platform, refers to the subsystems and APIs that enable an operator to view Workflow Executions that currently exist within a Terminal Service.

Debugging

Explore various ways to debug your application.

• Debug in a development environment: In addition to the normal development tools of logging and a debugger, you can also see what’s happening in your Workflow by using the Web UI and the Temporal CLI.
• Debug in a development production: Debug production Workflows using the Web UI, the Temporal CLI, Replays, Tracing, or Logging.

Schedules

Run Workflows on a schedule and delay the start of a Workflow.

• Schedule a Workflow
  • Create a Scheduled Workflow: Create a new schedule for a scheduled Workflow.
  • Backfill a Scheduled Workflow: Backfills a past time range of actions for a scheduled Workflow.
  • Delete a Scheduled Workflow: Deletes a schedule for a scheduled Workflow.
  • Describe a Scheduled Workflow: Get schedule configuration and current state for a scheduled Workflow.
  • List a Scheduled Workflow: List a schedule for a scheduled Workflow.
  • Pause a Scheduled Workflow: Pause a schedule for a scheduled Workflow.
  • Trigger a Scheduled Workflow: Triggers an immediate action for a scheduled Workflow.
  • Update a Scheduled Workflow: Updates a schedule with a new definition for a scheduled Workflow.
• Use Start Delay: Start delay functionality if you need to delay the execution of the Workflow without the need for regular launches.

Data encryption

Use compression, encryption, and other data handling by implementing custom converters and codecs.

• Use a custom Payload Codec: Create a custom PayloadCodec implementation and define your encryption/compression and decryption/decompression logic.
• Use a custom Payload Converter: A custom data converter can be set via the DataConverter option when creating a client.

Durable Timers

Use Timers to make a Workflow Execution pause or "sleep" for seconds, minutes, days, months, or years.

• Sleep: A Timer lets a Workflow sleep for a fixed time period.

Child Workflows

Explore how to spawn a Child Workflow Execution and handle Child Workflow Events.

• Start a Child Workflow Execution: A Child Workflow Execution is a Workflow Execution that is scheduled from within another Workflow using a Child Workflow API.
• Set a Parent Close Policy: A Parent Close Policy determines what happens to a Child Workflow Execution if its Parent changes to a Closed status.

Continue-As-New

Continue the Workflow Execution with a new Workflow Execution using the same Workflow ID.

• Continue-As-New: Continue-As-New enables a Workflow Execution to close successfully and create a new Workflow Execution in a single atomic operation if the number of Events in the Event History is becoming too large.