Skip to content

Update Java versioning docs for automatic TemporalChangeVersion support #4236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bchav wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update Java versioning docs for automatic TemporalChangeVersion support #4236

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 33 additions & 27 deletions docs/develop/java/versioning.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 `"<Change ID>-<Version>"` 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<List<String>> TEMPORAL_CHANGE_VERSION = SearchAttributeKey.forKeywordList("TemporalChangeVersion");
```
import io.temporal.common.SearchAttributeKey;

#### Set the Search Attribute using `upsert`
public static final SearchAttributeKey<List<String>> 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<String> list = new ArrayList<String>();
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.
Expand Down