diff --git a/docs/develop/go/index.mdx b/docs/develop/go/index.mdx index 15723c7de2..f0152a6a28 100644 --- a/docs/develop/go/index.mdx +++ b/docs/develop/go/index.mdx @@ -96,6 +96,14 @@ Complete Activities asynchronously. - [How to asynchronously complete an Activity](/develop/go/asynchronous-activity-completion) +## [Standalone Activities](/develop/go/standalone-activities) + +Execute Activities independently without a Workflow using the Temporal Client. + +- [How to execute a Standalone Activity](/develop/go/standalone-activities#execute-activity) +- [How to get the result of a Standalone Activity](/develop/go/standalone-activities#get-activity-result) +- [How to get a handle to an existing Standalone Activity](/develop/go/standalone-activities#get-activity-handle) + ## [Versioning](/develop/go/versioning) Change Workflow Definitions without causing non-deterministic behavior in running Workflows. diff --git a/docs/develop/go/standalone-activities.mdx b/docs/develop/go/standalone-activities.mdx new file mode 100644 index 0000000000..0aed264eea --- /dev/null +++ b/docs/develop/go/standalone-activities.mdx @@ -0,0 +1,153 @@ +--- +id: standalone-activities +title: Standalone Activities - Go SDK +sidebar_label: Standalone Activities +toc_max_heading_level: 4 +keywords: + - standalone activity + - activity execution + - execute activity + - activity handle + - list activities + - count activities + - go sdk +tags: + - Activities + - Temporal Client + - Go SDK + - Temporal SDKs +description: Execute Activities independently without a Workflow using the Temporal Go SDK. +--- + +Standalone Activities are Activity Executions that run independently, without being orchestrated by a Workflow. +Instead of starting an Activity from within a Workflow Definition using `workflow.ExecuteActivity()`, you start a Standalone Activity directly from a Temporal Client using `client.ExecuteActivity()`. + +The Activity definition and Worker registration are identical to regular Activities — only the execution path differs. + +This page covers the following: + +- [Execute a Standalone Activity](#execute-activity) +- [Get the result of a Standalone Activity](#get-activity-result) +- [Get a handle to an existing Standalone Activity](#get-activity-handle) + +:::caution EXPERIMENTAL + +Standalone Activities are [Experimental](/evaluate/development-production-features/release-stages). +The API may change in future releases. + +::: + +:::info PREREQUISITES + +Standalone Activities require server-side support. +If you are running a self-hosted Temporal Server, the following dynamic config values must be enabled: + +- `activity.enableStandalone=true` +- `history.enableChasm=true` +- `history.enableTransitionHistory=true` + +The `ListActivities` and `CountActivities` APIs use Go's `iter.Seq2` type, which requires **Go 1.23 or later**. + +::: + + +## Execute a Standalone Activity {#execute-activity} + +Use [`client.ExecuteActivity()`](https://pkg.go.dev/go.temporal.io/sdk/client#Client) to start a Standalone Activity Execution. +This is called from application code (for example, a starter program), not from inside a Workflow Definition. + +`ExecuteActivity` returns an [`ActivityHandle`](https://pkg.go.dev/go.temporal.io/sdk/client#ActivityHandle) that you can use to get the result, describe, cancel, or terminate the Activity. + +
+ + View the source code + {' '} + in the context of the rest of the application code. +
+ +```go +import ( + "context" + "log" + "time" + + "go.temporal.io/sdk/client" +) + +func main() { + c, err := client.Dial(client.Options{}) + if err != nil { + log.Fatalln("Unable to create client", err) + } + defer c.Close() + + activityOptions := client.StartActivityOptions{ + ID: "my-standalone-activity-id", + TaskQueue: "my-task-queue", + ScheduleToCloseTimeout: 10 * time.Second, + } + + handle, err := c.ExecuteActivity( + context.Background(), activityOptions, MyActivity, "Temporal", + ) + if err != nil { + log.Fatalln("Unable to execute standalone activity", err) + } + + log.Println("Started standalone activity", + "ActivityID", handle.GetID(), + "RunID", handle.GetRunID(), + ) +} +``` + +You can pass the Activity as either a function reference or a string Activity type name: + +```go +// Using a function reference (recommended — enables compile-time parameter validation) +handle, err := c.ExecuteActivity(ctx, options, MyActivity, "arg1") + +// Using a string type name +handle, err := c.ExecuteActivity(ctx, options, "MyActivity", "arg1") +``` + +`client.StartActivityOptions` requires `ID`, `TaskQueue`, and at least one of `ScheduleToCloseTimeout` or `StartToCloseTimeout`. +See [`StartActivityOptions`](https://pkg.go.dev/go.temporal.io/sdk/client#StartActivityOptions) in the API reference for the full set of options. + +## Get the result of a Standalone Activity {#get-activity-result} + +Use `ActivityHandle.Get()` to block until the Activity completes and retrieve its result. +This is analogous to calling `Get()` on a `WorkflowRun`. + +```go +var result string +err = handle.Get(context.Background(), &result) +if err != nil { + log.Fatalln("Activity failed", err) +} +log.Println("Activity result:", result) +``` + +If the Activity completed successfully, the result is deserialized into the provided pointer. +If the Activity failed, the failure is returned as an error. + +## Get a handle to an existing Standalone Activity {#get-activity-handle} + +Use `client.GetActivityHandle()` to create a handle to a previously started Standalone Activity. +This is analogous to `client.GetWorkflow()` for Workflow Executions. + +Both `ActivityID` and `RunID` are required. + +```go +handle := c.GetActivityHandle(client.GetActivityHandleOptions{ + ActivityID: "my-standalone-activity-id", + RunID: "the-run-id", +}) + +// Use the handle to get the result, describe, cancel, or terminate +var result string +err := handle.Get(context.Background(), &result) +if err != nil { + log.Fatalln("Unable to get activity result", err) +} +``` diff --git a/sidebars.js b/sidebars.js index 17633d1b6e..63bd970fe3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -105,6 +105,7 @@ module.exports = { 'develop/go/message-passing', 'develop/go/cancellation', 'develop/go/asynchronous-activity-completion', + 'develop/go/standalone-activities', 'develop/go/versioning', 'develop/go/observability', 'develop/go/benign-exceptions',