[docs] Document Action trigger conditions

[rosemarYuan]

Linked issue: #754

Purpose of change

This is the third PR in the three-PR stack tracked by #754:

1. [api][java][python] Introduce EventType constants and unify Action trigger entry #756 — API changes (under review)
2. [runtime][java][python] Add CEL Action condition filtering #821 — CEL runtime (Java and Python)
3. This PR —Documentation

PR #821 introduced Action trigger conditions, but the existing documentation still described Actions mainly as event-type listeners. This PR documents the user-visible trigger-condition contract consistently across Java, Python, and YAML.

A trigger condition can be either an exact event type or a condition expression, which uses Common Expression Language (CEL). This change:

• explains OR semantics across trigger-condition entries, fan-out across matching Actions, exact event-type precedence, and per-Action short-circuit behavior;
• documents the event data available to condition expressions, including nested values, name collisions, missing values, numeric conversion, and supported macros;
• explains YAML validation and quoting rules for condition expressions, custom event types, and event aliases;
• clarifies that event aliases replace only complete event-type entries;
• provides decorated, annotated, and programmatic Action examples, including a complete Java registration example;
• documents action.trigger-condition.evaluate-failure-strategy; and

Tests

This is a documentation-only change. No Tests.

API

No public API or runtime behavior is changed. This PR documents the Action trigger-condition APIs and configuration introduced by #821.

Documentation

• doc-needed
• doc-not-needed
• doc-included

[weiqingy]

Thanks for taking this on. A few questions inline.

[weiqingy]

"Not supported" sits in the same register as line 398's "remains absent", but this one is a hard failure: ConditionExpressionCompiler.classifyIdent throws from the ActionMatcher constructor, so the job fails at operator initialization. The fixture dynamic_whole_attributes_index captures the split, plan_validation: pass with runtime_compilation: fail.

Would naming the outcome help a reader tell the two apart? Maybe something like "rejected when the runtime compiles the condition, so the job fails to start", if that reads right to you.

[weiqingy]

"is not" reads as rejected, though nothing rejects bare status. It clears plan validation and the type check (ConditionExpressionCompiler.java:124 declares non-framework idents SimpleType.DYN), then throws unbound at evaluation. Under the default WARN_AND_SKIP that is logged and treated as false, so the action just never fires.

That default lives only in the configuration.md row this PR adds, and neither page links to it. Would a sentence on the failure semantics plus a link fit here, the way monitoring.md:335 points at event-log.level? Same two gaps on workflow_agent.md, if so.

[weiqingy]

This sentence now frames the alias table below as the menu of legal trigger_conditions values, and that table offers output. An action triggered on output never runs: ActionExecutionOperator.java:247 sends OutputEvents downstream in the if branch, so the getActionsTriggeredBy call in the else at :269 is never reached. Nothing fails and nothing logs.

You document exactly this at workflow_agent.md:472-474. Should the caveat follow the alias table here, or hang off the pointer at 350-351?

[wenjin272]

Thanks for the detailed comments, @weiqingy. I refactored the two pages to keep the trigger-condition contract in workflow_agent.md and only YAML-specific guidance in yaml.md. The three issues you raised are now covered.

Could you please take another look and let me know if you have any further suggestions?

[weiqingy]

Thanks for addressing the comments. All three are closed, and moving the trigger-condition rules onto one page with yaml.md pointing at it reads much better.

One thing inline that doesn't need to hold this up, otherwise LGTM.

[weiqingy]

In Java and Python you pass the condition as a string, so an event type that needs quotes ends up with two layers: @Action("'order:created'"). This paragraph shows 'order:created' but never says the inner quotes belong in the string, and the example that made that clear came out in this commit. Drop a layer and @Action("order:created") looks right, but it gets read as an expression rather than an event type (TriggerCondition.java:32 leaves : out of the bare-name pattern), so the plan fails to build. The YAML page still says it outright at yaml.md:292. Since this page owns the rule now, would one line here help? Maybe: "In Java and Python the quotes are part of the condition string, for example @Action("'order:created'")."