Temporal Client - Go SDK feature guide

The pages shows how to do the following:

Connect to a local development Temporal Service
Connect to Temporal Cloud
Start a Workflow Execution

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 Cluster 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 Cluster.

When you are running a Cluster 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 Cluster.

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 Cluster.
	// 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:

The Temporal Cloud Namespace Id.
The Namespace's gRPC endpoint. An endpoint listing is available at the Temporal Cloud Website on each Namespace detail page. The endpoint contains the Namespace Id and port.
mTLS CA certificate.
mTLS private key.

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 Cluster, see Temporal Customization Samples.

To connect to and run Workflows through Temporal Cloud, you need the following:

A compatible mTLS CA certificate and mTLS private key that has been added to your Namespace. See certificate requirements.
Your Temporal Cloud Namespace Id, which includes your Temporal Cloud Namespace Name and the unique five- or six-digit Temporal Cloud Account Id that is appended to it. This information can be found in the URL of your Namespace; for example, https://cloud.temporal.io/namespaces/yournamespace.a2fx6/. Remember that the Namespace Id must include the Account Id: yournamespace.a2fx6.

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 Cluster, 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 Cluster to create the first Event (WorkflowExecutionStarted) in the Workflow Execution Event History. The Temporal Cluster 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:

Field	Required	Type
`ID`	No	`string`
`TaskQueue`	Yes	`string`
`WorkflowExecutionTimeout`	No	`time.Duration`
`WorkflowRunTimeout`	No	`time.Duration`
`WorkflowTaskTimeout`	No	`time.Duration`
`WorkflowIDReusePolicy`	No	`WorkflowIdReusePolicy`
`WorkflowExecutionErrorWhenAlreadyStarted`	No	`bool`
`RetryPolicy`	No	`RetryPolicy`
`CronSchedule`	No	`string`
`Memo`	No	`map[string]interface{}`
`SearchAttributes`	No	`map[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.

Type: time.Duration
Default: Same as WorkflowExecutionTimeout

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

Type: WorkflowIdReusePolicy
Default: enums.WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE

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.

Type: RetryPolicy
Default: None

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.

Connect to development Temporal Service​

Connect to Temporal Cloud​

Start Workflow Execution​

Set Workflow Task Queue​

Set custom Workflow Id​

Go StartWorkflowOptions reference​

ID​

TaskQueue​

WorkflowExecutionTimeout​

WorkflowRunTimeout​

WorkflowTaskTimeout​

WorkflowIDReusePolicy​

WorkflowExecutionErrorWhenAlreadyStarted​

RetryPolicy​

CronSchedule​

Memo​

SearchAttributes​

Get Workflow results​