From 07ad319895223f7da5634bf80f1d514acb1a00dc Mon Sep 17 00:00:00 2001 From: Sean Kane Date: Fri, 11 Jul 2025 14:13:41 -0600 Subject: [PATCH] docs: update temporal activity docstrings to reflect documentation --- temporalcli/commands.gen.go | 38 +++++----- temporalcli/commandsgen/commands.yml | 103 ++++++++++++++++----------- 2 files changed, 80 insertions(+), 61 deletions(-) diff --git a/temporalcli/commands.gen.go b/temporalcli/commands.gen.go index 1e5a68d7a..9bf6c8ec3 100644 --- a/temporalcli/commands.gen.go +++ b/temporalcli/commands.gen.go @@ -503,14 +503,14 @@ func NewTemporalActivityPauseCommand(cctx *CommandContext, parent *TemporalActiv s.Command.Use = "pause [flags]" s.Command.Short = "Pause an Activity" if hasHighlighting { - s.Command.Long = "Pause an Activity.\n\nIf the Activity is not currently running (e.g. because it previously\nfailed), it will not be run again until it is unpaused.\n\nHowever, if the Activity is currently running, it will run to completion.\nIf the Activity is on its last retry attempt and fails, the failure will\nbe returned to the caller, just as if the Activity had not been paused.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided. If both are provided - Activity\nType will be used, and Activity ID will be ignored.\n\nSpecify the Activity and Workflow IDs:\n\n\x1b[1mtemporal activity pause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\x1b[0m" + s.Command.Long = "Pause an Activity.\n\nIf the Activity is not currently running (e.g. because it previously\nfailed), it will not be run again until it is unpaused.\n\nHowever, if the Activity is currently running, it will run until the next \ntime it fails, completes, or times out, at which point the pause will kick in.\n\nIf the Activity is on its last retry attempt and fails, the failure will\nbe returned to the caller, just as if the Activity had not been paused.\n\nActivities should be specified either by their Activity ID or Activity Type.\n\nFor example, specify the Activity and Workflow IDs like this:\n\n\x1b[1mtemporal activity pause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\x1b[0m\n\nTo later unpause the activity, see unpause. You may also want to \nreset the activity to unpause it while also starting it from the beginning." } else { - s.Command.Long = "Pause an Activity.\n\nIf the Activity is not currently running (e.g. because it previously\nfailed), it will not be run again until it is unpaused.\n\nHowever, if the Activity is currently running, it will run to completion.\nIf the Activity is on its last retry attempt and fails, the failure will\nbe returned to the caller, just as if the Activity had not been paused.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided. If both are provided - Activity\nType will be used, and Activity ID will be ignored.\n\nSpecify the Activity and Workflow IDs:\n\n```\ntemporal activity pause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n```" + s.Command.Long = "Pause an Activity.\n\nIf the Activity is not currently running (e.g. because it previously\nfailed), it will not be run again until it is unpaused.\n\nHowever, if the Activity is currently running, it will run until the next \ntime it fails, completes, or times out, at which point the pause will kick in.\n\nIf the Activity is on its last retry attempt and fails, the failure will\nbe returned to the caller, just as if the Activity had not been paused.\n\nActivities should be specified either by their Activity ID or Activity Type.\n\nFor example, specify the Activity and Workflow IDs like this:\n\n```\ntemporal activity pause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n```\n\nTo later unpause the activity, see unpause. You may also want to \nreset the activity to unpause it while also starting it from the beginning." } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "Activity ID to pause. Either `activity-id` or `activity-type` must be provided, but not both.") - s.Command.Flags().StringVarP(&s.ActivityType, "activity-type", "g", "", "Either `activity-id` or `activity-type` must be provided, but not both.Activity Type to pause.") - s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of the user submitting this request.") + s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "The Activity ID to pause. Either `activity-id` or `activity-type` must be provided, but not both.") + s.Command.Flags().StringVarP(&s.ActivityType, "activity-type", "g", "", "All activities of the Activity Type will be paused. Either `activity-id` or `activity-type` must be provided, but not both.") + s.Command.Flags().StringVar(&s.Identity, "identity", "", "The identity of the user or client submitting this request.") s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -538,16 +538,16 @@ func NewTemporalActivityResetCommand(cctx *CommandContext, parent *TemporalActiv s.Command.Use = "reset [flags]" s.Command.Short = "Reset an Activity" if hasHighlighting { - s.Command.Long = "Resetting an activity resets both the number of attempts and the activity\ntimeout.\n\nIf activity is paused and 'keep_paused' flag is not provided - it will be\nunpaused.\nIf activity is paused and 'keep_paused' flag is provided - it will stay\npaused.\nIf activity is waiting for the retry, is will be rescheduled immediately.\nIf the 'reset_heartbeats' flag is set, the activity heartbeat timer and\nheartbeats will be reset.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided. If both are provided - Activity\nType will be used, and Activity ID will be ignored.\n\nSpecify the Activity Type of ID and Workflow IDs:\n\n\x1b[1mtemporal activity reset \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --keep-paused\n --reset-heartbeats\x1b[0m" + s.Command.Long = "Resetting an activity restarts the activity as if it were first being \nscheduled. That is, it will reset both the number of attempts and the \nactivity timeout, as well as, optionally, the \nheartbeat details.\n\nIf the activity may be executing (i.e. it has not yet timed out), the \nreset will take effect the next time it fails, heartbeats, or times out.\nIf is waiting for a retry (i.e. has failed or timed out), the reset \nwill apply immediately.\n\nIf the activity is already paused, it will be unpaused by default. \nYou can specify \x1b[1mkeep_paused\x1b[0m to prevent this.\n\nIf the activity is paused and the \x1b[1mkeep_paused\x1b[0m flag is not provided, \nit will be unpaused. If the activity is paused and \x1b[1mkeep_paused\x1b[0m flag \nis provided - it will stay paused.\n\nActivities can be specified by their Activity ID or Activity Type.\n\n### Resetting activities that heartbeat {#reset-heartbeats}\n\nActivities that heartbeat will receive a Canceled failure \nthe next time they heartbeat after a reset.\n\nIf, in your Activity, you need to do any cleanup when an Activity is \nreset, handle this error and then re-throw it when you've cleaned up.\n\nIf the \x1b[1mreset_heartbeats\x1b[0m flag is set, the heartbeat details will also be cleared.\n\nSpecify the Activity Type of ID and Workflow IDs:\n\n\x1b[1mtemporal activity reset \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --keep-paused\n --reset-heartbeats\x1b[0m" } else { - s.Command.Long = "Resetting an activity resets both the number of attempts and the activity\ntimeout.\n\nIf activity is paused and 'keep_paused' flag is not provided - it will be\nunpaused.\nIf activity is paused and 'keep_paused' flag is provided - it will stay\npaused.\nIf activity is waiting for the retry, is will be rescheduled immediately.\nIf the 'reset_heartbeats' flag is set, the activity heartbeat timer and\nheartbeats will be reset.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided. If both are provided - Activity\nType will be used, and Activity ID will be ignored.\n\nSpecify the Activity Type of ID and Workflow IDs:\n\n```\ntemporal activity reset \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --keep-paused\n --reset-heartbeats\n```" + s.Command.Long = "Resetting an activity restarts the activity as if it were first being \nscheduled. That is, it will reset both the number of attempts and the \nactivity timeout, as well as, optionally, the \nheartbeat details.\n\nIf the activity may be executing (i.e. it has not yet timed out), the \nreset will take effect the next time it fails, heartbeats, or times out.\nIf is waiting for a retry (i.e. has failed or timed out), the reset \nwill apply immediately.\n\nIf the activity is already paused, it will be unpaused by default. \nYou can specify `keep_paused` to prevent this.\n\nIf the activity is paused and the `keep_paused` flag is not provided, \nit will be unpaused. If the activity is paused and `keep_paused` flag \nis provided - it will stay paused.\n\nActivities can be specified by their Activity ID or Activity Type.\n\n### Resetting activities that heartbeat {#reset-heartbeats}\n\nActivities that heartbeat will receive a Canceled failure \nthe next time they heartbeat after a reset.\n\nIf, in your Activity, you need to do any cleanup when an Activity is \nreset, handle this error and then re-throw it when you've cleaned up.\n\nIf the `reset_heartbeats` flag is set, the heartbeat details will also be cleared.\n\nSpecify the Activity Type of ID and Workflow IDs:\n\n```\ntemporal activity reset \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --keep-paused\n --reset-heartbeats\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "Activity ID to reset. Either `activity-id` or `activity-type` must be provided, but not both.") - s.Command.Flags().StringVarP(&s.ActivityType, "activity-type", "g", "", "Activity Type to reset. Either `activity-id` or `activity-type` must be provided, but not both.") - s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of the user submitting this request.") - s.Command.Flags().BoolVar(&s.KeepPaused, "keep-paused", false, "If activity was paused - it will stay paused.") - s.Command.Flags().BoolVar(&s.ResetHeartbeats, "reset-heartbeats", false, "Reset the Activity's heartbeat.") + s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "The Activity ID to reset. Either `activity-id` or `activity-type` must be provided, but not both.") + s.Command.Flags().StringVarP(&s.ActivityType, "activity-type", "g", "", "The Activity Type to reset. Either `activity-id` or `activity-type` must be provided, but not both.") + s.Command.Flags().StringVar(&s.Identity, "identity", "", "The identity of the user or client submitting this request.") + s.Command.Flags().BoolVar(&s.KeepPaused, "keep-paused", false, "If the activity was paused, it will stay paused.") + s.Command.Flags().BoolVar(&s.ResetHeartbeats, "reset-heartbeats", false, "Clear the Activity's heartbeat details.") s.WorkflowReferenceOptions.buildFlags(cctx, s.Command.Flags()) s.Command.Run = func(c *cobra.Command, args []string) { if err := s.run(cctx, args); err != nil { @@ -577,14 +577,14 @@ func NewTemporalActivityUnpauseCommand(cctx *CommandContext, parent *TemporalAct s.Command.Use = "unpause [flags]" s.Command.Short = "Unpause an Activity" if hasHighlighting { - s.Command.Long = "Re-schedule a previously-paused Activity for execution.\n\nIf the Activity is not running and is past its retry timeout, it will be\nscheduled immediately. Otherwise, it will be scheduled after its retry\ntimeout expires.\n\nUse \x1b[1m--reset-attempts\x1b[0m to reset the number of previous run attempts to\nzero. For example, if an Activity is near the maximum number of attempts\nN specified in its retry policy, \x1b[1m--reset-attempts\x1b[0m will allow the\nActivity to be retried another N times after unpausing.\n\nUse \x1b[1m--reset-heartbeat\x1b[0m to reset the Activity's heartbeats.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided. If both are provided - Activity\nType will be used, and Activity ID will be ignored.\n\nActivities can be unpaused in bulk via a visibility Query list filter:\n\n\x1b[1mtemporal activity unpause \\\n --query YourQuery \\\n --reason YourReasonForTermination\x1b[0m\n\n\nSpecify the Activity ID or Type and Workflow IDs:\n\n\x1b[1mtemporal activity unpause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --reset-attempts\n --reset-heartbeats\x1b[0m" + s.Command.Long = "Re-schedule a previously-paused Activity for execution.\n\nIf the Activity is not running and is past its retry timeout, it will be\nscheduled immediately. Otherwise, it will be scheduled after its retry\ntimeout expires.\n\nUse \x1b[1m--reset-attempts\x1b[0m to reset the number of previous run attempts to\nzero. For example, if an Activity is near the maximum number of attempts\nN specified in its retry policy, \x1b[1m--reset-attempts\x1b[0m will allow the\nActivity to be retried another N times after unpausing.\n\nUse \x1b[1m--reset-heartbeat\x1b[0m to reset the Activity's heartbeats.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided.\n\nSpecify the Activity ID or Type and Workflow IDs:\n\n\x1b[1mtemporal activity unpause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --reset-attempts\n --reset-heartbeats\x1b[0m\n\nActivities can be unpaused in bulk via a visibility Query list filter. \nFor example, if you want to unpause activities of type Foo that you \npreviously paused, do:\n\n\x1b[1mtemporal activity unpause \\\n --query 'TemporalPauseInfo=\"property:activityType=Foo\"'\x1b[0m" } else { - s.Command.Long = "Re-schedule a previously-paused Activity for execution.\n\nIf the Activity is not running and is past its retry timeout, it will be\nscheduled immediately. Otherwise, it will be scheduled after its retry\ntimeout expires.\n\nUse `--reset-attempts` to reset the number of previous run attempts to\nzero. For example, if an Activity is near the maximum number of attempts\nN specified in its retry policy, `--reset-attempts` will allow the\nActivity to be retried another N times after unpausing.\n\nUse `--reset-heartbeat` to reset the Activity's heartbeats.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided. If both are provided - Activity\nType will be used, and Activity ID will be ignored.\n\nActivities can be unpaused in bulk via a visibility Query list filter:\n\n```\ntemporal activity unpause \\\n --query YourQuery \\\n --reason YourReasonForTermination\n```\n\n\nSpecify the Activity ID or Type and Workflow IDs:\n\n```\ntemporal activity unpause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --reset-attempts\n --reset-heartbeats\n```" + s.Command.Long = "Re-schedule a previously-paused Activity for execution.\n\nIf the Activity is not running and is past its retry timeout, it will be\nscheduled immediately. Otherwise, it will be scheduled after its retry\ntimeout expires.\n\nUse `--reset-attempts` to reset the number of previous run attempts to\nzero. For example, if an Activity is near the maximum number of attempts\nN specified in its retry policy, `--reset-attempts` will allow the\nActivity to be retried another N times after unpausing.\n\nUse `--reset-heartbeat` to reset the Activity's heartbeats.\n\nActivities can be specified by their Activity ID or Activity Type.\nOne of those parameters must be provided.\n\nSpecify the Activity ID or Type and Workflow IDs:\n\n```\ntemporal activity unpause \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId\n --reset-attempts\n --reset-heartbeats\n```\n\nActivities can be unpaused in bulk via a visibility Query list filter. \nFor example, if you want to unpause activities of type Foo that you \npreviously paused, do:\n\n```\ntemporal activity unpause \\\n --query 'TemporalPauseInfo=\"property:activityType=Foo\"'\n```" } s.Command.Args = cobra.NoArgs - s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "Activity ID to unpause. Can only be used without --query or --match-all. Either `activity-id` or `activity-type` must be provided, but not both.") - s.Command.Flags().StringVarP(&s.ActivityType, "activity-type", "g", "", "Activity Type to unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both.") - s.Command.Flags().StringVar(&s.Identity, "identity", "", "Identity of the user submitting this request.") + s.Command.Flags().StringVarP(&s.ActivityId, "activity-id", "a", "", "The Activity ID to unpause. Can only be used without --query or --match-all. Either `activity-id` or `activity-type` must be provided, but not both.") + s.Command.Flags().StringVarP(&s.ActivityType, "activity-type", "g", "", "Activities of this Type will unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both.") + s.Command.Flags().StringVar(&s.Identity, "identity", "", "The identity of the user or client submitting this request.") s.Command.Flags().BoolVar(&s.ResetAttempts, "reset-attempts", false, "Also reset the activity attempts.") s.Command.Flags().BoolVar(&s.ResetHeartbeats, "reset-heartbeats", false, "Reset the Activity's heartbeats. Only works with --reset-attempts.") s.Command.Flags().BoolVar(&s.MatchAll, "match-all", false, "Every paused activity should be unpaused. This flag is ignored if activity-type is provided. Can only be used with --query.") @@ -623,9 +623,9 @@ func NewTemporalActivityUpdateOptionsCommand(cctx *CommandContext, parent *Tempo s.Command.Use = "update-options [flags]" s.Command.Short = "Update Activity options" if hasHighlighting { - s.Command.Long = "Update Activity options. Specify the Activity and Workflow IDs, and\noptions you want to update.\nUpdates are incremental, only changing the specified options.\n\n\x1b[1mtemporal activity update-options \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --task-queue NewTaskQueueName \\\n --schedule-to-close-timeout DURATION \\\n --schedule-to-start-timeout DURATION \\\n --start-to-close-timeout DURATION \\\n --heartbeat-timeout DURATION \\\n --retry-initial-interval DURATION \\\n --retry-maximum-interval DURATION \\\n --retry-backoff-coefficient NewBackoffCoefficient \\\n --retry-maximum-attempts NewMaximumAttempts\x1b[0m" + s.Command.Long = "Updates the options of a running Activity that were passed into it from\n a Workflow. Updates are incremental, only changing the specified \n options.\n\nFor example:\n\n\x1b[1mtemporal activity update-options \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --task-queue NewTaskQueueName \\\n --schedule-to-close-timeout DURATION \\\n --schedule-to-start-timeout DURATION \\\n --start-to-close-timeout DURATION \\\n --heartbeat-timeout DURATION \\\n --retry-initial-interval DURATION \\\n --retry-maximum-interval DURATION \\\n --retry-backoff-coefficient NewBackoffCoefficient \\\n --retry-maximum-attempts NewMaximumAttempts\x1b[0m\n\nYou may follow this command with \x1b[1mtemporal activity reset\x1b[0m, and the new values will apply after the reset." } else { - s.Command.Long = "Update Activity options. Specify the Activity and Workflow IDs, and\noptions you want to update.\nUpdates are incremental, only changing the specified options.\n\n```\ntemporal activity update-options \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --task-queue NewTaskQueueName \\\n --schedule-to-close-timeout DURATION \\\n --schedule-to-start-timeout DURATION \\\n --start-to-close-timeout DURATION \\\n --heartbeat-timeout DURATION \\\n --retry-initial-interval DURATION \\\n --retry-maximum-interval DURATION \\\n --retry-backoff-coefficient NewBackoffCoefficient \\\n --retry-maximum-attempts NewMaximumAttempts\n\n```" + s.Command.Long = "Updates the options of a running Activity that were passed into it from\n a Workflow. Updates are incremental, only changing the specified \n options.\n\nFor example:\n\n```\ntemporal activity update-options \\\n --activity-id YourActivityId \\\n --workflow-id YourWorkflowId \\\n --task-queue NewTaskQueueName \\\n --schedule-to-close-timeout DURATION \\\n --schedule-to-start-timeout DURATION \\\n --start-to-close-timeout DURATION \\\n --heartbeat-timeout DURATION \\\n --retry-initial-interval DURATION \\\n --retry-maximum-interval DURATION \\\n --retry-backoff-coefficient NewBackoffCoefficient \\\n --retry-maximum-attempts NewMaximumAttempts\n```\n\nYou may follow this command with `temporal activity reset`, and the new values will apply after the reset." } s.Command.Args = cobra.NoArgs s.Command.Flags().StringVar(&s.ActivityId, "activity-id", "", "Activity ID. Required.") diff --git a/temporalcli/commandsgen/commands.yml b/temporalcli/commandsgen/commands.yml index 689f807e3..bc667ea7c 100644 --- a/temporalcli/commandsgen/commands.yml +++ b/temporalcli/commandsgen/commands.yml @@ -337,9 +337,11 @@ commands: - name: temporal activity update-options summary: Update Activity options description: | - Update Activity options. Specify the Activity and Workflow IDs, and - options you want to update. - Updates are incremental, only changing the specified options. + Updates the options of a running Activity that were passed into it from + a Workflow. Updates are incremental, only changing the specified + options. + + For example: ``` temporal activity update-options \ @@ -354,8 +356,9 @@ commands: --retry-maximum-interval DURATION \ --retry-backoff-coefficient NewBackoffCoefficient \ --retry-maximum-attempts NewMaximumAttempts - ``` + + You may follow this command with `temporal activity reset`, and the new values will apply after the reset. options: - name: activity-id type: string @@ -427,33 +430,36 @@ commands: If the Activity is not currently running (e.g. because it previously failed), it will not be run again until it is unpaused. - However, if the Activity is currently running, it will run to completion. + However, if the Activity is currently running, it will run until the next + time it fails, completes, or times out, at which point the pause will kick in. + If the Activity is on its last retry attempt and fails, the failure will be returned to the caller, just as if the Activity had not been paused. - Activities can be specified by their Activity ID or Activity Type. - One of those parameters must be provided. If both are provided - Activity - Type will be used, and Activity ID will be ignored. + Activities should be specified either by their Activity ID or Activity Type. - Specify the Activity and Workflow IDs: + For example, specify the Activity and Workflow IDs like this: ``` temporal activity pause \ --activity-id YourActivityId \ --workflow-id YourWorkflowId ``` + + To later unpause the activity, see [unpause](#unpause). You may also want to + [reset](#reset) the activity to unpause it while also starting it from the beginning. options: - name: activity-id short: a type: string - description: Activity ID to pause. Either `activity-id` or `activity-type` must be provided, but not both. + description: The Activity ID to pause. Either `activity-id` or `activity-type` must be provided, but not both. - name: activity-type short: g type: string - description: Either `activity-id` or `activity-type` must be provided, but not both.Activity Type to pause. + description: All activities of the Activity Type will be paused. Either `activity-id` or `activity-type` must be provided, but not both. - name: identity type: string - description: Identity of the user submitting this request. + description: The identity of the user or client submitting this request. option-sets: - workflow reference @@ -474,17 +480,7 @@ commands: Use `--reset-heartbeat` to reset the Activity's heartbeats. Activities can be specified by their Activity ID or Activity Type. - One of those parameters must be provided. If both are provided - Activity - Type will be used, and Activity ID will be ignored. - - Activities can be unpaused in bulk via a visibility Query list filter: - - ``` - temporal activity unpause \ - --query YourQuery \ - --reason YourReasonForTermination - ``` - + One of those parameters must be provided. Specify the Activity ID or Type and Workflow IDs: @@ -495,20 +491,29 @@ commands: --reset-attempts --reset-heartbeats ``` + + Activities can be unpaused in bulk via a visibility Query list filter. + For example, if you want to unpause activities of type Foo that you + previously paused, do: + + ``` + temporal activity unpause \ + --query 'TemporalPauseInfo="property:activityType=Foo"' + ``` options: - name: activity-id short: a type: string description: | - Activity ID to unpause. Can only be used without --query or --match-all. Either `activity-id` or `activity-type` must be provided, but not both. + The Activity ID to unpause. Can only be used without --query or --match-all. Either `activity-id` or `activity-type` must be provided, but not both. - name: activity-type short: g type: string description: | - Activity Type to unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both. + Activities of this Type will unpause. Can only be used without --match-all. Either `activity-id` or `activity-type` must be provided, but not both. - name: identity type: string - description: Identity of the user submitting this request. + description: The identity of the user or client submitting this request. - name: reset-attempts type: bool description: Also reset the activity attempts. @@ -533,20 +538,34 @@ commands: - name: temporal activity reset summary: Reset an Activity description: | - Resetting an activity resets both the number of attempts and the activity - timeout. + Resetting an activity restarts the activity as if it were first being + scheduled. That is, it will reset both the number of attempts and the + activity timeout, as well as, optionally, the + [heartbeat details](#reset-heartbeats). - If activity is paused and 'keep_paused' flag is not provided - it will be - unpaused. - If activity is paused and 'keep_paused' flag is provided - it will stay - paused. - If activity is waiting for the retry, is will be rescheduled immediately. - If the 'reset_heartbeats' flag is set, the activity heartbeat timer and - heartbeats will be reset. + If the activity may be executing (i.e. it has not yet timed out), the + reset will take effect the next time it fails, heartbeats, or times out. + If is waiting for a retry (i.e. has failed or timed out), the reset + will apply immediately. + + If the activity is already paused, it will be unpaused by default. + You can specify `keep_paused` to prevent this. + + If the activity is paused and the `keep_paused` flag is not provided, + it will be unpaused. If the activity is paused and `keep_paused` flag + is provided - it will stay paused. Activities can be specified by their Activity ID or Activity Type. - One of those parameters must be provided. If both are provided - Activity - Type will be used, and Activity ID will be ignored. + + ### Resetting activities that heartbeat {#reset-heartbeats} + + Activities that heartbeat will receive a [Canceled failure](/references/failures#cancelled-failure) + the next time they heartbeat after a reset. + + If, in your Activity, you need to do any cleanup when an Activity is + reset, handle this error and then re-throw it when you've cleaned up. + + If the `reset_heartbeats` flag is set, the heartbeat details will also be cleared. Specify the Activity Type of ID and Workflow IDs: @@ -561,20 +580,20 @@ commands: - name: activity-id short: a type: string - description: Activity ID to reset. Either `activity-id` or `activity-type` must be provided, but not both. + description: The Activity ID to reset. Either `activity-id` or `activity-type` must be provided, but not both. - name: activity-type short: g type: string - description: Activity Type to reset. Either `activity-id` or `activity-type` must be provided, but not both. + description: The Activity Type to reset. Either `activity-id` or `activity-type` must be provided, but not both. - name: identity type: string - description: Identity of the user submitting this request. + description: The identity of the user or client submitting this request. - name: keep-paused type: bool - description: If activity was paused - it will stay paused. + description: If the activity was paused, it will stay paused. - name: reset-heartbeats type: bool - description: Reset the Activity's heartbeat. + description: Clear the Activity's heartbeat details. option-sets: - workflow reference