AGENTS.md — BusinessProcessCore

Read this before building or changing a business process. It catalogs what the core gives you and the contracts a process must honor. The authoritative sources are spec/business-process-data-model-spec.md and the Business Process API contract; if this file disagrees with them, they win — and fix this file.

Contents of core/

The core ships no workflows. Every workflow, notification, and task-raising action lives in the business process solutions.

Capability catalog (what a process gets for free)

Process tracking tables

Rules from the spec that every process flow must follow:

• After every faf001_bpstep write, update the instance's faf001_status, faf001_statusmessage, and faf001_lastupdated (step first, then instance).
• Error columns are for failures only; faf001_statusmessage explains the why.
• Payloads go in faf001_bpdatavalue, never on the instance or step.
• Populate exactly one value column, matching faf001_datatype.
• Data keys share one namespace per instance: globalKey, <step>.<field>, <widget-prefix>.<field>.

Choice values used by flows

Full list (14 choices) in solution/export/OptionSets/ and the spec.

The step trigger contract

A process stage is a Copilot Studio workflow with a Dataverse trigger on faf001_bpstep (scope Organization = 4). Two shapes are used:

Step names are therefore API: never rename one without updating every trigger that filters on it. Make step names unique across all processes in the environment (prefix with the process domain).

The human task contract

1. The raising flow creates a faf001_bpstep with faf001_steptype = 324010001 (Human Task) and faf001_status = 324010002 (Waiting).
2. It creates a faf001_bptask linked to the instance and that step, with faf001_widgetid, faf001_inputdata (JSON the widget renders), faf001_tasktype, faf001_status = 324010003 (Waiting), and faf001_requiredrole bound to a role looked up by name (roles?$filter=name eq '<Role>', bind null if not found).
3. It sets the instance to Waiting, then notifies eligible users (process-side pattern — see business-processes/AGENTS.md).
4. A user claims → starts → completes the task in the Workflow Console through faf001_AssignTask / faf001_StartTask / faf001_CompleteTask.
5. faf001_CompleteTask atomically writes outcome, notes, and widget outputs as faf001_bpdatavalue rows and sets the linked step to Completed (324010003) — which fires the next stage's trigger.

Output keys. The prefix is the widget ID with a trailing -ui removed (fallback: normalized task name). The server always writes <prefix>.decision (approved | rejected | needs_info) and <prefix>.notes; widget values become <prefix>.<key>. Example: widget extracted-order-review-ui → extracted-order-review.decision, extracted-order-review.edited_order. The next flow reads them by faf001_datakey (order by modifiedon desc, top 1).

Business Process API (Custom Actions)

Consumed by the console and the monitoring agent; flows normally use the Dataverse connector on the tables directly. All are unbound, synchronous, run as the caller.

Configuration, identity, and agent

• faf001_WorkflowConsoleBaseUrl — environment variable with the console launch URL. Read current value (fallback: default) from environmentvariabledefinition / environmentvariablevalue, then append page=StartTaskDetail&taskId=<task id> (use & or ? depending on whether the URL already has a query string).
• Dataverse connection reference faf001_sharedcommondataserviceforapps is owned by the core; process solutions reuse it rather than defining their own.
• Runtime security role — defined in solution/config/security-role.business-process-user.json; least privilege, never widened for a single process.
• Business Process Monitoring Agent (bots/faf001_businessprocessmonitoringagent) — process-agnostic; a new process needs no changes to it.

Extension points vs. frozen surface

Changing the core itself

Only when the change is genuinely process-agnostic and the user has agreed (issue first). Changes ripple — update all affected places in the same change:

Choice values are append-only: add new values at the end of the 32401xxxx sequence.