From 43640c5fec8bb3b3d7eb11e70ead5df248d32b5d Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Mon, 13 Apr 2026 15:34:37 -0700 Subject: [PATCH 1/3] Add docs for stand alone nexus operations --- docs/develop/go/nexus/index.mdx | 1 + .../go/nexus/standalone-operations.mdx | 162 ++++++++++++++++++ sidebars.js | 1 + 3 files changed, 164 insertions(+) create mode 100644 docs/develop/go/nexus/standalone-operations.mdx diff --git a/docs/develop/go/nexus/index.mdx b/docs/develop/go/nexus/index.mdx index 4d5c5fcdc9..b77b5fad78 100644 --- a/docs/develop/go/nexus/index.mdx +++ b/docs/develop/go/nexus/index.mdx @@ -25,3 +25,4 @@ Temporal Go SDK support for Nexus is [Generally Available](/evaluate/development - [Quickstart](/develop/go/nexus/quickstart) - [Feature guide](/develop/go/nexus/feature-guide) +- [Standalone Operations](/develop/go/nexus/standalone-operations) diff --git a/docs/develop/go/nexus/standalone-operations.mdx b/docs/develop/go/nexus/standalone-operations.mdx new file mode 100644 index 0000000000..d8add5740b --- /dev/null +++ b/docs/develop/go/nexus/standalone-operations.mdx @@ -0,0 +1,162 @@ +--- +id: standalone-operations +title: Standalone Nexus Operations - Go SDK +sidebar_label: Standalone Operations +toc_max_heading_level: 4 +keywords: + - standalone nexus operation + - nexus operation execution + - execute nexus operation + - nexus operation handle + - list nexus operations + - count nexus operations + - go sdk +tags: + - Nexus + - Temporal Client + - Go SDK + - Temporal SDKs +description: Execute Nexus Operations independently without a Workflow using the Temporal Go SDK. +--- + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Temporal Go SDK support for Standalone Nexus Operations is at +[Pre-release](/evaluate/development-production-features/release-stages#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](/develop/go/nexus/feature-guide) for details on +[defining a Service contract](/develop/go/nexus/feature-guide#define-nexus-service-contract), +[developing Operation handlers](/develop/go/nexus/feature-guide#develop-nexus-service-operation-handlers), and +[registering a Service in a Worker](/develop/go/nexus/feature-guide#register-a-nexus-service-in-a-worker). + +This page focuses on the client-side APIs that are unique to Standalone Nexus Operations: + +- [Execute a Standalone Nexus Operation](#execute-operation) +- [Get the result of a Standalone Nexus Operation](#get-operation-result) +- [List Standalone Nexus Operations](#list-operations) +- [Count Standalone Nexus Operations](#count-operations) + +:::note + +This documentation uses source code from +[nexus-standalone-operations](https://github.com/temporalio/samples-go/tree/main/nexus-standalone-operations). + +::: + +## Execute a Standalone Nexus Operation {#execute-operation} + +To execute a Standalone Nexus Operation, first create a +[`NexusClient`](https://pkg.go.dev/go.temporal.io/sdk/client#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`](https://pkg.go.dev/go.temporal.io/sdk/client#NexusOperationHandle) +that you can use to get the result of the Operation. +[`StartNexusOperationOptions`](https://pkg.go.dev/go.temporal.io/sdk/client#StartNexusOperationOptions) requires `ID` +and at least one of `ScheduleToCloseTimeout` or `StartToCloseTimeout`. + +```go +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](https://github.com/temporalio/samples-go/blob/main/nexus-standalone-operations/starter/main.go) +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 {#get-operation-result} + +Use `NexusOperationHandle.Get()` to block until the Operation completes and retrieve its result. This works for both +synchronous and asynchronous (Workflow-backed) Operations. + +```go +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 {#list-operations} + +Use [`client.ListNexusOperations()`](https://pkg.go.dev/go.temporal.io/sdk/client#Client) to list Standalone Nexus +Operation Executions that match a [List Filter](/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`. + +```go +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](/list-filter) syntax. For example, +`"Endpoint = 'my-endpoint' AND Status = 'Running'"`. + +## Count Standalone Nexus Operations {#count-operations} + +Use [`client.CountNexusOperations()`](https://pkg.go.dev/go.temporal.io/sdk/client#Client) to count Standalone Nexus +Operation Executions that match a [List Filter](/list-filter) query. + +Note that `CountNexusOperations` is called on the base `client.Client`, not on the `NexusClient`. + +```go +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 {#run-standalone-nexus-operations-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](/develop/go/nexus/feature-guide#nexus-calls-across-namespaces-temporal-cloud) +and [Connect to Temporal Cloud](/develop/go/client/temporal-client#connect-to-temporal-cloud). diff --git a/sidebars.js b/sidebars.js index e606b87475..32c7e843e7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -195,6 +195,7 @@ module.exports = { items: [ 'develop/go/nexus/quickstart', 'develop/go/nexus/feature-guide', + 'develop/go/nexus/standalone-operations', ], }, { From 3cf8772e20dc551fdbbebe85d6205c4568cf2275 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Thu, 21 May 2026 08:12:34 -0700 Subject: [PATCH 2/3] Clean up --- docs/develop/go/nexus/standalone-operations.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/develop/go/nexus/standalone-operations.mdx b/docs/develop/go/nexus/standalone-operations.mdx index d8add5740b..5e9e8af820 100644 --- a/docs/develop/go/nexus/standalone-operations.mdx +++ b/docs/develop/go/nexus/standalone-operations.mdx @@ -28,7 +28,7 @@ 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 +Standalone Nexus Operations let you run Nexus Operation Executions 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()`. @@ -61,8 +61,8 @@ application code (for example, a starter program), not from inside a Workflow De `ExecuteOperation` returns a [`NexusOperationHandle`](https://pkg.go.dev/go.temporal.io/sdk/client#NexusOperationHandle) that you can use to get the result of the Operation. -[`StartNexusOperationOptions`](https://pkg.go.dev/go.temporal.io/sdk/client#StartNexusOperationOptions) requires `ID` -and at least one of `ScheduleToCloseTimeout` or `StartToCloseTimeout`. +[`StartNexusOperationOptions`](https://pkg.go.dev/go.temporal.io/sdk/client#StartNexusOperationOptions) requires `ID`. +`ScheduleToCloseTimeout` is optional and defaults to the maximum allowed by the Temporal server. ```go nexusClient, err := c.NewNexusClient(client.NexusClientOptions{ From 14a533540fc2b38a1d2428df93fca06ecb9788ad Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Wed, 27 May 2026 08:12:31 -0700 Subject: [PATCH 3/3] Add top level page --- .../nexus/standalone-nexus-operation.mdx | 99 ++++++++++++++ sidebars.js | 1 + ...alone-nexus-operations-vs-workflowdark.svg | 121 ++++++++++++++++++ ...lone-nexus-operations-vs-workflowlight.svg | 121 ++++++++++++++++++ 4 files changed, 342 insertions(+) create mode 100644 docs/encyclopedia/nexus/standalone-nexus-operation.mdx create mode 100644 static/diagrams/standalone-nexus-operations-vs-workflowdark.svg create mode 100644 static/diagrams/standalone-nexus-operations-vs-workflowlight.svg diff --git a/docs/encyclopedia/nexus/standalone-nexus-operation.mdx b/docs/encyclopedia/nexus/standalone-nexus-operation.mdx new file mode 100644 index 0000000000..058ca2bd50 --- /dev/null +++ b/docs/encyclopedia/nexus/standalone-nexus-operation.mdx @@ -0,0 +1,99 @@ +--- +id: standalone-nexus-operation +title: Standalone Nexus Operation +sidebar_label: Standalone Nexus Operation +description: Learn about Standalone Nexus Operations in Temporal, their benefits, execution model, and when to use them. +slug: /standalone-nexus-operation +toc_max_heading_level: 4 +keywords: + - standalone nexus operation + - nexus operation execution + - execute nexus operation + - explanation + - term +tags: + - Concepts + - Nexus + - Durable Execution +--- + +import ThemedImage from '@theme/ThemedImage'; + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Standalone Nexus Operations are at [Pre-release](/evaluate/development-production-features/release-stages#pre-release). APIs are experimental and may be subject to backwards-incompatible changes. + +::: + +## What is a Standalone Nexus Operation? {#standalone-nexus-operation} + +A Standalone Nexus Operation is a top-level [Nexus Operation Execution](/nexus/operations) started +directly by a [Client](/encyclopedia/temporal-sdks#temporal-client), without using a caller +Workflow. Instead of calling a Nexus Operation from within a Workflow Definition, you execute it +directly from a Nexus Client created from the Temporal SDK Client and bound to a +[Nexus Endpoint](/nexus/endpoints) and Service. + +
+ + + +
+ +Standalone Nexus Operations use the same Service contract, Operation handlers, and Worker setup as +Workflow-driven Operations — only the caller side differs. The same Operation can be executed as a +Standalone Nexus Operation and as a Workflow-driven Nexus Operation with no handler code changes. + +If you need to orchestrate multiple Nexus Operations, call them from a [Workflow](/workflows). But if +you just need to execute a single Nexus Operation across Namespace boundaries, use a Standalone +Nexus Operation. + +:::tip GET STARTED + +Pick your SDK and follow the quickstart: + +- [Go SDK - Standalone Nexus Operations](/develop/go/nexus/standalone-operations) + +::: + +## Use cases + +Standalone Nexus Operations are useful when application code outside of a Workflow needs to invoke +functionality exposed by another team's Namespace through a Nexus Endpoint — for example, calling a +shared service from a starter program, a job runner, an HTTP handler, or a script — with all the +reliability, retries, and observability of Nexus, but without paying the cost of a caller Workflow. + +## Key features + +- Execute any Nexus Operation as a top-level primitive without the overhead of a caller Workflow +- Same Service contract, Operation handlers, and Worker setup as Workflow-driven Operations +- Supports both synchronous and asynchronous (Workflow-backed) Nexus Operations +- At-least-once execution with automatic retries by the Nexus Machinery +- Addressable — get a handle to retrieve results, with the Operation token for asynchronous Operations +- Visibility — list and count Standalone Nexus Operation Executions using [List Filter](/list-filter) queries +- Dual use — execute the same Operation from a Workflow or standalone with no handler code changes + +## Observability {#observability} + +You can use [List Filters](/list-filter) to query Standalone Nexus Operation Executions by Endpoint, +Service, Operation, status, and other attributes using the SDK. + +`CountNexusOperations` returns the total number of Standalone Nexus Operation Executions matching a +filter. This is the total count of executions (running, completed, failed, etc.) — not the number of +queued tasks. + +## Pre-release limitations + +Standalone Nexus Operations are at Pre-release. APIs are experimental and may be subject to +backwards-incompatible changes. + + +## Temporal Cloud support + +Standalone Activities in Temporal Cloud is available as a Public Preview feature. diff --git a/sidebars.js b/sidebars.js index 32c7e843e7..ed346c29f9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1617,6 +1617,7 @@ module.exports = { items: [ 'encyclopedia/nexus/nexus-services', 'encyclopedia/nexus/nexus-operations', + 'encyclopedia/nexus/standalone-nexus-operation', 'encyclopedia/nexus/nexus-endpoints', 'encyclopedia/nexus/nexus-registry', 'encyclopedia/nexus/nexus-patterns', diff --git a/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg b/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg new file mode 100644 index 0000000000..8b6ec006cf --- /dev/null +++ b/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg @@ -0,0 +1,121 @@ + + + + + + + + + + + + + UI, CLI, SDK + + + + + + top-level primitives + + + + + + + + + + + Standalone Nexus Operation + Execution + + + + + + Execute a single Nexus Operation + across Namespaces reliably + + + + + + + + + + + Workflow + Execution + + + + + + + + Nexus Operation (Step 1) + + + + + + Nexus Operation (Step 2) + + + + + + Nexus Operation (Step 3) + + + + + Workflows: Multi-step + orchestration with automatic + durability via event history + & replay + + + + + + + + + + + Nexus Service, Operation Handlers + & Worker Deployment + + + + + + + + Same Nexus programming model: + write once & use anywhere. + + + + + Nexus Operations can be called standalone or from a + Workflow, with the same Service contract and handlers. + + + + + + + Standalone Nexus Operation + + Workflow & Nexus Operation Steps + + Description + + diff --git a/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg b/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg new file mode 100644 index 0000000000..d639a17c26 --- /dev/null +++ b/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg @@ -0,0 +1,121 @@ + + + + + + + + + + + + + UI, CLI, SDK + + + + + + top-level primitives + + + + + + + + + + + Standalone Nexus Operation + Execution + + + + + + Execute a single Nexus Operation + across Namespaces reliably + + + + + + + + + + + Workflow + Execution + + + + + + + + Nexus Operation (Step 1) + + + + + + Nexus Operation (Step 2) + + + + + + Nexus Operation (Step 3) + + + + + Workflows: Multi-step + orchestration with automatic + durability via event history + & replay + + + + + + + + + + + Nexus Service, Operation Handlers + & Worker Deployment + + + + + + + + Same Nexus programming model: + write once & use anywhere. + + + + + Nexus Operations can be called standalone or from a + Workflow, with the same Service contract and handlers. + + + + + + + Standalone Nexus Operation + + Workflow & Nexus Operation Steps + + Description + +