Skip to content

Add experimental support for Event Groups (direct assignment) - #3197

Merged
mjameswh merged 20 commits into
mainfrom
event-groups-direct-only
Nov 18, 2026
Merged

mjameswh merged 20 commits into
mainfrom
event-groups-direct-only

Conversation

@mjameswh

@mjameswh mjameswh commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What was changed

Add experimental support for Event Groups. Only direct assignment of explicit Event Groups is supported in this PR.

Event Groups is a new form of Workflow-level metadata that allows for improved visibility into a Workflow execution's history by grouping logically related Events together based on user-defined or system-inferred criteria.

  • Explicit groups: Workflow.newEventGroup(id).
  • An optional label can be provided with Workflow.newEventGroup(id, EventGroupOptions.newBuilder().setLabel("label").build()); the label is codec-encoded payload.
  • Attach a group per call (addEventGroups on various command options).

Implicit Event Groups and Scope-based propagation is not covered by this PR.

Review notes

  • This PR is quite large. The PR has been staged as a sequence of reasonably scoped commits that should hopefully make review easier.
  • Implicit Event Groups and scope-based propagation in Java brings a few particularities, friction points and complexities, that would have unreasonably conflated this PR. They have therefore been scoped out of this PR, and moved to their own, distinct PR.

The test server now stores the event group markers and user metadata of each command on the event that command produces, instead of only on the start events. Actions that act on an existing entity receive the command as a CommandRequest, so they no longer read those fields from the entity's data.
@mjameswh
mjameswh requested a review from a team as a code owner November 10, 2026 10:15
addEventGroups now accepts a list as well as varargs. The signal and cancel options on ExternalWorkflowStub and ChildWorkflowStub move to signalWithOptions and cancelWithOptions, so a null argument keeps its existing meaning.
@Quinn-With-Two-Ns

Copy link
Copy Markdown
Contributor

One other thing I noticed is a static event group looks possible to create for example through a static option:

static final EventGroup GROUP = Workflow.newEventGroup(
    "orders", EventGroupOptions.newBuilder().setLabel("Orders").build());
static final TimerOptions TIMER_OPTIONS =
    TimerOptions.newBuilder().addEventGroups(GROUP).build();

@WorkflowMethod
public void run() {
  Workflow.sleep(Duration.ofSeconds(1), TIMER_OPTIONS);
}

Each execution of run() uses the same group, but the groups encoding could be specific to the workflow right?.

@mjameswh

Copy link
Copy Markdown
Contributor Author

Each execution of run() uses the same group, but the groups encoding could be specific to the workflow right?.

Right. I had previously considered and dismissed the idea of sharing Event Groups as a blatant misuse of the Workflow API. I mean, you wouldn't expect that a Cancellation Scope or Promise that you created through Workflow.newXxx() would be safe to share across workflow executions, so why would it be different for Workflow.newEventGroup()?

But I have to admit that using this indirectly like you did, i.e. as part of some XxxOptions objects which are themselves safe to share, blurs the line and gives legitimacy to that pattern. It's very likely that some users will try exactly that, and there's no good reason to deny that.

So I simply removed marker caching. Its benefit was marginal anyway.

A group may be declared statically and shared by workflows whose data
converters differ, for instance through a context-aware payload codec,
so a cached marker could carry a label encoded for another workflow.
@mjameswh
mjameswh force-pushed the event-groups-direct-only branch from fdf5d9d to c64dd95 Compare November 12, 2026 12:51
…ent-groups-direct-only

# Conflicts:
#	temporal-sdk/src/main/java/io/temporal/internal/statemachines/WorkflowStateMachines.java
#	temporal-sdk/src/test/java/io/temporal/internal/statemachines/MutableSideEffectStateMachineTest.java
# Conflicts:
#	temporal-sdk/src/main/java/io/temporal/internal/statemachines/ExecuteLocalActivityParameters.java
#	temporal-sdk/src/main/java/io/temporal/internal/sync/SyncWorkflowContext.java
#	temporal-sdk/src/test/java/io/temporal/internal/replay/OutdatedDirectQueryReplayWorkflowRunTaskHandlerTest.java
#	temporal-sdk/src/test/java/io/temporal/internal/replay/ReplayWorkflowRunTaskHandlerTaskHandlerTests.java
#	temporal-sdk/src/test/java/io/temporal/internal/statemachines/LocalActivityStateMachineTest.java
@mjameswh
mjameswh merged commit 0e2f3e1 into main Nov 18, 2026
35 of 37 checks passed
@mjameswh
mjameswh deleted the event-groups-direct-only branch November 18, 2026 13:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants