Skip to main content

Temporal Client - Go SDK feature guide

The pages shows how to do the following:

Connect to development Temporal Service

How to connect to the local Temporal CLI development Temporal Service using the Go SDK

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 you are running a Temporal Service locally (such as the Temporal CLI), the number of connection options you must provide is minimal. Many SDKs default to the local host or IP address and port that Temporalite and Docker Compose serve (127.0.0.1:7233).

Use the Dial() API available in the go.temporal.io/sdk/client package to create a Client.

If you don't provide HostPort, the Client defaults the address and port number to 127.0.0.1:7233, which is the port of the development Temporal Service.

If you don't set a custom Namespace name in the Namespace field, the client connects to the default Namespace.

sample-apps/go/yourapp/gateway/main.go

package main

import (
"context"
"encoding/json"
"log"
"net/http"

"documentation-samples-go/yourapp"

"go.temporal.io/sdk/client"
)

func main() {
// Create a Temporal Client to communicate with the Temporal Service.
// A Temporal Client is a heavyweight object that should be created just once per process.
temporalClient, err := client.Dial(client.Options{
HostPort: client.DefaultHostPort,
})
if err != nil {
log.Fatalln("Unable to create Temporal Client", err)
}
defer temporalClient.Close()
// ...
}

Connect to Temporal Cloud

How to connect to Temporal Cloud using the Go SDK

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.

To connect to and run Workflows through Temporal Cloud, you need 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.

sample-apps/go/cloud/client/main.go

package main

import (
"context"
"crypto/tls"
"encoding/json"
"log"

"documentation-samples-go/cloud"

"go.temporal.io/sdk/client"
)

func main() {
// Get the key and cert from your env or local machine
clientKeyPath := "./secrets/yourkey.key"
clientCertPath := "./secrets/yourcert.pem"
// Specify the host and port of your Temporal Cloud Namespace
// Host and port format: namespace.unique_id.tmprl.cloud:port
hostPort := "<yournamespace>.<id>.tmprl.cloud:7233"
namespace := "<yournamespace>.<id>"
// Use the crypto/tls package to create a cert object
cert, err := tls.LoadX509KeyPair(clientCertPath, clientKeyPath)
if err != nil {
log.Fatalln("Unable to load cert and key pair.", err)
}
// Add the cert to the tls certificates in the ConnectionOptions of the Client
temporalClient, err := client.Dial(client.Options{
HostPort: hostPort,
Namespace: namespace,
ConnectionOptions: client.ConnectionOptions{
TLS: &tls.Config{Certificates: []tls.Certificate{cert}},
},
})
if err != nil {
log.Fatalln("Unable to connect to Temporal Cloud.", err)
}
defer temporalClient.Close()
// ...
}

Start Workflow Execution

How to start a Workflow Execution using the Go SDK

Workflow Execution semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, language-specific contextual data, and Workflow Function parameters.

In the examples below, all Workflow Executions are started using a Temporal Client. To spawn Workflow Executions from within another Workflow Execution, use either the Child Workflow or External Workflow APIs.

See the Customize Workflow Type section to see how to customize the name of the Workflow Type.

A request to spawn a Workflow Execution causes the Temporal Service to create the first Event (WorkflowExecutionStarted) in the Workflow Execution Event History. The Temporal Service then creates the first Workflow Task, resulting in the first WorkflowTaskScheduled Event.

To spawn a Workflow Execution, use the ExecuteWorkflow() method on the Go SDK Client.

The ExecuteWorkflow() API call requires an instance of context.Context, an instance of StartWorkflowOptions, a Workflow Type name, and all variables to be passed to the Workflow Execution. The ExecuteWorkflow() call returns a Future, which can be used to get the result of the Workflow Execution.

package main

import (
// ...

"go.temporal.io/sdk/client"
)

func main() {
temporalClient, err := client.Dial(client.Options{})
if err != nil {
// ...
}
defer temporalClient.Close()
// ...
workflowOptions := client.StartWorkflowOptions{
// ...
}
workflowRun, err := temporalClient.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition, param)
if err != nil {
// ...
}
// ...
}

func YourWorkflowDefinition(ctx workflow.Context, param YourWorkflowParam) (YourWorkflowResponse, error) {
// ...
}

If the invocation process has access to the function directly, then the Workflow Type name parameter can be passed as if the function name were a variable, without quotations.

workflowRun, err := temporalClient.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition, param)

If the invocation process does not have direct access to the statically defined Workflow Definition, for example, if the Workflow Definition is in an un-importable package, or it is written in a completely different language, then the Workflow Type can be provided as a string.

workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, "YourWorkflowDefinition", param)

Set Workflow Task Queue

How to set a Workflow's Task Queue using the Go SDK

In most SDKs, the only Workflow Option that must be set is the name of the Task Queue.

For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name.

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the TaskQueue field, and pass the instance to the ExecuteWorkflow call.

  • Type: string
  • Default: None, this is a required field to be set by the developer
workflowOptions := client.StartWorkflowOptions{
// ...
TaskQueue: "your-task-queue",
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

Set custom Workflow Id

How to set a custom Workflow Id using the Go SDK

Although it is not required, we recommend providing your own Workflow Id that maps to a business process or business entity identifier, such as an order identifier or customer identifier.

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the ID field, and pass the instance to the ExecuteWorkflow call.

  • Type: string
  • Default: System generated UUID
workflowOptions := client.StartWorkflowOptions{
// ...
ID: "Your-Custom-Workflow-Id",
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

Go StartWorkflowOptions reference

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, and pass the instance to the ExecuteWorkflow call.

The following fields are available:

FieldRequiredType
IDNostring
TaskQueueYesstring
WorkflowExecutionTimeoutNotime.Duration
WorkflowRunTimeoutNotime.Duration
WorkflowTaskTimeoutNotime.Duration
WorkflowIDReusePolicyNoWorkflowIdReusePolicy
WorkflowExecutionErrorWhenAlreadyStartedNobool
RetryPolicyNoRetryPolicy
CronScheduleNostring
MemoNomap[string]interface{}
SearchAttributesNomap[string]interface{}

ID

Although it is not required, we recommend providing your own Workflow Id that maps to a business process or business entity identifier, such as an order identifier or customer identifier.

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the ID field, and pass the instance to the ExecuteWorkflow call.

  • Type: string
  • Default: System generated UUID
workflowOptions := client.StartWorkflowOptions{
// ...
ID: "Your-Custom-Workflow-Id",
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

TaskQueue

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the TaskQueue field, and pass the instance to the ExecuteWorkflow call.

  • Type: string
  • Default: None; this is a required field to be set by the developer
workflowOptions := client.StartWorkflowOptions{
// ...
TaskQueue: "your-task-queue",
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

WorkflowExecutionTimeout

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the WorkflowExecutionTimeout field, and pass the instance to the ExecuteWorkflow call.

  • Type: time.Duration
  • Default: Unlimited
workflowOptions := client.StartWorkflowOptions{
// ...
WorkflowExecutionTimeout: time.Hours * 24 * 365 * 10,
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

WorkflowRunTimeout

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the WorkflowRunTimeout field, and pass the instance to the ExecuteWorkflow call.

workflowOptions := client.StartWorkflowOptions{
WorkflowRunTimeout: time.Hours * 24 * 365 * 10,
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

WorkflowTaskTimeout

Create an instance of StartWorkflowOptions from the go.temporal.io/sdk/client package, set the WorkflowTaskTimeout field, and pass the instance to the ExecuteWorkflow call.

  • Type: time.Duration
  • Default: time.Seconds * 10
workflowOptions := client.StartWorkflowOptions{
WorkflowTaskTimeout: time.Second * 10,
//...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

WorkflowIDReusePolicy

Set a value from the go.temporal.io/api/enums/v1 package.

workflowOptions := client.StartWorkflowOptions{
WorkflowIdReusePolicy: enums.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE,
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

WorkflowExecutionErrorWhenAlreadyStarted

  • Type: bool
  • Default: false
workflowOptions := client.StartWorkflowOptions{
WorkflowExecutionErrorWhenAlreadyStarted: false,
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

RetryPolicy

Create an instance of a RetryPolicy from the go.temporal.io/sdk/temporal package and provide it as the value to the RetryPolicy field of the instance of StartWorkflowOptions.

retrypolicy := &temporal.RetryPolicy{
InitialInterval: time.Second,
BackoffCoefficient: 2.0,
MaximumInterval: time.Second * 100,
}
workflowOptions := client.StartWorkflowOptions{
RetryPolicy: retrypolicy,
// ...
}
workflowRun, err := temporalClient.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

CronSchedule

  • Type: string
  • Default: None
workflowOptions := client.StartWorkflowOptions{
CronSchedule: "15 8 * * *",
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

Sample

Memo

  • Type: map[string]interface{}
  • Default: Empty
workflowOptions := client.StartWorkflowOptions{
Memo: map[string]interface{}{
"description": "Test search attributes workflow",
},
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

SearchAttributes

How to set Workflow Execution Search Attributes in Go

  • Type: map[string]interface{}
  • Default: Empty.

These are the corresponding Search Attribute value types in Go:

  • Keyword = string
  • Int = int64
  • Double = float64
  • Bool = bool
  • Datetime = time.Time
  • Text = string
searchAttributes := map[string]interface{}{
"CustomIntField": 1,
"MiscData": "yellow",
}
workflowOptions := client.StartWorkflowOptions{
SearchAttributes: searchAttributes,
// ...
}
workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition)
if err != nil {
// ...
}

Get Workflow results

How to get the results of a Workflow Execution using the Go SDK

If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id.

The Workflow Id, Run Id, and Namespace may be used to uniquely identify a Workflow Execution in the system and get its result.

It's possible to both block progress on the result (synchronous execution) or get the result at some other point in time (asynchronous execution).

In the Temporal Platform, it's also acceptable to use Queries as the preferred method for accessing the state and results of Workflow Executions.

The ExecuteWorkflow call returns an instance of WorkflowRun, which is the workflowRun variable in the following line.

 workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, app.YourWorkflowDefinition, param)
if err != nil {
// ...
}
// ...
}

The instance of WorkflowRun has the following three methods:

  • GetWorkflowID(): Returns the Workflow Id of the invoked Workflow Execution.
  • GetRunID(): Always returns the Run Id of the initial Run (See Continue As New) in the series of Runs that make up the full Workflow Execution.
  • Get: Takes a pointer as a parameter and populates the associated variable with the Workflow Execution result.

To wait on the result of Workflow Execution in the same process that invoked it, call Get() on the instance of WorkflowRun that is returned by the ExecuteWorkflow() call.

 workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, YourWorkflowDefinition, param)
if err != nil {
// ...
}
var result YourWorkflowResponse
err = workflowRun.Get(context.Background(), &result)
if err != nil {
// ...
}
// ...
}

However, the result of a Workflow Execution can be obtained from a completely different process. All that is needed is the Workflow Id. (A Run Id is optional if more than one closed Workflow Execution has the same Workflow Id.) The result of the Workflow Execution is available for as long as the Workflow Execution Event History remains in the system.

Call the GetWorkflow() method on an instance of the Go SDK Client and pass it the Workflow Id used to spawn the Workflow Execution. Then call the Get() method on the instance of WorkflowRun that is returned, passing it a pointer to populate the result.

 // ...
workflowID := "Your-Custom-Workflow-Id"
workflowRun := c.GetWorkflow(context.Background, workflowID)

var result YourWorkflowResponse
err = workflowRun.Get(context.Background(), &result)
if err != nil {
// ...
}
// ...

Get last completion result

In the case of a Temporal Cron Job, you might need to get the result of the previous Workflow Run and use it in the current Workflow Run.

To do this, use the HasLastCompletionResult and GetLastCompletionResult APIs, available from the go.temporal.io/sdk/workflow package, directly in your Workflow code.

type CronResult struct {
Count int
}

func YourCronWorkflowDefinition(ctx workflow.Context) (CronResult, error) {
count := 1

if workflow.HasLastCompletionResult(ctx) {
var lastResult CronResult
if err := workflow.GetLastCompletionResult(ctx, &lastResult); err == nil {
count = count + lastResult.Count
}
}

newResult := CronResult {
Count: count,
}
return newResult, nil
}

This will work even if one of the cron Workflow Runs fails. The next Workflow Run gets the result of the last successfully Completed Workflow Run.

How to start a Workflow Execution

Workflow Execution semantics rely on several parameters—that is, to start a Workflow Execution you must supply a Task Queue that will be used for the Tasks (one that a Worker is polling), the Workflow Type, language-specific contextual data, and Workflow Function parameters.

In the examples below, all Workflow Executions are started using a Temporal Client. To spawn Workflow Executions from within another Workflow Execution, use either the Child Workflow or External Workflow APIs.

See the Customize Workflow Type section to see how to customize the name of the Workflow Type.

A request to spawn a Workflow Execution causes the Temporal Service to create the first Event (WorkflowExecutionStarted) in the Workflow Execution Event History. The Temporal Service then creates the first Workflow Task, resulting in the first WorkflowTaskScheduled Event.

Workflows can be started both synchronously and asynchronously. You can use typed or untyped Workflows stubs available via Temporal\Client\WorkflowClient. To create a Workflow Client:

use Temporal\Client\GRPC\ServiceClient;
use Temporal\Client\WorkflowClient;

$workflowClient = WorkflowClient::create(ServiceClient::create('localhost:7233'));

Synchronous start

A synchronous start initiates a Workflow and then waits for its completion. The started Workflow will not rely on the invocation process and will continue executing even if the waiting process crashes or stops.

Be sure to acquire the Workflow interface or class name you want to start. For example:

#[WorkflowInterface]
interface AccountTransferWorkflowInterface
{
#[WorkflowMethod(name: "MoneyTransfer")]
#[ReturnType('int')]
public function transfer(
string $fromAccountId,
string $toAccountId,
string $referenceId,
int $amountCents
);
}

To start the Workflow in sync mode:

$accountTransfer = $workflowClient->newWorkflowStub(
AccountTransferWorkflowInterface::class
);

$result = $accountTransfer->transfer(
'fromID',
'toID',
'refID',
1000
);

Asynchronous start

An asynchronous start initiates a Workflow Execution and immediately returns to the caller without waiting for a result. This is the most common way to start Workflows in a live environment.

To start a Workflow asynchronously, pass the Workflow stub instance and start parameters into the WorkflowClient->start method.

$accountTransfer = $workflowClient->newWorkflowStub(
AccountTransferWorkflowInterface::class
);

$run = $this->workflowClient->start($accountTransfer, 'fromID', 'toID', 'refID', 1000);

After the Workflow is started, you can receive the Workflow Id via the WorkflowRun object returned by the start method:

$run = $workflowClient->start($accountTransfer, 'fromID', 'toID', 'refID', 1000);

var_dump($run->getExecution()->getID());

Recurring start

You can start a Workflow Execution on a regular schedule with the CronSchedule option.

How to set a Workflow's Task Queue

In most SDKs, the only Workflow Option that must be set is the name of the Task Queue.

For any code to execute, a Worker Process must be running that contains a Worker Entity that is polling the same Task Queue name.

In PHP, a Task Queue is represented in code by its name as a string. There are four places where the name of the Task Queue is supplied by the developer.

  1. When starting a Workflow, a Task Queue name must be provided in the StartWorkflowOptions.
// Create new Workflow Options and set the Task Queue
$workflowOptions = WorkflowOptions::new()
->withTaskQueue("Workflow-Task-Queue-1")
// ...

$yourWorkflow = $workflowClient->newWorkflowStub(
YourWorkflowInterface::class,
$workflowOptions
);

$result = $yourWorkflow->workflowMethod();
  1. A Task Queue name must be provided as a parameter when creating a Worker.
use Temporal\WorkerFactory;

// Create a Worker Factory
$factory = WorkerFactory::create();

// Set the Task Queue when creating the Worker
$worker = $factory->newWorker("Workflow-Task-Queue-1");

// Workflows are stateful. So you need a type to create instances.
$worker->registerWorkflowTypes(YourWorkflow::class);

// start primary loop
$factory->run();

A single Worker can listen to only one Task Queue. And, it is important to remember that the name of the Task Queue the Worker is listening to must match the name of the Task Queue provided in the options to any given Workflow or Activity.

All Workers listening to the same Task Queue name must be registered to handle the exact same Workflows Types and Activity Types.

If a Worker polls a Task for a Workflow Type or Activity Type it does not know about, it will fail that Task. However, the failure of the Task will not cause the associated Workflow Execution to fail.

  1. Optionally, the name of a Task Queue can be provided in the ActivityOptions when calling an Activity from a Workflow.
class YourWorkflow implements YourWorkflowInterface
{
private $yourActivity;

public function __construct()
{
// Create Activity options and set the Task Queue
$activityOptions = ActivityOptions::new()
->withTaskQueue("Activity-Task-Queue-1")
// ...

// Create a new Activity Stub and pass the options
$this->yourActivity = Workflow::newActivityStub(
YourActivityInterface::class,
$activityOptions
);
}

public function workflowMethod(): \Generator
{
// Call the Activity
return yield $this->yourActivity->activityMethod();
}
}

If a Task Queue name is not provided in the ActivityOptions, then the Activity Tasks are placed in the same Task Queue as the Workflow Task Queue.

  1. Optionally, the name of a Task Queue can be provided in the ChildWorkflowOptions when calling a Child Workflow.
//Create new Child Workflow Options and set the Task Queue
$childWorkflowOptions = ChildWorkflowOptions::new()
->withTaskQueue("Child-Workflow-Task-Queue-1")
// ...

// Create a new Child Workflow Stub and set the Task Queue
$childWorkflow = Workflow::newChildWorkflowStub(
ChildWorkflowInterface::class,
$childWorkflowOptions
);

// Call the Child Workflow method
$promise = $childWorkflow->workflowMethod();

If a Task Queue name is not provided in the ChildWorkflowOptions, then the Child Workflow Tasks are placed in the same Task Queue as the Parent Workflow Task Queue.

How to set a Workflow Id

Although it is not required, we recommend providing your own Workflow Id that maps to a business process or business entity identifier, such as an order identifier or customer identifier.

The following code example grabs the userID as an input and uses it to start the Workflow. The userID is used as Workflow Id. You can use this to cancel your Workflow later.

#[WorkflowInterface]
interface SubscriptionWorkflowInterface
{
#[WorkflowMethod]
public function subscribe(string $userID);
}

The following code example, uses the input parameter userID as the Workflow Id.

#[WorkflowInterface]
interface SubscriptionWorkflowInterface
{
#[WorkflowMethod]
public function subscribe(
string $userID
);
}

You can also set the Workflow Id as a constant, for example:

public const WORKFLOW_ID = Your-Workflow-Id

How to get the results of a Workflow Execution

If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id.

The Workflow Id, Run Id, and Namespace may be used to uniquely identify a Workflow Execution in the system and get its result.

It's possible to both block progress on the result (synchronous execution) or get the result at some other point in time (asynchronous execution).

In the Temporal Platform, it's also acceptable to use Queries as the preferred method for accessing the state and results of Workflow Executions.

If you need to wait for the completion of a Workflow after an asynchronous start, make a blocking call to the WorkflowRun->getResult method.

$run = $workflowClient->start($accountTransfer, 'fromID', 'toID', 'refID', 1000);

var_dump($run->getResult());