Before upgrading your Temporal Cluster to v1.28.0, you must upgrade your core schemas to the following:
Please see our upgrade documentation for the necessary steps to upgrade your schemas.
Deprecating old Versioning APIs: The following APIs related to previous versions of Worker Versioning are deprecated.
The following APIs related to the December 2024 pre-release of Worker Versioning have been deprecated and are now no longer supported:
The following APIs are now deprecated and will be removed once the latest APIs reach to General Availability in the coming months:
Update-With-Start sends a Workflow Update that checks whether an already-running Workflow with that ID exists. If it does, the Update is processed. If not, it starts a new Workflow Execution with the supplied ID. When starting a new Workflow, it immediately processes the Update.
Update-With-Start is great for latency-sensitive use cases.
Now you can have multiple callers starting operations backed by a single workflow. When the handler tries to start a workflow that is already running, with the “use existing” conflict policy, the server will attach the caller’s callback to the running workflow. When the workflow completes, the server will call all attached callbacks to notify the callers with the workflow result.
Here’s an example using Go SDK (available in v1.34.0+):
import (
"context"
"github.com/nexus-rpc/sdk-go/nexus"
enumspb "go.temporal.io/api/enums/v1"
"go.temporal.io/sdk/client"
"go.temporal.io/sdk/temporalnexus"
)
sampleOperation := temporalnexus.NewWorkflowRunOperation(
"sample-operation",
SampleWorkflow,
func (
ctx context.Context,
input SampleWorkflowInput,
options nexus.StartOperationOptions,
) (client.StartWorkflowOptions, error) {
return client.StartWorkflowOptions{
// Workflow ID is used as idempotency key.
ID: "sample-workflow-id",
// If a workflow with same ID is already running, then it will attach the callback to the existing running workflow.
// Otherwise, it will start a new workflow.
WorkflowIDConflictPolicy: enumspb.WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING,
}, nil
},
)
The handler workflow will return a RequestIdReferenceLink to the caller. This is an indirect link to the history event that attached the callback in the handler workflow. Links can provide information about the handler workflow to the caller. In order to get the exact event history, there is now the RequestIdInfos map in the WorkflowExtendedInfo field of a DescribeWorkflowExecutionResponse. To enable RequestIdReferenceLink, you have to set the dynamic config history.enableRequestIdRefLinks to true (this might become enabled by default in a future release).
Nexus links were previously stored in the history event not directly associated with the callback that it came together. Now, the server is storing the Nexus links together with the callback. With this direct association, you can easily find out the caller that triggered the Nexus workflow from the callback through these links for example. This feature requires the latest version of Go SDK (v1.35.0+) and Java SDK (v1.30.0+).
The server now supports Nexus operation cancellation types. These are specified when starting an operation and indicate what should happen to Nexus operations when the parent context that started them is cancelled. To use them, you must be using an SDK version that supports them. Available cancellation types are:
Abandon - Do not request cancellation of the operationTryCancel - Request cancellation of the operation and immediately report cancellation to callersWaitRequested - Request cancellation and wait until the cancellation request has been received by the operation handlerWaitCompleted - Request cancellation and wait for the operation to complete. The operation may or may not complete as cancelled. Default and behavior for server versions <1.28For the WaitRequested type to work, you must set the dynamic config component.nexusoperations.recordCancelRequestCompletionEvents to true (default false ).
The following Worker Versioning APIs graduated into Public Preview stage. Production usage is encouraged but note that limited changes might be made to the APIs before General Availability in the coming months.
Using Worker Versioning: Find instructions in https://docs.temporal.io/worker-versioning.
Operator notes:
frontend.workerVersioningWorkflowAPIs (default: true)system.enableDeploymentVersions (default: true)matching.maxDeployments controls the maximum number of worker deployments that the server allows to be registered in a single namespace (default: 100, safe to increase to much higher values)matching.maxVersionsInDeployment controls the maximum number of versions that the server allows to be registered in a single worker deployments (default: 100, unsafe to increase beyond a few 100s)matching.maxTaskQueuesInDeploymentVersion controls the maximum number of task queues that the server allows to be registered in a single worker deployment version (default: 100, unsafe to increase beyond a few 100s)matching.wv.VersionDrainageStatusVisibilityGracePeriod systems waits for this amount of time before checking the drainage status of a version that just entered in DRAINING state (default: 3 minutes, setting a very low value might cause the status to become DRAINED incorrectly)matching.wv.VersionDrainageStatusRefreshInterval interval used for checking drainage status (default: 3 minutes, lowering the value will increase load on the Visibility database)Please see deprecation warnings regarding earlier versions of Temporal versioning APIs.
If you used Worker Versioning in v1.27.x, you must delete all Worker Deployments (via DeleteWorkerDeployment) before upgrading to v1.28.0, then recreate them after. This is due to breaking changes between v1.27.2 and v1.28.0.
If you already upgraded or need help, ask in #safe-deploys on Community Slack.
Simple priority allows you to control the execution order of workflows, activities, and child workflows based on assigned priority values within a single task queue. You can select a priority level in the integer range [1,5]. A lower value implies higher priority.
Priority can be attached to workflows and activities using the latest versions of most SDKs. In order for priority to take effect on the server, you need to switch to the new implementation of the matching service: set the dynamic config matching.useNewMatcher to true either on specific task queues, namespaces, or globally. After the new matcher has been turned on for a task queue, turning it off will cause tasks with non-default priority to be temporarily lost until it’s turned on again.
When the setting is changed, the implementation will be switched immediately, which may cause a momentary disruption in task dispatch.
Besides enabling priority, the new matcher will have a different profile of persistence operations, and slightly different behavior with task forwarding and some other edge cases. If you see performance regressions or unexpected behavior with the new matcher, please let us know.
See more usage details here: Temporal - Task Queue Priority Guide (Pre-Release)
PAUSED and PAUSE_REQUESTED to activity state. This allows to distinguish between the situation when pause signal is received, but activity is still running on the worker.ActivityPause/ActivityReset flag in heartbeat response. This notifies the workers about activity state.ResetActivity and UpdateActivityOptions commands.The Temporal server now supports resetting workflows even when the resulting new run has pending child workflows. Previously, such reset attempts were rejected if the new run appeared to have one or more pending child workflows.
With this update:
This change improves flexibility and reliability in handling resets for workflows with children in various states.
Behavior Matrix
| Reset Point | Child Running | Child Completed/Failed/Terminated |
|---|---|---|
| Before child started | New run does not reference the child | No reference to child |
| In between child start & completed. | Child is reconnected to new parent run. | Completed/Failed/Terminated event immediately replayed in new parent run |
| After child completed | N/A | All child events are included in the new run. |
Description: A new dynamic configuration history.sendRawHistoryBetweenInternalServices has been introduced. When enabled, the history service sends raw history event blobs to the frontend and matching services during GetWorkflowExecutionHistory and RecordWorkflowTaskStarted API calls. This reduces CPU usage on the history service by eliminating event decoding. The frontend service handles decoding before responding to clients, ensuring no impact on SDKs or other clients without adding extra CPU load to the frontend.
This configuration should only be enabled after all services have been upgraded to version v1.28, and must be disabled before downgrading to any version earlier than v1.28.
executions table for Cassandra-backed clusters contains additional columns (chasm_node_map).chasm_node_maps , has been added to SQL-backed clusters.ListSearchAttributesResponse.StorageSchema is no longer being populated.DescribeTaskQueue contains a new Stats field that contains the task queue’s statsstatsd.framework: opentelemetry to try it out and report any issues.Temporal Docs Server Docker Compose Helm Chart
1.28.0)Server Server With Auto Setup (what is Auto-Setup?) Admin-Tools
Full Changelog: https://github.com/temporalio/temporal/compare/v1.27.2...v1.28.0
Fetched April 11, 2026