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
- How to 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 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.
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:
- 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 Service, 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 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:
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 {
// ...
}
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.
- 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();
- 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.
- 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.
- 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());