Work items — the inbox
since 4.0Some things an application cannot settle on its own. A cost object has no tariff, a project heads for a loss, an approval waits for a line manager who never opens the expense app. Work items are where these land: one inbox for what needs a person's attention, addressed to a role, read by whoever holds it.
In one sentence. A module declares rules that compute what does not fix itself; the command
ui5:work-itemsreconciles them with the inbox — new findings added, vanished ones resolved, standing ones kept —, and each person sees the items addressed to them or to a role they hold.
What belongs in the inbox — and what does not
A work item exists for one of two reasons:
- Something lies outside the regular course — it does not fix itself: a missing tariff, an imminent loss, a failed run, a gap in the set-up.
- A process needs a person who does not already work in it — a hand-over across a boundary: an approval by a line manager, an objected draft going back to the person who entered it.
Not a work item: what its handler has in front of them anyway. The routine queue of a process — drafts waiting to be booked, a bank statement waiting to be settled, this month's VAT return — stays in the app that owns it. Copying it into the inbox would give you two truths to keep in step and an inbox full of the everyday. Deadlines belong in a calendar; only a missed one is an exception.
So the inbox stays short, and what it shows is worth looking at.
Two kinds, one row
| Finding | Task | |
|---|---|---|
| arises | a rule finds it at a run | a process delivers it |
| ends | its rule no longer finds it (resolved), or a person dismisses it with a reason | a person completes it, often with an outcome; or the process withdraws it |
| in 4.0 | built | provided — the columns and states exist; the API comes with its first consumer |
Both live in sdk_work_items, unique over their source (the rule's code) and their subject (what the item is about, unique within the source).
Writing a rule
A rule implements WorkItemRuleInterface: a unique code and the findings of the moment. Compute from the state as it is now — a rule is never a gate, it only reports.
use LaravelUi5\Sdk\WorkItems\Contracts\WorkItemRuleInterface;
use LaravelUi5\Sdk\WorkItems\WorkItemFinding;
final readonly class MissingTariffRule implements WorkItemRuleInterface
{
public function code(): string
{
return 'controlling.tariff_missing';
}
public function findings(): iterable
{
foreach (CostObject::query()->withoutTariff()->get() as $object) {
yield new WorkItemFinding(
subject: "co_object:{$object->code}",
role: AppRole::Controller,
text: "{$object->code}: no tariff for the activity Consulting.",
fix: 'Create the tariff in the Controlling app.',
action: ['intent' => 'ui5-artifact.open', 'target' => 'com.example.controlling'],
);
}
}
}Tag it in your service provider, and it takes part in every run:
$this->app->tag([MissingTariffRule::class], WorkItemRuleInterface::class);The text is yours, free text in the tenant's base language: the run writes it at night, when there is no request whose language it could take. The action is the intent that opens the subject in the app that owns it — the inbox shows and links, it never edits.
The severity is WorkItemSeverity::Action (asks someone to act, the default) or Notice (asks for a look).
Who sees an item
The addressee is a role — an enum case or its token, exactly as your module declares it with #[Role] and ui5:sync writes it into sdk_roles —, optionally one partner, and for a role scoped to a model, the model the role is held on:
#[Role(AppRole::ProjectManager, 'Leads a project.', scope: CostObject::class)]
new WorkItemFinding(subject: "co_object:{$object->code}", role: AppRole::ProjectManager,
text: '…', context: $object); // pass the model — the SDK derives its morph keyThe run checks every addressee before its first write: a scoped role needs its model as the context, a global role takes none, and the model must be of the role's scope. A finding that breaks it is the rule's defect, and the whole rule is refused at the run — not found weeks later by nobody seeing the item.
A person sees an item when it names them, or — naming no one person — when they hold its role through a direct role assignment valid at the moment of reading, and on the item's context where it has one. Anna, project manager of 26‑014, sees the items about 26‑014, not those about 26‑015. This is the mechanism #[ScopedByRole] reads, so the inbox and the owning app agree on who is responsible for what. A role someone holds only through a group does not put items in their inbox.
Running the rules
php artisan ui5:work-itemsAn automation command: it runs every tagged rule, each in a unit of work of its own, so a failing rule rolls back alone while the others are reconciled. Each rule's run is recorded in sdk_work_item_runs — when it ran, when it last succeeded, and the error if it failed. The command exits 1 when a rule failed, and refuses to start when two rules share a code.
The SDK does not schedule it. Whoever runs the installation decides when — on the Foundation a characteristic does; on the SDK alone, add it to your scheduler:
Schedule::command('ui5:work-items')->dailyAt('05:00');Reading and dismissing
WorkItemServiceInterface is the one entry point:
| Method | Returns |
|---|---|
forPerson($person, $at) / count($person, $at) | the pending items a person sees — the inbox |
open($role, ?$partner, ?$context) | a role's pending items, optionally of one partner or on one context |
dismiss($item, $reason, $sdk) | a person takes note of an open finding and leaves it — the reason is required |
all() | every item in every state — the IT lead's view |
marks($item, $at) / marked($at) | how a pending item hangs (below) |
A dismissed finding stays dismissed while its rule still finds it, and is resolved when it is gone. What a person decides is audited — the state, who closed the item, the reason —; the nightly sighting is not. Every write runs inside your unit of work; the service opens none. When an item is resolved or dismissed, WorkItemClosed is dispatched after the commit.
Items left hanging
An item can hang in three ways, and marks() names them:
| Mark | Means |
|---|---|
RuleGone | no tagged rule has its source any more — it will never be reconciled again |
RuleFailed | its rule failed at the last run — the item shows the state of the rule's last success |
Unaddressed | nobody can see it — no partner named, and nobody holds its role (on its context) |
Nothing closes on its own: a finding is true until it is fixed. Instead, the person technically responsible at the customer looks at the marked items every Monday morning, and before every release, and acts — dismisses with a reason, assigns the missing role, has the rule repaired. marked($at) is that list.
Related
- The Audit — what a dismissal leaves behind.
- Database Schema —
sdk_work_items,sdk_work_item_runs.