From 43640c5fec8bb3b3d7eb11e70ead5df248d32b5d Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Mon, 13 Apr 2026 15:34:37 -0700 Subject: [PATCH 1/7] 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/7] 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/7] 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 + + From e65c2927d50d656292cda594f415a028961a7154 Mon Sep 17 00:00:00 2001 From: Quinn Klassen Date: Tue, 2 Jun 2026 08:38:19 -0700 Subject: [PATCH 4/7] Respond to PR comments --- docs/develop/go/nexus/standalone-operations.mdx | 7 ++++--- .../nexus/standalone-nexus-operation.mdx | 2 +- .../standalone-nexus-operations-vs-workflowdark.svg | 12 +++++++----- .../standalone-nexus-operations-vs-workflowlight.svg | 12 +++++++----- 4 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/develop/go/nexus/standalone-operations.mdx b/docs/develop/go/nexus/standalone-operations.mdx index 5e9e8af820..fd64b01b20 100644 --- a/docs/develop/go/nexus/standalone-operations.mdx +++ b/docs/develop/go/nexus/standalone-operations.mdx @@ -28,9 +28,10 @@ All APIs are experimental and may be subject to backwards-incompatible changes. ::: -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()`. +[Standalone Nexus Operations](/standalone-nexus-operation) 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()`. 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 diff --git a/docs/encyclopedia/nexus/standalone-nexus-operation.mdx b/docs/encyclopedia/nexus/standalone-nexus-operation.mdx index 058ca2bd50..e5a879187f 100644 --- a/docs/encyclopedia/nexus/standalone-nexus-operation.mdx +++ b/docs/encyclopedia/nexus/standalone-nexus-operation.mdx @@ -96,4 +96,4 @@ backwards-incompatible changes. ## Temporal Cloud support -Standalone Activities in Temporal Cloud is available as a Public Preview feature. +Standalone Nexus Operations in Temporal Cloud is available as a Pre-release feature. \ No newline at end of file diff --git a/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg b/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg index 8b6ec006cf..95e781c19d 100644 --- a/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg +++ b/static/diagrams/standalone-nexus-operations-vs-workflowdark.svg @@ -85,11 +85,11 @@ - + - + - Nexus Service, Operation Handlers + Temporal Nexus Service, Operation Handlers & Worker Deployment @@ -115,7 +115,9 @@ Standalone Nexus Operation Workflow & Nexus Operation Steps - - Description + + Shared infrastructure + + Description diff --git a/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg b/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg index d639a17c26..625c45a513 100644 --- a/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg +++ b/static/diagrams/standalone-nexus-operations-vs-workflowlight.svg @@ -85,11 +85,11 @@ - + - + - Nexus Service, Operation Handlers + Temporal Nexus Service, Operation Handlers & Worker Deployment @@ -115,7 +115,9 @@ Standalone Nexus Operation Workflow & Nexus Operation Steps - - Description + + Shared infrastructure + + Description From d87b0b231ca3b74432e446f31cc00efd31404682 Mon Sep 17 00:00:00 2001 From: Jwahir Sundai Date: Tue, 2 Jun 2026 11:38:03 -0500 Subject: [PATCH 5/7] fix build error --- docs/develop/go/nexus/standalone-operations.mdx | 10 +++++----- docs/encyclopedia/nexus/standalone-nexus-operation.mdx | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/develop/go/nexus/standalone-operations.mdx b/docs/develop/go/nexus/standalone-operations.mdx index fd64b01b20..b0b677fd9b 100644 --- a/docs/develop/go/nexus/standalone-operations.mdx +++ b/docs/develop/go/nexus/standalone-operations.mdx @@ -53,7 +53,7 @@ This documentation uses source code from ::: -## Execute a Standalone Nexus Operation {#execute-operation} +## 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 @@ -88,7 +88,7 @@ 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} +## 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. @@ -105,7 +105,7 @@ 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} +## 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 @@ -133,7 +133,7 @@ for metadata, err := range resp.Results { The `Query` field accepts [List Filter](/list-filter) syntax. For example, `"Endpoint = 'my-endpoint' AND Status = 'Running'"`. -## Count Standalone Nexus Operations {#count-operations} +## 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. @@ -151,7 +151,7 @@ if err != nil { log.Println("Total Nexus operations:", resp.Count) ``` -## Run Standalone Nexus Operations with Temporal Cloud {#run-standalone-nexus-operations-temporal-cloud} +## 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 diff --git a/docs/encyclopedia/nexus/standalone-nexus-operation.mdx b/docs/encyclopedia/nexus/standalone-nexus-operation.mdx index e5a879187f..d499fabb7b 100644 --- a/docs/encyclopedia/nexus/standalone-nexus-operation.mdx +++ b/docs/encyclopedia/nexus/standalone-nexus-operation.mdx @@ -25,7 +25,7 @@ Standalone Nexus Operations are at [Pre-release](/evaluate/development-productio ::: -## What is a Standalone Nexus Operation? {#standalone-nexus-operation} +## 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 @@ -79,7 +79,7 @@ reliability, retries, and observability of Nexus, but without paying the cost of - 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} +## 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. From b140ec1be57180ce844c609a807d46625aaad76d Mon Sep 17 00:00:00 2001 From: Alex Mazzeo Date: Fri, 5 Jun 2026 11:11:40 -0700 Subject: [PATCH 6/7] Python & Typescript SANO docs (#4659) * Python & Typescript SANO docs * fix broken anchor * Fix using go links instead of python links * Add docs links to Typescript references --- docs/develop/go/index.mdx | 1 + docs/develop/python/index.mdx | 1 + docs/develop/python/nexus/feature-guide.mdx | 2 +- docs/develop/python/nexus/index.mdx | 1 + .../python/nexus/standalone-operations.mdx | 152 +++++++++++++++++ docs/develop/typescript/index.mdx | 1 + docs/develop/typescript/nexus/index.mdx | 1 + .../nexus/standalone-operations.mdx | 153 ++++++++++++++++++ sidebars.js | 4 +- 9 files changed, 314 insertions(+), 2 deletions(-) create mode 100644 docs/develop/python/nexus/standalone-operations.mdx create mode 100644 docs/develop/typescript/nexus/standalone-operations.mdx diff --git a/docs/develop/go/index.mdx b/docs/develop/go/index.mdx index 46b0900374..fd17f692bb 100644 --- a/docs/develop/go/index.mdx +++ b/docs/develop/go/index.mdx @@ -72,6 +72,7 @@ From there, you can dive deeper into any of the Temporal primitives to start bui - [Quickstart](/develop/go/nexus/quickstart) - [Feature guide](/develop/go/nexus/feature-guide) +- [Standalone Operations](/develop/go/nexus/standalone-operations) ## [Platform](/develop/go/platform) diff --git a/docs/develop/python/index.mdx b/docs/develop/python/index.mdx index 403be4645b..b858d23895 100644 --- a/docs/develop/python/index.mdx +++ b/docs/develop/python/index.mdx @@ -64,6 +64,7 @@ From there, you can dive deeper into any of the Temporal primitives to start bui - [Quickstart](/develop/python/nexus/quickstart) - [Feature guide](/develop/python/nexus/feature-guide) +- [Standalone Operations](/develop/python/nexus/standalone-operations) ## [Platform](/develop/python/platform) diff --git a/docs/develop/python/nexus/feature-guide.mdx b/docs/develop/python/nexus/feature-guide.mdx index f484adefa2..5e5f5e7424 100644 --- a/docs/develop/python/nexus/feature-guide.mdx +++ b/docs/develop/python/nexus/feature-guide.mdx @@ -262,7 +262,7 @@ class MyNexusServiceHandler: -### Register your Nexus Service handler in a Worker +### Register your Nexus Service handler in a Worker {/* #register-a-nexus-service-in-a-worker */} After developing an asynchronous Nexus Operation handler to start a Workflow, the next step is to register your Nexus Service handler in a Worker. At this stage you can pass any arguments you need to your service handler's `__init__` method. diff --git a/docs/develop/python/nexus/index.mdx b/docs/develop/python/nexus/index.mdx index bb4b354fcf..cd961325c4 100644 --- a/docs/develop/python/nexus/index.mdx +++ b/docs/develop/python/nexus/index.mdx @@ -25,3 +25,4 @@ Temporal Python SDK support for Nexus is [Generally Available](/evaluate/develop - [Quickstart](/develop/python/nexus/quickstart) - [Feature guide](/develop/python/nexus/feature-guide) +- [Standalone Operations](/develop/python/nexus/standalone-operations) diff --git a/docs/develop/python/nexus/standalone-operations.mdx b/docs/develop/python/nexus/standalone-operations.mdx new file mode 100644 index 0000000000..6f33b35700 --- /dev/null +++ b/docs/develop/python/nexus/standalone-operations.mdx @@ -0,0 +1,152 @@ +--- +id: standalone-operations +title: Standalone Nexus Operations - Python 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 + - python sdk +tags: + - Nexus + - Temporal Client + - Python SDK + - Temporal SDKs +description: Execute Nexus Operations independently without a Workflow using the Temporal Python SDK. +--- + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Temporal Python 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](/standalone-nexus-operation) 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.create_nexus_client()`, you execute a Standalone Nexus Operation directly from a Nexus Client created using +`client.create_nexus_client()`. + +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/python/nexus/feature-guide) for details on +[defining a Service contract](/develop/python/nexus/feature-guide#define-nexus-service-contract), +[developing Operation handlers](/develop/python/nexus/feature-guide#develop-nexus-service-operation-handlers), and +[registering a Service in a Worker](/develop/python/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) +- [Start a Standalone Nexus Operation and Wait for the Result](#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-python/tree/main/nexus-standalone-operations). + +::: + +## Execute a Standalone Nexus Operation {/* #execute-operation */} + +To execute a Standalone Nexus Operation, first create a +[`NexusClient`](https://python.temporal.io/temporalio.client.NexusClient.html) using `client.create_nexus_client()`, bound to a +specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call `start_operation()` or `execute_operation()` from application code (for example, a starter program), not from inside a Workflow Definition. + +`execute_operation` waits for the Operation to complete and returns the result. +Both methods require `id`. `schedule_to_close_timeout` is optional and defaults to the maximum allowed by the Temporal server. + +```python +nexus_client = client.create_nexus_client( + service=MyNexusService, endpoint=ENDPOINT_NAME +) + +# Await the result of the operation immediately. +echo_result = await nexus_client.execute_operation( + MyNexusService.echo, + EchoInput(message="hello"), + id=f"echo-{uuid.uuid4()}", + schedule_to_close_timeout=timedelta(seconds=10), +) +``` + +See the full +[starter sample](https://github.com/temporalio/samples-python/blob/main/nexus_standalone_operations/starter.py) +for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and +counts Operations. + +## Start a Standalone Nexus Operation and Wait for the Result {/* #get-operation-result */} + +`start_operation` returns a [`NexusOperationHandle`](https://python.temporal.io/temporalio.client.NexusOperationHandle.html). +Use `NexusOperationHandle.result()` to wait until the Operation completes and retrieve its result. This works for both +synchronous and asynchronous Operations. + +```python +# Start an operation and get a NexusOperationHandle +handle = await nexus_client.start_operation( + MyNexusService.hello, + HelloInput(name="World"), + id=f"hello-{uuid.uuid4()}", + schedule_to_close_timeout=timedelta(seconds=10), +) +# Await the result +try: + hello_result = await handle.result() + print(hello_result) +except err: + print(err) + raise +``` + +If the Operation completed successfully, the result is returned. If the Operation failed, the failure is raised as an error. + +## List Standalone Nexus Operations {/* #list-operations */} + +Use [`client.list_nexus_operations()`](https://python.temporal.io/temporalio.client.Client.html#list_nexus_operations) 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 `list_nexus_operations` is called on the base `client.Client`, not on the `NexusClient`. + +```python +query = f'Endpoint = "{ENDPOINT_NAME}"' +async for op in client.list_nexus_operations(query): + print( + f" OperationId: {op.operation_id},", + f" Operation: {op.operation},", + f" Status: {op.status.name}", + ) +``` + +The `query` parameter accepts [List Filter](/list-filter) syntax. For example, +`"Endpoint = 'my-endpoint' AND Status = 'Running'"`. + +## Count Standalone Nexus Operations {/* #count-operations */} + +Use [`client.count_nexus_operations()`](https://python.temporal.io/temporalio.client.Client.html#count_nexus_operations) to count Standalone Nexus +Operation Executions that match a [List Filter](/list-filter) query. + +Note that `count_nexus_operations` is called on the base `client.Client`, not on the `NexusClient`. + +```python +query = f'Endpoint = "{ENDPOINT_NAME}"' +count = await client.count_nexus_operations(query) +print(f"Total Nexus operations: {count.count}") +``` + +## Run Standalone Nexus Operations with Temporal Cloud {/* #run-standalone-nexus-operations-temporal-cloud */} + +The code samples referenced on this page use [`ClientConfig.load_client_connect_config()`](https://python.temporal.io/temporalio.envconfig.ClientConfig.html#load_client_connect_config), 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/python/nexus/feature-guide#nexus-calls-across-namespaces-temporal-cloud) +and [Connect to Temporal Cloud](/develop/python/client/temporal-client#connect-to-temporal-cloud). diff --git a/docs/develop/typescript/index.mdx b/docs/develop/typescript/index.mdx index d56f191890..5af04e141e 100644 --- a/docs/develop/typescript/index.mdx +++ b/docs/develop/typescript/index.mdx @@ -65,6 +65,7 @@ Once your local Temporal Service is set up, continue building with the following - [Quickstart](/develop/typescript/nexus/quickstart) - [Feature guide](/develop/typescript/nexus/feature-guide) +- [Standalone Operations](/develop/typescript/nexus/standalone-operations) ## [Platform](/develop/typescript/platform) diff --git a/docs/develop/typescript/nexus/index.mdx b/docs/develop/typescript/nexus/index.mdx index 16ce4c9921..4098784a6b 100644 --- a/docs/develop/typescript/nexus/index.mdx +++ b/docs/develop/typescript/nexus/index.mdx @@ -26,3 +26,4 @@ Temporal TypeScript SDK support for Nexus is in [Public Preview](/evaluate/devel - [Quickstart](/develop/typescript/nexus/quickstart) - [Feature guide](/develop/typescript/nexus/feature-guide) +- [Standalone Operations](/develop/typescript/nexus/standalone-operations) diff --git a/docs/develop/typescript/nexus/standalone-operations.mdx b/docs/develop/typescript/nexus/standalone-operations.mdx new file mode 100644 index 0000000000..dbb245a888 --- /dev/null +++ b/docs/develop/typescript/nexus/standalone-operations.mdx @@ -0,0 +1,153 @@ +--- +id: standalone-operations +title: Standalone Nexus Operations - TypeScript 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 + - typescript sdk +tags: + - Nexus + - Temporal Client + - TypeScript SDK + - Temporal SDKs +description: Execute Nexus Operations independently without a Workflow using the Temporal TypeScript SDK. +--- + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Temporal TypeScript 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](/standalone-nexus-operation) 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 +`@temporalio/workflow`'s `createNexusServiceClient()`, you execute a Standalone Nexus Operation directly from a Nexus +service client created on the Temporal Client using `client.nexus.createServiceClient()`. + +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/typescript/nexus/feature-guide) for details on +[defining a Service contract](/develop/typescript/nexus/feature-guide#define-nexus-service-contract) and +[developing Operation handlers and registering a Service in a Worker](/develop/typescript/nexus/feature-guide#develop-nexus-service-operation-handlers). + +This page focuses on the client-side APIs that are unique to Standalone Nexus Operations: + +- [Execute a Standalone Nexus Operation](#execute-operation) +- [Start a Standalone Nexus Operation and Wait for the Result](#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-typescript/tree/main/nexus-standalone-operations). + +::: + +## Execute a Standalone Nexus Operation {/* #execute-operation */} + +To execute a Standalone Nexus Operation, first create a [`NexusServiceClient`](https://typescript.temporal.io/api/interfaces/client.NexusServiceClient) using [`client.nexus.createServiceClient()`](https://typescript.temporal.io/api/classes/client.NexusClient#createserviceclient), +bound to a specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call +`startOperation()` or `executeOperation()` from application code (for example, a starter program), not from inside a +Workflow Definition. + +`executeOperation` waits for the Operation to complete and returns the result. +Both methods require `id`. `scheduleToCloseTimeout` is optional and defaults to the maximum allowed by the Temporal server. + +```ts +const nexusClient = client.nexus.createServiceClient({ + endpoint: ENDPOINT_NAME, + service: myNexusService, +}); + +// Await the result of the operation immediately. +const echoResult = await nexusClient.executeOperation( + myNexusService.operations.echo, + { message: 'hello' }, + { + id: `echo-${nanoid()}`, + scheduleToCloseTimeout: '10s', + }, +); +``` + +See the full +[starter sample](https://github.com/temporalio/samples-typescript/blob/main/nexus-standalone-operations/src/starter.ts) +for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and +counts Operations. + +## Start a Standalone Nexus Operation and Wait for the Result {/* #get-operation-result */} + +`startOperation` returns a [`NexusOperationHandle`](https://typescript.temporal.io/api/interfaces/client.NexusOperationHandle). +Use `NexusOperationHandle.result()` to wait until the Operation completes and retrieve its result. This works for both +synchronous and asynchronous Operations. + +```ts +// Start an operation and get a NexusOperationHandle +const handle = await nexusClient.startOperation( + myNexusService.operations.hello, + { name: 'World' }, + { + id: `hello-${nanoid()}`, + scheduleToCloseTimeout: '10s', + }, +); + +// Await the result +const helloResult = await handle.result(); +console.log(helloResult.greeting); +``` + +If the Operation completed successfully, the result is returned. If the Operation failed, the failure is thrown as an error. + +## List Standalone Nexus Operations {/* #list-operations */} + +Use [`client.nexus.list()`](https://typescript.temporal.io/api/classes/client.NexusClient#list) to list Standalone Nexus Operation Executions that match a [List Filter](/list-filter) query. +The result is an async iterator that yields operation metadata entries. + +Note that `client.nexus.list()` is called on the base `Client`, not on the `NexusServiceClient`. + +```ts +const query = `Endpoint = "${ENDPOINT_NAME}"`; +for await (const op of client.nexus.list({ query })) { + console.log( + `OperationId: ${op.operationId},`, + `Operation: ${op.operation},`, + `Status: ${op.status}`, + ); +} +``` + +The `query` parameter accepts [List Filter](/list-filter) syntax. For example, +`"Endpoint = 'my-endpoint' AND Status = 'Running'"`. + +## Count Standalone Nexus Operations {/* #count-operations */} + +Use [`client.nexus.count()`](https://typescript.temporal.io/api/classes/client.NexusClient#count) to count Standalone Nexus Operation Executions that match a [List Filter](/list-filter) query. + +Note that `client.nexus.count()` is called on the base `Client`, not on the Nexus service client. + +```ts +const query = `Endpoint = "${ENDPOINT_NAME}"`; +const count = await client.nexus.count(query); +console.log(`Total Nexus operations: ${count.count}`); +``` + +## Run Standalone Nexus Operations with Temporal Cloud {/* #run-standalone-nexus-operations-temporal-cloud */} + +The code samples referenced on this page use [`loadClientConnectConfig()`](https://typescript.temporal.io/api/namespaces/envconfig#loadclientconfig) from `@temporalio/envconfig`, 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/typescript/nexus/feature-guide#nexus-calls-across-namespaces-temporal-cloud) +and [Connect to Temporal Cloud](/develop/typescript/client/temporal-client#connect-to-temporal-cloud). diff --git a/sidebars.js b/sidebars.js index ed6c2f9e54..f2db99d5ed 100644 --- a/sidebars.js +++ b/sidebars.js @@ -565,6 +565,7 @@ module.exports = { items: [ 'develop/python/nexus/quickstart', 'develop/python/nexus/feature-guide', + 'develop/python/nexus/standalone-operations', ], }, { @@ -722,7 +723,8 @@ module.exports = { }, items: [ 'develop/typescript/nexus/quickstart', - 'develop/typescript/nexus/feature-guide' + 'develop/typescript/nexus/feature-guide', + 'develop/typescript/nexus/standalone-operations', ], }, { From ca20c6559124076ae1bb8086fd379d4c001ed8db Mon Sep 17 00:00:00 2001 From: Evan Reynolds Date: Mon, 8 Jun 2026 15:24:32 -0700 Subject: [PATCH 7/7] Adding Nexus Java standalone operations --- docs/develop/java/index.mdx | 1 + docs/develop/java/nexus/index.mdx | 1 + .../java/nexus/standalone-operations.mdx | 168 ++++++++++++++++++ sidebars.js | 1 + 4 files changed, 171 insertions(+) create mode 100644 docs/develop/java/nexus/standalone-operations.mdx diff --git a/docs/develop/java/index.mdx b/docs/develop/java/index.mdx index 46f73981be..f71a645be4 100644 --- a/docs/develop/java/index.mdx +++ b/docs/develop/java/index.mdx @@ -66,6 +66,7 @@ From there, you can dive deeper into any of the Temporal primitives to start bui - [Quickstart](/develop/java/nexus/quickstart) - [Feature guide](/develop/java/nexus/feature-guide) +- [Standalone Operations](/develop/java/nexus/standalone-operations) ## [Platform](/develop/java/platform) diff --git a/docs/develop/java/nexus/index.mdx b/docs/develop/java/nexus/index.mdx index 2246063f16..4b68df76fc 100644 --- a/docs/develop/java/nexus/index.mdx +++ b/docs/develop/java/nexus/index.mdx @@ -25,4 +25,5 @@ Temporal Java SDK support for Nexus is [Generally Available](/evaluate/developme - [Quickstart](/develop/java/nexus/quickstart) - [Feature guide](/develop/java/nexus/feature-guide) +- [Standalone Operations](/develop/java/nexus/standalone-operations) - [Nexus sync tutorial](https://learn.temporal.io/tutorials/nexus/nexus-sync-tutorial/) diff --git a/docs/develop/java/nexus/standalone-operations.mdx b/docs/develop/java/nexus/standalone-operations.mdx new file mode 100644 index 0000000000..def425e49f --- /dev/null +++ b/docs/develop/java/nexus/standalone-operations.mdx @@ -0,0 +1,168 @@ +--- +id: standalone-operations +title: Standalone Nexus Operations - Java 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 + - java sdk +tags: + - Nexus + - Temporal Client + - Java SDK + - Temporal SDKs +description: Execute Nexus Operations independently without a Workflow using the Temporal Java SDK. +--- + +:::tip SUPPORT, STABILITY, and DEPENDENCY INFO + +Temporal Java 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](/standalone-nexus-operation) 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.newNexusServiceStub()`, you execute a Standalone Nexus Operation directly from a Nexus service client created +from a `NexusClient` using `NexusClient.newNexusServiceClient()`. + +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/java/nexus/feature-guide) for details on +[defining a Service contract](/develop/java/nexus/feature-guide#define-nexus-service-contract), +[developing Operation handlers](/develop/java/nexus/feature-guide#develop-nexus-service-operation-handlers), and +[registering a Service in a Worker](/develop/java/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) +- [Start a Standalone Nexus Operation and Wait for the Result](#get-operation-result) +- [List Standalone Nexus Operations](#list-operations) +- [Count Standalone Nexus Operations](#count-operations) + +:::note +This documentation uses source code from the +[Java Nexus Standalone sample](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/nexusstandalone). + +::: + +## Execute a Standalone Nexus Operation {/* #execute-operation */} + +To execute a Standalone Nexus Operation, first create a +[`NexusClient`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/NexusClient.html), then +derive a typed +[`NexusServiceClient`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/NexusServiceClient.html) +from it with `newNexusServiceClient()`, bound to a specific Nexus Endpoint and Service. The endpoint must be +pre-created on the server. Then call `start()` or `execute()` from application code (for example, a starter program), +not from inside a Workflow Definition. + +`execute()` waits for the Operation to complete and returns the result. +Both methods take a [`StartNexusOperationOptions`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/StartNexusOperationOptions.html) +whose `id` is required — the SDK never generates one for you. `scheduleToCloseTimeout` is optional and defaults to the +maximum allowed by the Temporal server. + +```java +NexusClient nexusClient = NexusClient.newInstance(stubs, options); +NexusServiceClient greetingClient = + nexusClient.newNexusServiceClient(GreetingNexusService.class, ENDPOINT_NAME); + +// Block until the operation completes and return its result. +GreetingOutput greeting = + greetingClient.execute( + GreetingNexusService::greet, + new GreetingInput("World"), + StartNexusOperationOptions.newBuilder() + .setId("greet-" + UUID.randomUUID()) + .setScheduleToCloseTimeout(Duration.ofSeconds(10)) + .build()); +``` + +`executeAsync()` is the same but returns a `CompletableFuture` instead of blocking. + +```java +CompletableFuture future = + greetingClient.executeAsync( + GreetingNexusService::greet, new GreetingInput("World"), options); +GreetingOutput greeting = future.get(); +``` + +See the full +[starter sample](https://github.com/temporalio/samples-java/blob/main/core/src/main/java/io/temporal/samples/nexusstandalone/StandaloneClientStarter.java) +for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and +counts Operations. + +## Start a Standalone Nexus Operation and Wait for the Result {/* #get-operation-result */} + +`start()` returns a +[`NexusOperationHandle`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/NexusOperationHandle.html). +Use `NexusOperationHandle.getResult()` to wait until the Operation completes and retrieve its result. This works for +both synchronous and asynchronous Operations. + +```java +// Start an operation and get a NexusOperationHandle. +NexusOperationHandle handle = + greetingClient.start( + GreetingNexusService::startGreeting, new GreetingInput("World"), options); + +// Block until the operation completes and retrieve its result. +GreetingOutput greeting = handle.getResult(); +``` + +If the Operation completed successfully, the result is returned. If the Operation failed, the failure is thrown as a +`NexusOperationException`. Use `getResultAsync()` for a non-blocking `CompletableFuture`, or +`getResult(long timeout, TimeUnit unit)` to bound the wait. + +## List Standalone Nexus Operations {/* #list-operations */} + +Use [`NexusClient.listNexusOperationExecutions()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/NexusClient.html) +to list Standalone Nexus Operation Executions that match a [List Filter](/list-filter) query. The result is a `Stream` +of operation metadata entries. + +Note that `listNexusOperationExecutions()` is called on a `NexusClient`, not on the typed `NexusServiceClient`. + +```java +String query = "Endpoint = \"" + ENDPOINT_NAME + "\""; +nexusClient + .listNexusOperationExecutions(query) + .forEach( + op -> + System.out.printf( + "OperationId: %s, Operation: %s, Status: %s%n", + op.getOperationId(), op.getOperation(), op.getStatus())); +``` + +The `query` parameter accepts [List Filter](/list-filter) syntax. For example, +`"Endpoint = 'my-endpoint' AND ExecutionStatus = 'Running'"`. + +## Count Standalone Nexus Operations {/* #count-operations */} + +Use [`NexusClient.countNexusOperationExecutions()`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/NexusClient.html) +to count Standalone Nexus Operation Executions that match a [List Filter](/list-filter) query. + +Note that `countNexusOperationExecutions()` is called on a `NexusClient`, not on the typed `NexusServiceClient`. + +```java +String query = "Endpoint = \"" + ENDPOINT_NAME + "\""; +NexusOperationExecutionCount count = nexusClient.countNexusOperationExecutions(query); +System.out.println("Total Nexus operations: " + count.getCount()); +``` + +Passing a `GROUP BY` query (for example, `"GROUP BY ExecutionStatus"`) returns a count per group, available through +`NexusOperationExecutionCount.getGroups()`. + +## Run Standalone Nexus Operations with Temporal Cloud {/* #run-standalone-nexus-operations-temporal-cloud */} + +The code samples referenced on this page build their client from a `ClientConfigProfile` loaded from a TOML profile, so +the same code works against Temporal Cloud — just point the profile at your Cloud Namespace (or override the connection +via `TEMPORAL_*` environment variables). 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/java/nexus/feature-guide#nexus-calls-across-namespaces-temporal-cloud) +and [Connect to Temporal Cloud](/develop/java/client/temporal-client#connect-to-temporal-cloud). diff --git a/sidebars.js b/sidebars.js index f2db99d5ed..927ac98d59 100644 --- a/sidebars.js +++ b/sidebars.js @@ -327,6 +327,7 @@ module.exports = { items: [ 'develop/java/nexus/quickstart', 'develop/java/nexus/feature-guide', + 'develop/java/nexus/standalone-operations', ], }, {