Schema changes

Before upgrading your Temporal Cluster to v1.28.0, you must upgrade your core schemas to the following:

• MySQL schema v1.17
• PostgreSQL schema v1.17
• Cassandra schema v1.12

Please see our upgrade documentation for the necessary steps to upgrade your schemas.

Deprecation Announcements

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:

• DescribeDeployment
• ListDeployments
• GetDeploymentReachability
• GetCurrentDeployment
• SetCurrentDeployment

The following APIs are now deprecated and will be removed once the latest APIs reach to General Availability in the coming months:

• UpdateWorkerVersioningRules
• GetWorkerVersioningRules
• UpdateWorkerBuildIdCompatibility
• GetWorkerBuildIdCompatibility
• GetWorkerTaskReachability

Release Highlights

Update-With-Start GA

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.

Nexus - Back Multiple Operations by Single Workflow

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 - Callback ↔ Link Association

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+).

Nexus - Cancellation Types

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 operation
• TryCancel - Request cancellation of the operation and immediately report cancellation to callers
• WaitRequested - Request cancellation and wait until the cancellation request has been received by the operation handler
• WaitCompleted - 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.28

For the WaitRequested type to work, you must set the dynamic config component.nexusoperations.recordCancelRequestCompletionEvents to true (default false ).

Nexus - Miscellaneous

• Nexus callback request processing logic will now attempt to deserialize failure information from the body of failed callback HTTP requests. This means that Nexus operation handlers should now see more informative messages about why their callback failed to be delivered to callers.
• Links added by Nexus operations should now be appropriately propagated across continue-as-new, workflow reset, and workflow retries.

Versioning / Safe-Deploy Public Preview

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.

• ListWorkerDeployments
• DescribeWorkerDeployment
• DescribeWorkerDeploymentVersion
• SetWorkerDeploymentCurrentVersion
• SetWorkerDeploymentRampingVersion
• UpdateWorkerVersionMetadata
• DeleteWorkerDeployment
• DeleteWorkerDeploymentVersion

Using Worker Versioning: Find instructions in https://docs.temporal.io/worker-versioning.

Operator notes:

• The following configs need to be enabled:
  • frontend.workerVersioningWorkflowAPIs (default: true)
  • system.enableDeploymentVersions (default: true)
• Knobs:
  • 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.

Simple priority for task queues - pre-release

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)

Operator commands

• Improvements to the activity in DescribeWorkflow:
  • Add activity options to the pending activity info
    • Task Queue name
    • All timeouts
    • Retry Policy
  • Add PauseInfo to the pending activity info
    • Timestamp
    • Identity
    • Pause reason
  • Add 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.
• Send ActivityPause/ActivityReset flag in heartbeat response. This notifies the workers about activity state.
• Add the ability to restore activity options to its original state for ResetActivity and UpdateActivityOptions commands.
• Add a flag to CLI to restore activity options for the activity reset and update-options CLI commands.

Reset workflow with pending child

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:

• The server now accepts resets in these scenarios.
• If a child workflow is still running at the time of reset, it will be automatically reconnected to the new run.
• If a child workflow has already completed, its completion event is preserved and replayed as part of the new run.

This change improves flexibility and reliability in handling resets for workflows with children in various states.

Behavior Matrix

Send raw history event from history service to frontend service

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.

Miscellaneous / Bug Fixes

• Temporal’s schema has been updated.
  • The executions table for Cassandra-backed clusters contains additional columns (chasm_node_map).
  • A new table, chasm_node_maps , has been added to SQL-backed clusters.
• Proto durations will now automatically be capped to 100 years. Previously this cap was removed and now has been returned to 100 years. This change should have no effect on processing.
• When listing the custom search attributes, the field ListSearchAttributesResponse.StorageSchema is no longer being populated.
• Update-with-Start will return the result for the requested update ID if the targeted workflow is closed and contains the update outcome
• Update-With-Start will attach to any in-flight Update before applying the Start operation
• DescribeTaskQueue contains a new Stats field that contains the task queue’s stats
• We are in the process of deprecating Tally library. As part of this we have implemented statsd metric collection via OTel. If you’re using statsd please add the config statsd.framework: opentelemetry to try it out and report any issues.

Helpful links to get you started with Temporal

Temporal Docs
Server
Docker Compose
Helm Chart

Docker images for this release (use the tag 1.28.0)

Server
Server With Auto Setup (what is Auto-Setup?)
Admin-Tools

Full Changelog: v1.27.2...v1.28.0