diff --git a/docs/develop/dotnet/client/index.mdx b/docs/develop/dotnet/client/index.mdx index ba21be6851..5d191a7b56 100644 --- a/docs/develop/dotnet/client/index.mdx +++ b/docs/develop/dotnet/client/index.mdx @@ -2,9 +2,11 @@ id: index title: Client - .NET SDK sidebar_label: Client -description: This section explains how to implement the Temporal Client with the .NET SDK +description: + Connect a Temporal Client, start Workflow Executions, and get Workflow results with the Temporal .NET SDK. toc_max_heading_level: 4 tags: + - Temporal Client - .NET SDK - Temporal SDKs --- diff --git a/docs/develop/dotnet/client/temporal-client.mdx b/docs/develop/dotnet/client/temporal-client.mdx index ff2990e7a2..b14e8ba636 100644 --- a/docs/develop/dotnet/client/temporal-client.mdx +++ b/docs/develop/dotnet/client/temporal-client.mdx @@ -3,12 +3,13 @@ id: temporal-client title: Temporal Client - .NET SDK sidebar_label: Temporal Client description: - Create a Temporal Client, connect to Temporal Cloud, start a Workflow, and get Workflow results using the Temporal - .NET SDK with detailed steps and code examples. + Connect to a development Temporal Service or Temporal Cloud from .NET, set a Task Queue and Workflow Id, and get + Workflow Execution results. +toc_max_heading_level: 4 tags: + - Temporal Client - .NET SDK - Temporal SDKs - - Temporal Client - Certificates --- @@ -37,7 +38,7 @@ configuration. You can provide these options directly in code, or load them from **TOML configuration file** using the `Temporalio.Client.EnvConfig` helpers. We recommend environment variables or a configuration file for secure, repeatable configuration. -When you’re running a Temporal Service locally (such as with the +When you're running a Temporal Service locally (such as with the [Temporal CLI dev server](/cli/command-reference/server#start-dev)), the required options are minimal. If you don't specify a host/port, most connections default to `127.0.0.1:7233` and the `default` Namespace. @@ -314,10 +315,10 @@ tls_client_key_path = "your-tls-client-key-path" ``` With the connections options defined in the configuration file, use the `ClientEnvConfig.LoadClientConnectOptions` -method to create a Temporal Client using the `staging` profile as follows. After loading the profile, you can also +method to create a Temporal Client from a named profile as follows. After loading the profile, you can also programmatically override specific connection options before creating the client. -```csharp title="LoadProfile.cs" {25. 41} +```csharp title="LoadProfile.cs" {25,41} using Temporalio.Client; using Temporalio.Client.EnvConfig; @@ -467,7 +468,7 @@ var myClient = TemporalClient.ConnectAsync(new() }); ``` -Unlike `ApiKey`, `TlsOptions` is not mutable on an existing connection — the certificate bytes are fixed once the +Unlike `ApiKey`, `TlsOptions` is not mutable on an existing connection. The certificate bytes are fixed once the connection is established. To rotate an mTLS client certificate without restarting your Worker, connect a new client with the new certificate and assign it to the running `TemporalWorker`'s `Client` property: @@ -493,11 +494,11 @@ completion, Activity Heartbeats, and so on); calls already in flight on the old -## Start a Workflow {/* #start-workflow */} +## Start a Workflow Execution {/* #start-workflow */} -[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. +[Workflow Execution](/workflow-execution) semantics rely on several parameters. 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. A request to spawn a Workflow Execution causes the Temporal Service to create the first Event ([WorkflowExecutionStarted](/references/events#workflowexecutionstarted)) in the Workflow Execution Event History. The @@ -515,6 +516,38 @@ var result = await client.ExecuteWorkflowAsync( Console.WriteLine("Result: {0}", result); ``` +### Set a Workflow's Task Queue {/* #set-task-queue */} + +The only Workflow Option that you must set is the name of the [Task Queue](/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. + +To set a Task Queue in .NET, specify the `taskQueue` argument in the `WorkflowOptions` given to `StartWorkflowAsync()` +or `ExecuteWorkflowAsync()`. + +```csharp +var result = await client.ExecuteWorkflowAsync( + (MyWorkflow wf) => wf.RunAsync(), + new(id: "my-workflow-id", taskQueue: "my-task-queue")); +``` + +### Set a Workflow Id {/* #workflow-id */} + +You must set a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). + +When setting a Workflow Id, we recommend mapping it to a business process or business entity identifier, such as an +order identifier or customer identifier. + +To set a Workflow Id in .NET, specify the `id` argument in the `WorkflowOptions` given to `StartWorkflowAsync()` or +`ExecuteWorkflowAsync()`. + +```csharp +var result = await client.ExecuteWorkflowAsync( + (MyWorkflow wf) => wf.RunAsync(), + new(id: "my-workflow-id", taskQueue: "my-task-queue")); +``` + ## Get Workflow results {/* #get-workflow-results */} If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id. diff --git a/docs/develop/go/client/index.mdx b/docs/develop/go/client/index.mdx index 1ff3afc1cc..ccf0bfc419 100644 --- a/docs/develop/go/client/index.mdx +++ b/docs/develop/go/client/index.mdx @@ -2,9 +2,12 @@ id: index title: Client - Go SDK sidebar_label: Client -description: This section explains how to implement the Temporal Client with the Go SDK +description: + Connect a Temporal Client, start Workflow Executions, get Workflow results, and manage Namespaces with the + Temporal Go SDK. toc_max_heading_level: 4 tags: + - Temporal Client - Go SDK - Temporal SDKs --- diff --git a/docs/develop/go/client/namespaces.mdx b/docs/develop/go/client/namespaces.mdx index a2c1ea039c..1c52173eec 100644 --- a/docs/develop/go/client/namespaces.mdx +++ b/docs/develop/go/client/namespaces.mdx @@ -12,7 +12,7 @@ description: Register and manage Namespaces in Temporal using CLI or SDK APIs. I This page shows how to do the following: -- [Register Namespaces](#register-namespace) +- [Register a Namespace](#register-namespace) - [Manage Namespaces](#manage-namespaces) You can create, update, deprecate, or delete your [Namespaces](/namespaces) using either the Temporal CLI or SDK APIs. @@ -30,7 +30,7 @@ Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your You must register a Namespace with the Temporal Service before setting it in the Temporal Client. -### How to register Namespaces {/* #register-namespace */} +## Register a Namespace {/* #register-namespace */} Registering a Namespace creates a Namespace on the Temporal Service or Temporal Cloud. @@ -67,7 +67,7 @@ To update your Namespace, use the [`Update` API](https://pkg.go.dev/go.temporal. To update your Namespace using the Temporal CLI, use the [temporal operator namespace update](/cli/command-reference/operator#update) command. -### How to manage Namespaces {/* #manage-namespaces */} +## Manage Namespaces {/* #manage-namespaces */} You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces. diff --git a/docs/develop/go/client/temporal-client.mdx b/docs/develop/go/client/temporal-client.mdx index c0e60f8d21..d3ff30bd87 100644 --- a/docs/develop/go/client/temporal-client.mdx +++ b/docs/develop/go/client/temporal-client.mdx @@ -3,8 +3,8 @@ id: temporal-client title: Temporal Client - Go SDK sidebar_label: Temporal Client description: - Connect to Temporal Service or Cloud, start Workflow Executions, manage Workflow options, and retrieve Workflow - results using the Go SDK. Follow detailed steps and code examples to effectively use Temporal’s capabilities. + Connect to a development Temporal Service or Temporal Cloud from Go, set StartWorkflowOptions, and get Workflow + Execution results. toc_max_heading_level: 4 tags: - Temporal Client @@ -223,7 +223,6 @@ func main() { } } ``` -{/* SNIPEND */} @@ -563,11 +562,11 @@ apiKeyProvider.APIKey = myKeyUpdated -## Start Workflow Execution {/* #start-workflow-execution */} +## Start a Workflow Execution {/* #start-workflow-execution */} -[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. +[Workflow Execution](/workflow-execution) semantics rely on several parameters. 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](/develop/go/workflows/child-workflows) or External Workflow @@ -635,9 +634,9 @@ Workflow Type can be provided as a `string`. workflowRun, err := c.ExecuteWorkflow(context.Background(), workflowOptions, "YourWorkflowDefinition", param) ``` -### Set Workflow Task Queue {/* #set-task-queue */} +### Set a Workflow's Task Queue {/* #set-task-queue */} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). +The only Workflow Option that you must set is the name of the [Task Queue](/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. @@ -666,7 +665,7 @@ application load. For more information, refer to [Task Queues Processing Tuning](/develop/worker-performance/task-queues#task-queues-processing-tuning) and [Worker Versioning](/worker-versioning). -### Set custom Workflow Id {/* #workflow-id */} +### Set a Workflow Id {/* #workflow-id */} Although it is not required, we recommend providing your own [Workflow Id](/workflow-execution/workflowid-runid#workflow-id) that maps to a business process or business entity @@ -943,7 +942,7 @@ if err != nil { } ``` -### Get Workflow results {/* #get-workflow-results */} +## Get Workflow results {/* #get-workflow-results */} If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id. @@ -972,8 +971,9 @@ following line. 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. +- `GetRunID()`: Always returns the Run Id of the initial Run (see + [Continue-As-New](/workflow-execution/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 @@ -994,11 +994,10 @@ To wait on the result of Workflow Execution in the same process that invoked it, ``` 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. - -{/* TODO (See [How long do Workflow Execution Histories persist](#)). */} +the [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). +(A [Run Id](/workflow-execution/workflowid-runid#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 @@ -1017,7 +1016,7 @@ to populate the result. // ... ``` -**Get last completion result** +### Get last completion result In the case of a [Temporal Cron Job](/cron-job), you might need to get the result of the previous Workflow Run and use it in the current Workflow Run. diff --git a/docs/develop/java/client/index.mdx b/docs/develop/java/client/index.mdx index c9744f8509..f35c4168af 100644 --- a/docs/develop/java/client/index.mdx +++ b/docs/develop/java/client/index.mdx @@ -2,9 +2,12 @@ id: index title: Client - Java SDK sidebar_label: Client -description: This section explains how to implement the Temporal Client with the Java SDK +description: + Connect a Temporal Client, start Workflow Executions, get Workflow results, and manage Namespaces with the + Temporal Java SDK. toc_max_heading_level: 4 tags: + - Temporal Client - Java SDK - Temporal SDKs --- diff --git a/docs/develop/java/client/temporal-client.mdx b/docs/develop/java/client/temporal-client.mdx index e46f6f2253..490e773075 100644 --- a/docs/develop/java/client/temporal-client.mdx +++ b/docs/develop/java/client/temporal-client.mdx @@ -2,10 +2,10 @@ id: temporal-client title: Temporal Client - Java SDK sidebar_label: Temporal Client -toc_max_heading_level: 3 +toc_max_heading_level: 4 description: - This guide introduces Temporal Clients, explaining their role and configuration in Java to connect to various Temporal - Services, including starting Workflow Executions and customizing Workflow options. + Connect to a development Temporal Service or Temporal Cloud from Java, set WorkflowOptions, and get Workflow + Execution results. tags: - Temporal Client - Java SDK @@ -34,7 +34,7 @@ Temporal Client inside an Activity to communicate with a Temporal Service. ::: -## Connect to a development Temporal Service {/* #connect-to-development-service */} +## Connect to development Temporal Service {/* #connect-to-development-service */} Use the `newLocalServiceStubs` method to create a stub that points to the Temporal development service, and then use the [`WorkflowClient.newInstance` method](https://javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowClient.html#newInstance(io.temporal.serviceclient.WorkflowServiceStubs)) @@ -597,9 +597,9 @@ its next scheduled check, and the Worker keeps running against the same `client` ## Start a Workflow Execution {/* #start-workflow-execution */} -[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. +[Workflow Execution](/workflow-execution) semantics rely on several parameters. 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](/develop/java/workflows/child-workflows) or External Workflow @@ -619,7 +619,7 @@ Workflow Execution from within a Workflow. See [`SignalwithStart`](/develop/java/workflows/message-passing#signal-with-start) to start a Workflow Execution to receive a Signal from within another Workflow. -**Using `WorkflowStub`** +### Use WorkflowStub `WorkflowStub` is a proxy generated by the `WorkflowClient`. Each time a new Workflow Execution is started, an instance of the Workflow implementation object is created. Then, one of the methods (depending on the Workflow Type of the @@ -634,7 +634,7 @@ You can use a typed or untyped `WorkflowStub` in the client code. has methods from the `WorkflowStub` interface, such as `start`, `signalWithStart`, `getResults` (sync and async), `query`, `signal`, `cancel` and `terminate`. Note that the Temporal Java SDK also provides typed `WorkflowStub` versions for these methods. When using untyped `WorkflowStub`, we rely on the Workflow Type, Activity Type, Child - Workflow Type, as well as Query and Signal names. For details, see [Temporal Client](#connect-to-development-service). + Workflow Type, as well as Query and Signal names. For details, see [Temporal Client](/encyclopedia/temporal-client). A Workflow Execution can be started either synchronously or asynchronously. @@ -721,7 +721,7 @@ String type = Workflow.getInfo().getWorkflowType(); See [Workflow Execution Result](#get-workflow-results) for details on how to get the results of the Workflow Execution. -**Using `ExternalWorkflowStub`** +### Use ExternalWorkflowStub Use `ExternalWorkflowStub` within a Workflow to invoke, and send Signals to, other Workflows by type. @@ -737,14 +737,14 @@ This helps particularly for executing Workflows written in other language SDKs, See the [Temporal Polyglot](https://github.com/tsurdilo/temporal-polyglot) code for examples of executing Workflows written in other language SDKs. -**Recurring start** +### Start a Workflow on a schedule You can start a Workflow Execution on a regular schedule by using [`setCronSchedule`](/develop/java/workflows/schedules#cron-schedule) Workflow option in the Client code. -### How to set a Workflow's Task Queue {/* #set-task-queue */} +### Set a Workflow's Task Queue {/* #set-task-queue */} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). +The only Workflow Option that you must set is the name of the [Task Queue](/task-queue). For your code to execute, a Worker Process must be running. This process needs a Worker Entity that is polling the same Task Queue name. @@ -769,7 +769,7 @@ YourWorkflowInterface workflow1 = .build()); ``` -### How to set a Workflow Id {/* #workflow-id */} +### Set a Workflow Id {/* #workflow-id */} Although it is not required, we recommend providing your own [Workflow Id](/workflow-execution/workflowid-runid#workflow-id) that maps to a business process or business entity @@ -778,7 +778,7 @@ identifier, such as an order identifier or customer identifier. Set the Workflow Id with the [`WorkflowStub`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowStub.html) instance in the Client code using -[`WorkflowOptions.Builder.setWorkflowId​`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowOptions.Builder.html). +[`WorkflowOptions.Builder.setWorkflowId`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowOptions.Builder.html). - Type: `String` - Default: none @@ -815,7 +815,7 @@ The following fields are available: | [`WorkflowIdReusePolicy`](#workflowidreusepolicy) | No | `WorkflowIdReusePolicy` | | [`RetryOptions`](#retryoptions) | No | [`RetryOptions`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/common/RetryOptions.html) | | [`CronSchedule`](#cronschedule) | No | String | -| [`Memo`](#memo) | No | string | +| [`Memo`](#memo) | No | `String` | | [`SearchAttributes`](#searchattributes) | No | `Map` | #### WorkflowId @@ -823,7 +823,7 @@ The following fields are available: Set the Workflow Id with the [`WorkflowStub`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowStub.html) instance in the Client code using -[`WorkflowOptions.Builder.setWorkflowId​`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowOptions.Builder.html). +[`WorkflowOptions.Builder.setWorkflowId`](https://www.javadoc.io/doc/io.temporal/temporal-sdk/latest/io/temporal/client/WorkflowOptions.Builder.html). - Type: `String` - Default: none @@ -1060,7 +1060,7 @@ The following Java types are supported: - OffsetDateTime - Collection of the types in this list. -### How to get the result of a Workflow Execution in Java {/* #get-workflow-results */} +## Get Workflow results {/* #get-workflow-results */} If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id. @@ -1145,7 +1145,7 @@ WorkflowStub workflowStub = client.newUntypedWorkflowStub(workflowType, workflow String result = untyped.getResult(String.class); ``` -**Get last (successful) completion result** +### Get last completion result For a Temporal Cron Job, get the result of previous successful runs using `GetLastCompletionResult()`. The method returns `null` if there is no previous completion. The following example shows how to implement this in a Workflow. diff --git a/docs/develop/php/client/index.mdx b/docs/develop/php/client/index.mdx index 62e6808389..d8ab45dbf6 100644 --- a/docs/develop/php/client/index.mdx +++ b/docs/develop/php/client/index.mdx @@ -2,9 +2,11 @@ id: index title: Client - PHP SDK sidebar_label: Client -description: This section explains how to implement the Temporal Client with the PHP SDK +description: + Connect a Temporal Client, start Workflow Executions, and get Workflow results with the Temporal PHP SDK. toc_max_heading_level: 4 tags: + - Temporal Client - PHP SDK - Temporal SDKs --- diff --git a/docs/develop/php/client/temporal-client.mdx b/docs/develop/php/client/temporal-client.mdx index 9700816aae..b4c44788fe 100644 --- a/docs/develop/php/client/temporal-client.mdx +++ b/docs/develop/php/client/temporal-client.mdx @@ -2,28 +2,17 @@ id: temporal-client title: Temporal Client - PHP SDK sidebar_label: Temporal Client -slug: /develop/php/client/temporal-client -toc_max_heading_level: 3 +toc_max_heading_level: 4 tags: - Temporal Client - PHP SDK - Temporal SDKs - Certificates -description: Connect a Temporal Client to a Temporal Service and start Workflow Executions. This guide covers communication, including sending signals and queries. +description: + Connect to a development Temporal Service or Temporal Cloud from PHP, start Workflow Executions, and configure RPC + retries and timeouts. --- -This guide introduces Temporal Clients. -It explains the role and use of Clients and shows you how to configure your PHP Client code to connect to the Temporal Service. - -This page shows how to do the following: - -- [Connect to a local development Temporal Service](#connect-to-a-dev-cluster) -- [Connect to Temporal Cloud](#connect-to-temporal-cloud) -- [Start a Workflow Execution](#start-workflow-execution) -- [Advanced connection options](#advanced-connection-options) - -## How to connect a Temporal Client to a Temporal Service {/* #connect-to-a-dev-cluster */} - A [Temporal Client](/encyclopedia/temporal-client) enables you to communicate with the [Temporal Service](/temporal-service). Communication with a Temporal Service includes, but isn't limited to, the following: @@ -35,6 +24,14 @@ Communication with a Temporal Service includes, but isn't limited to, the follow - Getting the results of a Workflow Execution. - Providing an Activity Task Token. +This page shows you how to do the following using the PHP SDK with the Temporal Client: + +- [Connect to a local development Temporal Service](#connect-to-a-dev-cluster) +- [Connect to Temporal Cloud](#connect-to-temporal-cloud) +- [Start a Workflow Execution](#start-workflow-execution) +- [Get Workflow results](#get-workflow-results) +- [Advanced connection options](#advanced-connection-options) + :::caution A Temporal Client cannot be initialized and used inside a Workflow. @@ -42,6 +39,8 @@ However, it is acceptable and common to use a Temporal Client inside an Activity ::: +## Connect to development Temporal Service {/* #connect-to-a-dev-cluster */} + When you are running a Temporal Service locally (such as the [Temporal CLI](/cli/command-reference/server#start-dev)), the number of connection options you must provide is minimal. Many SDKs default to `127.0.0.1:7233`. @@ -69,7 +68,7 @@ $workflowClient = WorkflowClient::create($serviceClient); See the [Advanced connection options](#advanced-connection-options) section for more information on configuring the connection. -## How to connect a Temporal Client to a Temporal Cloud {/* #connect-to-temporal-cloud */} +## Connect to Temporal Cloud {/* #connect-to-temporal-cloud */} When you connect to [Temporal Cloud](/cloud), you need to provide additional connection and client options that include the following: @@ -127,16 +126,16 @@ $serviceClient = \Temporal\Client\GRPC\ServiceClient::createSSL(/*...*/) ->withAuthKey('your-api-key'); ``` -Rotating an mTLS client certificate without restarting the Worker isn't currently supported by the PHP SDK or RoadRunner -— the certificate configured on `ServiceClient::createSSL()` or in RoadRunner's `tls:` block is fixed for the life of -the process. To rotate a certificate, stage the new certificate alongside the old one on your Temporal Cloud Namespace, -then restart your Worker (RoadRunner process) with the new certificate before removing the old one. See +Rotating an mTLS client certificate without restarting the Worker isn't currently supported by the PHP SDK or +RoadRunner. The certificate configured on `ServiceClient::createSSL()` or in RoadRunner's `tls:` block is fixed for the +life of the process. To rotate a certificate, stage the new certificate alongside the old one on your Temporal Cloud +Namespace, then restart your Worker (RoadRunner process) with the new certificate before removing the old one. See [Update certificates using Temporal Cloud UI/tcld](/cloud/certificates#manage-certificates) for the zero-downtime staging sequence. -## How to start a Workflow Execution {/* #start-workflow-execution */} +## Start a Workflow Execution {/* #start-workflow-execution */} -[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. +[Workflow Execution](/workflow-execution) semantics rely on several parameters. 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 following all Workflow Executions are started using a Temporal Client. To spawn Workflow Executions from within another Workflow Execution, use either the [Child Workflow](/develop/php/workflows/child-workflows) or External Workflow APIs. @@ -198,7 +197,7 @@ $stub->update('finish'); A Workflow Execution can be started either synchronously or asynchronously. -**Synchronous start** +### Start a Workflow synchronously 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. @@ -226,7 +225,7 @@ $accountTransfer = $workflowClient->newWorkflowStub( $result = $accountTransfer->transfer('fromID', 'toID', 'refID', 1000); ``` -**Asynchronous start** +### Start a Workflow asynchronously 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. @@ -256,11 +255,11 @@ var_dump($run->describe()); var_dump($run->getResult(timeout: 10)); ``` -**Recurring start** +### Start a Workflow on a schedule You can start a Workflow Execution on a regular schedule with [the CronSchedule option](/develop/php/workflows/schedules#temporal-cron-jobs). -### How to set a Workflow's Task Queue {/* #set-task-queue */} +### Set a Workflow's Task Queue {/* #set-task-queue */} In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). When developing in PHP, the Task Queue name defaults to `"default"`. @@ -285,11 +284,11 @@ $stub = $workflowClient->newWorkflowStub( ); ``` -### How to set a Workflow Id {/* #workflow-id */} +### Set a Workflow Id {/* #workflow-id */} -Although it is not required, we recommend providing your own [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)that maps to a business process or business entity identifier, such as an order identifier or customer identifier. +Although it is not required, we recommend providing your own [Workflow Id](/workflow-execution/workflowid-runid#workflow-id) that maps to a business process or business entity identifier, such as an order identifier or customer identifier. -Set the Workflow Id with the Workflow stub in the Client code using [`WorkflowOptions::withTaskQueue()`](https://php.temporal.io/classes/Temporal-Client-WorkflowOptions.html#method_withWorkflowId). +Set the Workflow Id with the Workflow stub in the Client code using [`WorkflowOptions::withWorkflowId()`](https://php.temporal.io/classes/Temporal-Client-WorkflowOptions.html#method_withWorkflowId). ```php $stub = $workflowClient->newWorkflowStub( @@ -299,7 +298,7 @@ $stub = $workflowClient->newWorkflowStub( ); ``` -### How to get the results of a Workflow Execution {/* #get-workflow-results */} +## Get Workflow results {/* #get-workflow-results */} If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id. diff --git a/docs/develop/python/client/index.mdx b/docs/develop/python/client/index.mdx index ae21f078e0..b0ac1d16f1 100644 --- a/docs/develop/python/client/index.mdx +++ b/docs/develop/python/client/index.mdx @@ -2,9 +2,11 @@ id: index title: Client - Python SDK sidebar_label: Client -description: This section explains how to implement the Temporal Client with the Python SDK +description: + Connect a Temporal Client, start Workflow Executions, and get Workflow results with the Temporal Python SDK. toc_max_heading_level: 4 tags: + - Temporal Client - Python SDK - Temporal SDKs --- diff --git a/docs/develop/python/client/temporal-client.mdx b/docs/develop/python/client/temporal-client.mdx index c0d92785ec..8a6b112a65 100644 --- a/docs/develop/python/client/temporal-client.mdx +++ b/docs/develop/python/client/temporal-client.mdx @@ -4,8 +4,8 @@ title: Temporal Client - Python SDK sidebar_label: Temporal Client toc_max_heading_level: 4 description: - Discover how to connect and use Temporal Clients with Python. Link your Client to Temporal Service, Temporal Cloud, - start Workflow Executions, set Task Queues, Workflow Ids, and get Workflow results. + Connect to a development Temporal Service or Temporal Cloud from Python, set a Task Queue and Workflow Id, and get + Workflow Execution results. tags: - Temporal Client - Python SDK @@ -37,7 +37,7 @@ options directly in code, load them from **environment variables**, or a **TOML [`envconfig`](https://python.temporal.io/temporalio.envconfig.html) helpers. We recommend environment variables or a configuration file for secure, repeatable configuration. -When you’re running a Temporal Service locally (such as with the +When you're running a Temporal Service locally (such as with the [Temporal CLI dev server](/cli/command-reference/server#start-dev)), the required options are minimal. If you don't specify a host/port, most connections default to `127.0.0.1:7233` and the `default` Namespace. @@ -485,9 +485,9 @@ Heartbeats, and so on); calls already in flight on the old client finish normall ## Start a Workflow Execution {/* #start-workflow-execution */} -[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. +[Workflow Execution](/workflow-execution) semantics rely on several parameters. 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](/develop/python/workflows/child-workflows) or External Workflow @@ -527,7 +527,7 @@ if __name__ == "__main__": ### Set a Workflow's Task Queue {/* #set-task-queue */} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). +The only Workflow Option that you must set is the name of the [Task Queue](/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. @@ -559,7 +559,7 @@ if __name__ == "__main__": You must set a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). -When setting a Workflow Id, we recommended mapping it to a business process or business entity identifier, such as an +When setting a Workflow Id, we recommend mapping it to a business process or business entity identifier, such as an order identifier or customer identifier. To set a Workflow Id in Python, specify the `id` argument when executing a Workflow with either @@ -587,7 +587,7 @@ if __name__ == "__main__": asyncio.run(main()) ``` -### Get the results of a Workflow Execution {/* #get-workflow-results */} +## Get Workflow results {/* #get-workflow-results */} If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id. diff --git a/docs/develop/ruby/client/index.mdx b/docs/develop/ruby/client/index.mdx index 819a1ff70e..43235ed84f 100644 --- a/docs/develop/ruby/client/index.mdx +++ b/docs/develop/ruby/client/index.mdx @@ -2,9 +2,11 @@ id: index title: Client - Ruby SDK sidebar_label: Client -description: This section explains how to implement the Temporal Client with the Ruby SDK +description: + Connect a Temporal Client, start Workflow Executions, and get Workflow results with the Temporal Ruby SDK. toc_max_heading_level: 4 tags: + - Temporal Client - Ruby SDK - Temporal SDKs --- @@ -13,7 +15,7 @@ import * as Components from '@site/src/components'; -![.NET SDK Banner](/img/assets/banner-ruby-temporal.png) +![Ruby SDK Banner](/img/assets/banner-ruby-temporal.png) diff --git a/docs/develop/ruby/client/temporal-client.mdx b/docs/develop/ruby/client/temporal-client.mdx index c4912838c2..99dbd60c01 100644 --- a/docs/develop/ruby/client/temporal-client.mdx +++ b/docs/develop/ruby/client/temporal-client.mdx @@ -3,12 +3,13 @@ id: temporal-client title: Temporal Client - Ruby SDK sidebar_label: Temporal Client description: - Create a Temporal Client, connect to Temporal Cloud, start a Workflow, and get Workflow results using the Temporal - Ruby SDK. + Connect to a development Temporal Service or Temporal Cloud from Ruby, set a Task Queue and Workflow Id, and get + Workflow Execution results. +toc_max_heading_level: 4 tags: + - Temporal Client - Ruby SDK - Temporal SDKs - - Temporal Client - Certificates --- @@ -36,7 +37,7 @@ these options directly in code, load them from **environment variables**, or a * [`EnvConfig`](https://ruby.temporal.io/Temporalio/EnvConfig.html) helpers. We recommend environment variables or a configuration file for secure, repeatable configuration. -When you’re running a Temporal Service locally (such as with the +When you're running a Temporal Service locally (such as with the [Temporal CLI dev server](/cli/command-reference/server#start-dev)), the required options are minimal. If you don't specify a host/port, most connections default to `127.0.0.1:7233` and the `default` Namespace. @@ -435,7 +436,7 @@ client finish normally. -## Start a Workflow {/* #start-workflow */} +## Start a Workflow Execution {/* #start-workflow */} To start a Workflow Execution, supply: @@ -456,6 +457,38 @@ result = my_client.execute_workflow( puts "Result: #{result}" ``` +### Set a Workflow's Task Queue {/* #set-task-queue */} + +The only Workflow Option that you must set is the name of the [Task Queue](/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. + +To set a Task Queue in Ruby, specify the `task_queue` keyword argument on `start_workflow` or `execute_workflow`. + +```ruby +result = my_client.execute_workflow( + MyWorkflow, 'some-input', + id: 'my-workflow-id', task_queue: 'my-task-queue' +) +``` + +### Set a Workflow Id {/* #workflow-id */} + +You must set a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). + +When setting a Workflow Id, we recommend mapping it to a business process or business entity identifier, such as an +order identifier or customer identifier. + +To set a Workflow Id in Ruby, specify the `id` keyword argument on `start_workflow` or `execute_workflow`. + +```ruby +result = my_client.execute_workflow( + MyWorkflow, 'some-input', + id: 'my-workflow-id', task_queue: 'my-task-queue' +) +``` + ## Get Workflow results {/* #get-workflow-results */} Once a Workflow Execution is started, the Workflow Id and Run Id can be used to uniquely identify it. diff --git a/docs/develop/rust/client/index.mdx b/docs/develop/rust/client/index.mdx index e4288f816f..6bc68f9b4d 100644 --- a/docs/develop/rust/client/index.mdx +++ b/docs/develop/rust/client/index.mdx @@ -3,9 +3,10 @@ id: index title: Client - Rust SDK sidebar_label: Client description: - This section explains how to implement the Client with the Rust SDK + Connect a Temporal Client, start Workflow Executions, and get Workflow results with the Temporal Rust SDK. toc_max_heading_level: 4 tags: + - Temporal Client - Rust SDK - Temporal SDKs --- diff --git a/docs/develop/rust/client/temporal-client.mdx b/docs/develop/rust/client/temporal-client.mdx index c2255495b8..5cba9adfef 100644 --- a/docs/develop/rust/client/temporal-client.mdx +++ b/docs/develop/rust/client/temporal-client.mdx @@ -4,8 +4,8 @@ title: Temporal Client - Rust SDK sidebar_label: Temporal Client toc_max_heading_level: 4 description: - Discover how to connect and use Temporal Clients with Rust. Connect your Client to Temporal Service or Temporal Cloud, - start Workflow Executions, set Task Queues and Workflow Ids, and get Workflow results. + Connect to a development Temporal Service or Temporal Cloud from Rust, set a Task Queue and Workflow Id, and get + Workflow Execution results. tags: - Temporal Client - Rust SDK @@ -327,7 +327,7 @@ let handle = client.start_workflow( ### Set a Workflow's Task Queue {/* #set-task-queue */} -In most cases, the Task Queue is a required Workflow option. +The only Workflow Option that you must set is the name of the [Task Queue](/task-queue). For a Workflow to make progress, at least one Worker must be polling the same Task Queue. @@ -349,7 +349,8 @@ let handle = client You must set a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). -A Workflow Id should usually map to a business process or business entity identifier, such as an order ID or customer ID. +A Workflow Id should usually map to a business process or business entity identifier, such as an order identifier or +customer identifier. In Rust, set the Workflow Id in `WorkflowStartOptions`: @@ -365,7 +366,7 @@ let handle = client ).await?; ``` -## Get the results of a Workflow Execution {/* #get-workflow-results */} +## Get Workflow results {/* #get-workflow-results */} If starting a Workflow succeeds, you get a Workflow handle. You can use that handle to wait for the result, describe the Workflow, or interact with it through Signals, Queries, and Updates. diff --git a/docs/develop/typescript/client/index.mdx b/docs/develop/typescript/client/index.mdx index f9daa66c93..4e34fabb2b 100644 --- a/docs/develop/typescript/client/index.mdx +++ b/docs/develop/typescript/client/index.mdx @@ -3,9 +3,11 @@ id: index title: Client - TypeScript SDK sidebar_label: Client description: - This section explains how to implement the Client with the TypeScript SDK + Connect a Temporal Client, start Workflow Executions, get Workflow results, and manage Namespaces with the + Temporal TypeScript SDK. toc_max_heading_level: 4 tags: + - Temporal Client - TypeScript SDK - Temporal SDKs --- diff --git a/docs/develop/typescript/client/namespaces.mdx b/docs/develop/typescript/client/namespaces.mdx index c42a1d78be..c742ad8d84 100644 --- a/docs/develop/typescript/client/namespaces.mdx +++ b/docs/develop/typescript/client/namespaces.mdx @@ -1,17 +1,19 @@ --- id: namespaces -title: Manage Namespaces - TypeScript SDK +title: Namespaces - TypeScript SDK sidebar_label: Namespaces -slug: /develop/typescript/client/namespaces -toc_max_heading_level: 2 +toc_max_heading_level: 4 tags: - Namespaces - TypeScript SDK - Temporal SDKs -description: Efficiently create and manage Namespaces on Temporal using CLI or SDK APIs. Isolate Workflow Executions, control access with custom Authorizers, and manage via Temporal Cloud UI or CLI. +description: Register and manage Namespaces with the Temporal CLI or SDK APIs. Isolate Workflow Executions, match development lifecycles, and restrict access with a custom Authorizer. --- -## How to create and manage Namespaces {/* #namespaces */} +This page shows how to do the following: + +- [Register a Namespace](#register-namespace) +- [Manage Namespaces](#manage-namespaces) You can create, update, deprecate or delete your [Namespaces](/namespaces) using either the Temporal CLI or SDK APIs. @@ -28,7 +30,7 @@ Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your You must register a Namespace with the Temporal Service before setting it in the Temporal Client. -### How to register Namespaces {/* #register-namespace */} +## Register a Namespace {/* #register-namespace */} Registering a Namespace creates a Namespace on the Temporal Service or Temporal Cloud. @@ -39,7 +41,7 @@ Note that these APIs and `temporal operator namespace` commands will not work wi Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Frontend Service in the Temporal Service to set restrictions on who can create, update, or deprecate Namespaces. -### How to manage Namespaces {/* #manage-namespaces */} +## Manage Namespaces {/* #manage-namespaces */} You can get details for your Namespaces, update Namespace configuration, and deprecate or delete your Namespaces. diff --git a/docs/develop/typescript/client/temporal-client.mdx b/docs/develop/typescript/client/temporal-client.mdx index ce3e5b1140..1bc4133f2e 100644 --- a/docs/develop/typescript/client/temporal-client.mdx +++ b/docs/develop/typescript/client/temporal-client.mdx @@ -4,8 +4,8 @@ title: Temporal Client - TypeScript SDK sidebar_label: Temporal Client toc_max_heading_level: 4 description: - The Temporal Client SDK enables seamless communication with the Temporal Service, allowing applications to start - Workflow Executions, send Signals, and query Workflows efficiently. + Connect to a development Temporal Service or Temporal Cloud from TypeScript, connect a Worker with NativeConnection, + and get Workflow Execution results. tags: - Temporal Client - TypeScript SDK @@ -637,11 +637,11 @@ When instantiating a `Connection`, you specify most connection options except fo Service endpoint, TLS settings, and authentication credentials. When instantiating a `Client`, you provide the `Connection` object and the Namespace you want to connect to, along with other client options. -## Start Workflow Execution {/* #start-workflow-execution */} +## Start a Workflow Execution {/* #start-workflow-execution */} -[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. +[Workflow Execution](/workflow-execution) semantics rely on several parameters. 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. @@ -676,12 +676,12 @@ You can test this by executing a Client command without a matching Worker. Tempo History, but does not make progress with the Workflow Execution until a Worker starts polling with a matching Task Queue and Workflow Definition. -Workflow Execution run in a separate V8 isolate context in order to provide a +Workflow Executions run in a separate V8 isolate context to provide a [deterministic runtime](/workflow-definition#deterministic-constraints). ### Set a Workflow's Task Queue {/* #set-task-queue */} -In most SDKs, the only Workflow Option that must be set is the name of the [Task Queue](/task-queue). +The only Workflow Option that you must set is the name of the [Task Queue](/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. @@ -782,7 +782,7 @@ const handle = await client.workflow.start(example, { This starts a new Client with the given Workflow Id, Task Queue name, and an argument. -### Get the results of a Workflow Execution {/* #get-workflow-results */} +## Get Workflow results {/* #get-workflow-results */} If the call to start a Workflow Execution is successful, you will gain access to the Workflow Execution's Run Id. @@ -804,7 +804,7 @@ return 'Completed ' + wf.workflowInfo().workflowId + ', Total Charged: ' + total `totalCharged` is just a function declared in your code. For a full example, see [subscription-workflow-project-template-typescript/src/workflows.ts](https://github.com/temporalio/subscription-workflow-project-template-typescript/blob/main/src/workflows.ts). -A Workflow function may return a result. If it doesn’t (in which case the return type is `Promise`), the result +A Workflow function may return a result. If it doesn't (in which case the return type is `Promise`), the result will be `undefined`. If you started a Workflow with `client.workflow.start()`, you can choose to wait for the result anytime with @@ -817,8 +817,6 @@ const result = await handle.result(); Using a Workflow Handle isn't necessary with `client.workflow.execute()`. -Workflows that prematurely end will throw a `WorkflowFailedError` if you call `result()`. - If you call `result()` on a Workflow that prematurely ended for some reason, it throws a [`WorkflowFailedError` error](https://typescript.temporal.io/api/classes/client.WorkflowFailedError/) that reflects the reason. For that reason, it is recommended to catch that error.