From 4dcedb627633d333aec9f58c085a89b583297377 Mon Sep 17 00:00:00 2001 From: Brandon Chavis Date: Tue, 24 Feb 2026 16:38:23 -0500 Subject: [PATCH] Update Java versioning docs to reflect automatic TemporalChangeVersion support The Java SDK v1.30.0 added setEnableUpsertVersionSearchAttributes in WorkflowImplementationOptions, which automatically upserts the TemporalChangeVersion search attribute on getVersion calls. The docs previously stated the Java SDK does not support this. Updated to document the automatic option as the recommended approach while preserving the manual upsert instructions as a fallback. Closes temporalio/sdk-java#587 Co-Authored-By: Claude Opus 4.6 --- docs/develop/java/versioning.mdx | 60 ++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/docs/develop/java/versioning.mdx b/docs/develop/java/versioning.mdx index 721701e0cd..054fabc212 100644 --- a/docs/develop/java/versioning.mdx +++ b/docs/develop/java/versioning.mdx @@ -127,61 +127,67 @@ public void processFile(Arguments args) { } ``` -### Adding Support for Versioned Workflow Visibility in the Event History +### Adding support for versioned Workflow visibility in the Event History -In other Temporal SDKs, when you invoke `getVersion` or the patching API, the SDK records an -`UpsertWorkflowSearchAttribute` Event in the history. -This adds support for a custom query parameter in the web UI named `TemporalChangeVersion` that allows you to filter Workflows based on their version. -The Java SDK does not automatically add this attribute, so you'll likely want to do it manually. +When you invoke `getVersion`, the SDK can record an `UpsertWorkflowSearchAttribute` Event in the history. +This adds a [Search Attribute](/search-attribute#default-search-attribute) named `TemporalChangeVersion` that allows you to filter Workflows based on their version. -Within your Workflow Implementation code you'll need to perform the following steps: +#### Enable automatic upsert (Java SDK v1.30.0+) -#### Import the `SearchAttributes` class +Starting with Java SDK v1.30.0, you can enable automatic `TemporalChangeVersion` upserts by setting `enableUpsertVersionSearchAttributes` in `WorkflowImplementationOptions`: ```java -import io.temporal.common.SearchAttributeKey; +WorkflowImplementationOptions options = WorkflowImplementationOptions.newBuilder() + .setEnableUpsertVersionSearchAttributes(true) + .build(); + +worker.registerWorkflowImplementationTypes(options, YourWorkflowImpl.class); ``` -#### Define the `SearchAttributesKey` object +When enabled, each call to `Workflow.getVersion` automatically upserts the `TemporalChangeVersion` Search Attribute with a keyword list of `"-"` entries. + +:::note + +This option is backwards compatible and safe to enable on running Workflows. +However, once enabled, you cannot roll back to a version of the SDK that does not support this option. + +::: + +#### Upsert manually -This object will be used as the key within the search attributes. This is done as an instance variable. +If you are using a version of the Java SDK earlier than v1.30.0, or prefer to control the upsert yourself, you can set the attribute manually. ```java -public static final SearchAttributeKey> TEMPORAL_CHANGE_VERSION = SearchAttributeKey.forKeywordList("TemporalChangeVersion"); -``` +import io.temporal.common.SearchAttributeKey; -#### Set the Search Attribute using `upsert` +public static final SearchAttributeKey> TEMPORAL_CHANGE_VERSION = + SearchAttributeKey.forKeywordList("TemporalChangeVersion"); +``` -You should set this attribute when you make the call to `getVersion`. +Set this attribute when you call `getVersion`: ```java int version = Workflow.getVersion("MovedThankYouAfterLoop", Workflow.DEFAULT_VERSION, 1); if (version != Workflow.DEFAULT_VERSION) { - Workflow.upsertTypedSearchAttributes(Constants.TEMPORAL_CHANGE_VERSION - .valueSet(Arrays.asList(("MovedThankYouAfterLoop-" + version)))); + Workflow.upsertTypedSearchAttributes(TEMPORAL_CHANGE_VERSION + .valueSet(Arrays.asList("MovedThankYouAfterLoop-" + version))); } ``` -You should only set the attribute on new versions. - -#### Setting Attributes for Multiple `getVersion` Calls - -The code in the previous section works well for code that only has one call to `getVersion()`. -However, you may encounter situations where you have to have multiple calls to `getVersion()` to handle multiple independent changes to your Workflow. -In this case, you should create a list of all the version changes and then set the attribute value: +For multiple `getVersion` calls, collect all version changes and set the attribute once: ```java List list = new ArrayList(); int versionOne = Workflow.getVersion("versionOne", Workflow.DEFAULT_VERSION, 1); int versionTwo = Workflow.getVersion("versionTwo", Workflow.DEFAULT_VERSION, 1); -if ( versionOne != Workflow.DEFAULT_VERSION ) { - list.append("versionOne-" + versionOne); +if (versionOne != Workflow.DEFAULT_VERSION) { + list.add("versionOne-" + versionOne); } if (versionTwo != Workflow.DEFAULT_VERSION) { - list.append("versionTwo-" + versionTwo); + list.add("versionTwo-" + versionTwo); } -Workflow.upsertTypedSearchAttributes(Constants.TEMPORAL_CHANGE_VERSION.valueSet(list)); +Workflow.upsertTypedSearchAttributes(TEMPORAL_CHANGE_VERSION.valueSet(list)); ``` Patching allows you to make changes to currently running Workflows.