`task_api` ECA model ⭐¶

Source: web/modules/contrib/fedms_eca/config/optional/eca.eca.task_api.yml

Purpose: The heart of the FedMS workflow. This model walks the fedms_task_pattern registry and spawns fedms_task instances when group or membership lifecycle events fire — driven by the field_flag_start_processed / field_flag_end_processed flags on event and session groups, plus user-add events on every group level.

This is the model you will touch most often when adjusting FedMS workflow behavior. Read carefully before editing.

Events the model listens to¶

The model has a large set of events. The most important:

Event plugin	Label
`content_entity:insert` (group_relationship event-group_membership)	Add user to an event
`content_entity:insert` (group_relationship session-group_membership)	Add user to a session
`content_entity:insert` (group_relationship org-group_membership)	Add user to an organization
`eca_base:eca_cron`	Cron — re-evaluate lifecycle flags

And a large number of custom condition events:

Plugin	Used for
`fedms_task_pattern_condition`	Is group an event? Is group a session? Check event type. Check session type. Check user role. Check org/event/session group role.
`fedms_task_pattern_condition_arguments`	Event type arguments. Session type arguments. Check role arguments. Check org/event/session group role arguments.

The custom plugins live in fedms_task/src/Plugin/ECA/Event/ and are referenced from the model's events: section.

How a task is spawned (mental model)¶

┌─ Trigger ───────────────────────────────────────────────────┐
│ Either: a group_relationship insert (user → group)          │
│ Or:     a group field_flag_*_processed flip (lifecycle)     │
└────────────────────┬────────────────────────────────────────┘
                     ▼
   Walk all enabled fedms_task_pattern entities
                     ▼
   For each pattern, evaluate its conditions:
     - Is the group of the right bundle?
     - Does the group's bundle (event_type / session_type) match?
     - Does the user's role match?
     - Custom rule + conditionArguments
                     ▼
   Compute timestamps via TaskPattern::getTimestamp():
     - actionableRelation:    task_create | session_start | session_end
     - dueRelation:           same set
     - actionableRelationDate / dueRelationDate as DateTime modifier
                     ▼
   For each entity that references the pattern,
   create a fedms_task with:
     label    = pattern.taskLabel (token-replaced)
     milestone = pattern.milestoneEntity()
     pattern  = pattern
     assignee = the affected user (or a default)
     group    = the affected group
     polymorphic target = the referencing entity
                     ▼
   Duplicate check: if an open task with the same
   (assignee, group, pattern, target) exists, skip.
                     ▼
   For each successor in pattern.successors[],
   enqueue a follow-up evaluation

Entities & contexts touched¶

group (bundles org, event, session)
group_relationship (membership additions trigger the _insert events)
fedms_task_pattern (config — read to decide what to spawn)
fedms_task (content — created)
taxonomy_term (fedms_task_milestone) — referenced by spawned tasks

Custom condition plugins¶

The conditions used by task_api are all event plugins under fedms_task/src/Plugin/ECA/Event/. They dispatch a Symfony event that the corresponding action plugin (CreateTaskFromPattern) listens to and uses to short-circuit pattern evaluation.

Plugin id (event-id)	What it checks
`fedms_task_pattern_is_event`	Is the affected group an event?
`fedms_task_pattern_is_session`	Is the affected group a session?
`fedms_task_pattern_check_event_type`	Does the event's bundle match the argument?
`fedms_task_pattern_check_session_type`	Does the session's bundle match the argument?
`fedms_task_pattern_check_user_role`	Does the user have the given site role?
`fedms_task_pattern_check_user_org_group_role`	Does the user have a given role in the parent org?
`fedms_task_pattern_check_user_event_group_role`	Same for the parent event.
`fedms_task_pattern_check_user_session_group_role`	Same for sessions.

Each _condition event has a matching _condition_arguments event that provides the arguments from the pattern's conditionArguments field.

How lifecycle flags drive bulk processing¶

Two fields on the event and session group entities drive lifecycle processing:

field_flag_start_processed — FALSE until the start window has passed and the start tasks have spawned. Set to TRUE once processed.
field_flag_end_processed — same for the end of the window.

The view views.view.groups_unprocessed selects all events and sessions whose flags are still unprocessed and whose date window has passed. Cron walks this view and triggers the relevant branches of task_api.

Don't flip these flags manually unless you fully understand the side-effects — flipping a flag back to FALSE will cause tasks to spawn again.

Editing notes / gotchas¶

Successors form chains, not graphs. Avoid creating cycles in fedms_task_pattern.successors[]. There is no cycle-breaker.
Milestones are referenced by UUID, not by ID — see TaskPattern::milestoneEntity(). Don't refactor that to numeric IDs without updating every pattern's milestone: value.
Custom condition plugins are PHP, not ECA-only. If you change their signatures or behavior, run the PHP tests:

l3d ahoy test phpstanmodule fedms_task
l3d ahoy test phpunitmodule fedms_task

Org-level patterns use task_create timestamps only. See TaskPattern::getTimestamp() — it short-circuits to "now" for bundle === 'org' regardless of the pattern's actionableRelation. This is deliberate.
The model has many branches. Use the modeler's visual view to understand it; the raw YAML has ~2,400 lines and is not human-friendly.
Bulk imports can produce lots of tasks. Be careful when adding a pattern with broad conditions on a high-membership event.

Active issues against task_api and the task engine:

fedms/components/tasks#5 — Variations of task completion.
fedms/components/tasks#11 — Task rule when members are removed.
fedms/components/tasks#15 — Task rule when other tasks are completed (successors).
fedms/components/tasks#20 — Prevent ambiguous task/webform relationship.
fedms/components/tasks#22 — "One of" content groups in task patterns.
fedms/components/tasks#24 — Dynamic due dates.
fedms/components/tasks#26 — Successor tasks for embedded objects.

task_api ECA model ⭐¶