Skip to main content

Temporal Client - Ruby SDK

This page shows how to do the following:

Create a Temporal Client​

A Temporal Client enables you to communicate with the Temporal Service. Communication with a Temporal Service includes, but isn't limited to, the following:

  • Starting Workflow Executions.
  • Sending Signals to Workflow Executions.
  • Sending Queries to Workflow Executions.
  • Getting the results of a Workflow Execution.
  • Providing an Activity Task Token.
caution

A Temporal Client cannot be initialized and used inside a Workflow. However, it is acceptable and common to use a Temporal Client inside an Activity to communicate with a Temporal Service.

When running a Temporal Service locally (such as via Temporal CLI), the number of connection options required is minimal.

Use the connect class method on the Temporalio::Client class to create and connect to a Temporal Client to the Temporal Service.

client = Temporalio::Client.connect('localhost:7233', 'default')

Connect to Temporal Cloud​

How to connect to Temporal Cloud using an API Key​

To use an API key with the Temporal Ruby SDK, you will need to provide additional connection options:

  • Your API Key value
  • Your Namespace and Account id combination, which follows the format <namespace_id>.<account_id>.
  • The endpoint may vary. The most common endpoint used is the gRPC regional endpoint, which follows the format: <region>.<cloud_provider>.api.temporal.io:7233.
  • For Namespaces with High Availability features with API key authentication enabled, use the gRPC Namespace endpoint: <namespace>.<account>.tmprl.cloud:7233. This allows automated failover without needing to switch endpoints.

You can find the Namespace and Account ID, as well as the endpoint, on the Namespaces tab:

The Namespace and Account ID combination on the left, and the regional endpoint on the right

Now, when instantiating a Temporal client in your Ruby SDK code, provide the api_key value.

To create an initial connection:

client = Temporalio::Client.connect(
  '<endpoint>', # Endpoint
  '<namespace_id>.<account_id>', # Namespace
  api_key: '<api_key>',
  tls: true
)

To update an API key, update the value of api_key:

client.connection.api_key = '<updated_api_key>'

How to connect to Temporal Cloud using mTLS​

When you connect to Temporal Cloud, you need to provide additional connection and client options that include the following:

For more information about managing and generating client certificates for Temporal Cloud, see How to manage certificates in Temporal Cloud.

For more information about configuring TLS to secure inter- and intra-network communication for a Temporal Service, see Temporal Customization Samples.

Use the connect static method on the Temporalio::Client class to create and connect to a Temporal Client to the Temporal Service. Specify the tls parameter of the connection options to connect to a Temporal Service with mTLS enabled.

client = Temporalio::Client.connect(
  '<endpoint>', # Endpoint
  '<namespace_id>.<account_id>', # Namespace
  tls: Temporalio::Client::Connection::TLSOptions.new(
    client_cert: File.read('my-client-cert.pem'),
    client_private_key: File.read('my-client-key.pem')
  )
)

Start a Workflow​

To start a Workflow Execution, supply:

  • A Task Queue
  • A Workflow Type
  • Input arguments
  • Workflow options such as Workflow Id

To start a Workflow Execution in Ruby, use either the start_workflow or execute_workflow methods in the Client. You must set a Workflow Id and Task Queue in the parameters given to the method.

result = my_client.execute_workflow(
  MyWorkflow, 'some-input',
  id: 'my-workflow-id', task_queue: 'my-task-queue'
)
puts "Result: #{result}"

Get Workflow results​

Once a Workflow Execution is started, the Workflow Id and Run Id can be used to uniquely identify it.

You can block until the result is available, or retrieve it later using the handle.

You can also use Queries to access Workflow state and results while the Workflow is running.

Use start_workflow or workflow_handle on the Client to return a Workflow handle. Then use the result method to await on the result of the Workflow.

handle = my_client.workflow_handle('my-workflow-id')
result = handle.result
puts "Result: #{result}"