Skip to main content

Standalone Nexus Operations - Go SDK

SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Go SDK support for Standalone Nexus Operations is at Pre-release.

All APIs are experimental and may be subject to backwards-incompatible changes.

Standalone Nexus Operations are Nexus Operation Executions that run independently, without being orchestrated by a Workflow. Instead of calling a Nexus Operation from within a Workflow Definition using workflow.NewNexusClient(), you execute a Standalone Nexus Operation directly from a Nexus Client created using client.NewNexusClient().

Standalone Nexus Operations use the same Nexus Service contract, Operation handlers, and Worker setup as Workflow-driven Operations — only the execution path differs. See the Nexus feature guide for details on defining a Service contract, developing Operation handlers, and registering a Service in a Worker.

This page focuses on the client-side APIs that are unique to Standalone Nexus Operations:

note

This documentation uses source code from nexus-standalone-operations.

Execute a Standalone Nexus Operation​

To execute a Standalone Nexus Operation, first create a NexusClient using client.NewNexusClient(), bound to a specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call ExecuteOperation() from application code (for example, a starter program), not from inside a Workflow Definition.

ExecuteOperation returns a NexusOperationHandle that you can use to get the result of the Operation. StartNexusOperationOptions requires ID and at least one of ScheduleToCloseTimeout or StartToCloseTimeout.

nexusClient, err := c.NewNexusClient(client.NexusClientOptions{
    Endpoint: "my-nexus-endpoint",
    Service:  "my-service-name",
})

handle, err := nexusClient.ExecuteOperation(ctx, operationName, input, client.StartNexusOperationOptions{
    ID:                     "unique-operation-id",
    ScheduleToCloseTimeout: 10 * time.Second,
})

See the full starter sample for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and counts Operations.

To run the starter (in a separate terminal from the Worker):

go run nexus-standalone-operations/starter/main.go

Get the result of a Standalone Nexus Operation​

Use NexusOperationHandle.Get() to block until the Operation completes and retrieve its result. This works for both synchronous and asynchronous (Workflow-backed) Operations.

var result service.EchoOutput
err = handle.Get(context.Background(), &result)
if err != nil {
    log.Fatalln("Operation failed", err)
}
log.Println("Operation result:", result.Message)

If the Operation completed successfully, the result is deserialized into the provided pointer. If the Operation failed, the failure is returned as an error.

List Standalone Nexus Operations​

Use client.ListNexusOperations() to list Standalone Nexus Operation Executions that match a List Filter query. The result contains an iterator that yields operation metadata entries.

Note that ListNexusOperations is called on the base client.Client, not on the NexusClient.

resp, err := c.ListNexusOperations(context.Background(), client.ListNexusOperationsOptions{
    Query: "Endpoint = 'my-nexus-endpoint'",
})
if err != nil {
    log.Fatalln("Unable to list Nexus operations", err)
}

for metadata, err := range resp.Results {
    if err != nil {
        log.Fatalln("Error iterating operations", err)
    }
    log.Printf("OperationID: %s, Operation: %s, Status: %v\n",
        metadata.OperationID, metadata.Operation, metadata.Status)
}

The Query field accepts List Filter syntax. For example, "Endpoint = 'my-endpoint' AND Status = 'Running'".

Count Standalone Nexus Operations​

Use client.CountNexusOperations() to count Standalone Nexus Operation Executions that match a List Filter query.

Note that CountNexusOperations is called on the base client.Client, not on the NexusClient.

resp, err := c.CountNexusOperations(context.Background(), client.CountNexusOperationsOptions{
    Query: "Endpoint = 'my-nexus-endpoint'",
})
if err != nil {
    log.Fatalln("Unable to count Nexus operations", err)
}

log.Println("Total Nexus operations:", resp.Count)

Run Standalone Nexus Operations with Temporal Cloud​

The code samples on this page use envconfig.MustLoadDefaultClientOptions(), so the same code works against Temporal Cloud — just configure the connection via environment variables or a TOML profile. No code changes are needed.

For full details on connecting to Temporal Cloud, including Namespace creation, Nexus Endpoint setup, certificate generation, and authentication options, see Make Nexus calls across Namespaces in Temporal Cloud and Connect to Temporal Cloud.