agentleFS
hydrhydr/dataverse-modelling-mcp/skills/business-process-flows/SKILL.md

business-process-flows

Skill8 starsChanged 41 days agoMITView on GitHub

Create, read, change and run Business Process Flows (Dataverse "Geschäftsprozessflüsse", process bar on top of model-driven forms) via the dataverse-modelling-mcp server — without the designer. Covers the JSON definition (stages, data/action/flow steps, branches, cross-table stages, triggered workflows), validation codes and their fixes, activation, ordering, security roles, and moving running instances between stages. Use when the user mentions business process flow, BPF, Geschäftsprozessfluss, process stages, stage gates, the process bar, or wants to guide users through a sales/service process.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. korchard333/claude-power-platform-community★ 46same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository7 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Only write back when fullyUnderstood is true.

    line 91
  2. Very specific:

    Only an active instance moves.

    line 114

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Business Process Flows on Dataverse

A business process flow (BPF) is a workflow row with category = 4. Its XAML describes stages, not actions. You never write that XAML. You describe the process as a JSON definition; the server generates the XAML in exactly the shape the designer writes, and the platform derives everything else from it on save — clientdata, uidata (what the process bar renders and where branch conditions are evaluated) and the processstage rows.

Format reference: docs/business-process-flows-reference.md in this repository.

Tool map

IntentTool
Which processes exist on a table, in which order?bpf_list
Get a process as editable JSONbpf_get_definition
Check a definition before writingbpf_validate_definition (with processId when it replaces a process)
Which relationship leads from table A to table B?bpf_find_relationships
Create a process (optionally activate it)bpf_create
Rewrite a process — also while it is activebpf_set_definition
Rename / describebpf_update
Activate / deactivatebpf_set_state
Deletebpf_delete
Which process new records getbpf_set_order
Let a security role use the processbpf_grant_access
Raw XAML for backupbpf_export_xaml
Undo a changebpf_restore_xaml
Instances on a recordbpf_instance_list
Start a process on a recordbpf_instance_start
Move an instance to another stagebpf_instance_move
Finish, abandon, reactivate an instancebpf_instance_set_status

Standard workflows

Create a process

bpf_validate_definition(definitionFile) → fix issues
→ bpf_create(name, definitionFile, uniqueName | solutionUniqueName, activate=true)
→ bpf_grant_access(processId, roleIds)
→ bpf_set_order(primaryEntity, processIds)   (only if the table has several processes)
  • In a solution: pass solutionUniqueName. The process goes into the solution on create, and its instance table on the first activation — the solution exports only with both. Activating later with bpf_set_state? Pass solutionUniqueName there.
  • Process order: a new process is placed after the table's existing ones, so it does not take over new records from the current default. Put it first with bpf_set_order if that is wanted.
  • The first activation takes about two minutes: it creates the table that stores the instances (logical name = uniqueName, e.g. sample_leadtoorder) with a lookup per table of the process (bpf_<table>id), activestageid and traversedpath.
  • An active process applies itself to every new record of its table for users who have access to it — lowest process order first, processes without an order last, shortly after the record is created (asynchronously). Equal orders have no defined order; bpf_list shows them by name, and bpf_set_order gives every process a distinct number. Do not leave test processes activated in a shared environment.
  • Until bpf_grant_access runs, only System Administrator and System Customizer see the process. Users who create records need Create on the instance table, or the automatic start fails. bpf_grant_access only adds privileges (organisation depth): readOnly takes nothing away, and there is no revoke — remove privileges in the role itself.

Change a process

bpf_get_definition(processId) → edit the JSON → bpf_set_definition(processId, …, dryRun=true)
→ read diff and issues → bpf_set_definition(processId, …, backupFile=…)
  • An activated process can be rewritten in place (unlike a classic workflow): no deactivation. A table that is new in the process gets its lookup column during the write.
  • Keep stageId and stepId. Running instances point at the stage id (activestageid). Stages and steps you leave without an id are matched to the existing ones — stages by name and table, data steps by attribute, action/flow steps by process, triggers by workflow and event — so a definition written from scratch keeps the ids too.
  • To rename a stage, keep its stageId. Matching is by name, so a renamed stage without its id is a new stage, and the old one is removed (BPF062 points this out and names the id to keep). Removing a stage that active instances stand on is refused (BPF060) unless allowStageRemoval=true.
  • To check a definition against the process it replaces — same id matching, same instance check — call bpf_validate_definition with processId. dryRun=true on bpf_set_definition lists every change in diff (stages, steps, labels, required flags, next, branches, relationships, triggers); new stages and steps show no id there, as they only get one on the real write.
  • In a definition read back, next, branch targets and fromStage name stages by id — so a rename stays a one-field change. The path list next to it shows the same with names.
  • Only write back when fullyUnderstood is true. Task-flow pages, the link controls of the shipped system processes, closed loops and action steps with input parameters are not authored here; the parser lists them in unrecognised.

Work with running instances

bpf_instance_list(entity, recordId)            → instance ids, active stage, status
bpf_instance_move(processId, instanceId, stageId [, recordId])
bpf_instance_set_status(processId, instanceId, "finished" | "aborted" | "active")
bpf_instance_start(processId, recordId [, stageId])

Moves go back to any passed stage, or forward to the stage that follows the active one (its next or a branch target) — one stage at a time, like the form. Branch conditions are not evaluated server-side: moving to a branch target is the caller's decision. A move onto a stage of another table needs recordId — the record of that table the process continues on.

  • A record holds one instance per process. bpf_instance_start on a record that already has one starts nothing and returns the existing instance with created: false — move that one instead. An active process usually has started it already (see above).
  • stageId on bpf_instance_start must lie on the main path (the next chain) within the primary table; anything else: start at the first stage and move.
  • Only an active instance moves; a finished or aborted one needs status: "active" first.
  • finished is only possible on the last stage of a path (no next, no branch).

The definition

{
  "primaryEntity": "lead",
  "languageCode": 1033,
  "workflows": [ { "workflowId": "<guid>", "on": "finished" } ],
  "stages": [
    {
      "name": "Qualify",
      "category": "Qualify",
      "steps": [
        { "attribute": "parentaccountid", "label": "Existing account?" },
        { "attribute": "budgetamount", "required": true },
        { "kind": "action", "processId": "<guid of an on-demand workflow or custom action>", "label": "Score lead" }
      ],
      "workflows": [ { "workflowId": "<guid>", "on": "stageExit" } ],
      "branch": {
        "branches": [ {
          "description": "Large deal",
          "conditions": [ { "attribute": "budgetamount", "operator": "GreaterEqual",
                            "value": { "kind": "literal", "dataType": "Money", "literal": "50000" } } ],
          "next": "Executive review"
        } ],
        "else": "Develop"
      }
    },
    { "name": "Executive review", "steps": [ { "attribute": "description" } ], "next": "Develop" },
    {
      "name": "Develop",
      "entity": "opportunity",
      "relationship": { "name": "opportunity_originating_lead" },
      "steps": [ { "attribute": "customerneed" },
                 { "kind": "flow", "processId": "<guid of an instant flow>", "required": true } ]
    }
  ]
}

How the path works

  • The main path is the next chain from the first stage. Without next, a stage leads to the one listed after it; the last stage ends the path; "next": "end" ends it early.
  • A branch decides when the user leaves its stage: the first case that holds names the next stage, otherwise else. A branching stage still has a next — the platform stores it as the main path, and bpf_instance_start with stageId follows it. Point it at the stage most records take (usually the else target, or the stage where the branches merge again).
  • Tables follow the path, not the list. A stage without entity continues on the table of the stages leading to it (over next or a branch). Where those are on different tables, the stage must name its table (BPF044). Every way into a stage from another table needs that stage's relationship (BPF040) — whether the way is the main path or a branch. A branch may lead straight to a stage on another table.
  • No loops (BPF051, BPF052). To send a record back, move its instance with bpf_instance_move.

Definition

FieldMeaning
primaryEntityTable the process starts on. The first stage is on it. Fixed after creation (BPF008).
stagesStages in display order. The path runs top to bottom unless next or a branch says otherwise.
languageCodeLanguage of all labels. Defaults to the organisation's base language.
workflowsProcess-level ("global") workflows: on = applied, reactivated, finished, abandoned.

Stage

FieldMeaning
stageIdGUID. Keep it on existing stages; assigned when absent.
keyOptional handle for references. A stage can also be referred to by its name or id (precedence: key, id, name).
nameLabel in the process bar.
entityTable of the stage. Defaults to the table of the stages leading to it (see "How the path works"); bpf_get_definition lists every stage's table under path.
categoryQualify, Develop, Propose, Close, Identify, Research, Resolve, Approval (or the number). Reporting only.
stepsSteps in display order (max 30).
nextStage that follows on the main path (key, name or id). Default: the next one in the list; the last stage ends the path. "end" ends it early. A branching stage keeps one too — see above.
branchCondition evaluated when the user leaves the stage — see below.
relationshipHow the process reaches this stage from a stage on another table. Required whenever a way into the stage comes from another table.
workflowsWorkflows run on stageEnter / stageExit.

Step

FieldMeaning
kindfield (default, the designer's "data step"), action (button running an on-demand workflow or a custom process action), flow (button running an instant cloud flow).
stepIdGUID. Keep it; assigned when absent.
labelText shown. Defaults to the attribute's display name / the process name.
attributefield: column of the stage's table.
requiredfield: the stage cannot be left empty. flow: the flow must have run. Not for action (BPF027).
processIdaction: workflow (category 0, on-demand) or custom action (category 3) on the stage's table. flow: the workflow id (category 5) of an instant flow — manually triggered, in a solution; a scheduled or automated flow cannot be started by the button (BPF311).
classIdfield: form control class; derived from the attribute type. Only read back to keep an existing step unchanged.
parametersfield: raw control parameters (duplicate detection of system lookups). Read back and written unchanged; not to be authored.
systemControlfield: marks a system control. Read back and written unchanged.

Branch

branch.branches is an if / else-if chain; branch.else the stage taken when no case holds.

FieldMeaning
branchesCases, tested in order.
elseStage when no case holds. Optional for the platform — but the designer refuses to save a condition without it (BPF026). Must name a stage; to end the process on that way, give the target stage "next": "end".
conditionsComparisons, in the shape of the classic-workflow definitions: attribute, operator, value (literal or field), bracketed groups via conditions + groupOperator.
logicalOperatorAnd (default) or Or.
nextStage taken when the case holds.
descriptionName of the case in the designer.

Rules the designer enforces and the validator checks:

  • A condition can only compare the stage's own data steps (BPF024) — the designer offers no other fields and rejects them on save. Add a data step for the field, or move the condition.
  • Operators: Equal, NotEqual, GreaterThan, GreaterEqual, LessThan, LessEqual, Contains, DoesNotContain, BeginsWith, DoesNotBeginWith, EndsWith, DoesNotEndWith, Null, NotNull (BPF019). No relative dates.
  • Conditions are evaluated in the browser, from uidata, when the user clicks "Next stage".
  • The check only runs once every field the stage's conditions read has a value. While one is empty, no case applies and the instance continues on next. Make those data steps required (warning BPF028) — that also makes Null/NotNull comparisons pointless.
  • The literal must have the column's type. The generated check compares strictly: a choice compared with "1" as text never matches the option 1. Leave dataType out and the server takes it from the column (BPF306 when the literal does not fit, BPF312 when the option does not exist).
Column typeliteraldataType (filled in when omitted)
Choice, statusthe option's number: "74" — not the labelOptionSetValue
Yes/no"true" / "false" ("1" / "0" work too)Boolean
Lookup"<table>:<guid>:<label>", e.g. "account:<guid>:Contoso"EntityReference
Whole number"50"Integer
Decimal, float, currency"10000.50" (dot as separator)Decimal / Double / Money
Date"2024-01-31"DateTime
Textany textString

Example — branch on a yes/no field of a lead into a stage on another table:

{ "name": "Qualify", "steps": [ { "attribute": "sample_needsstrategy", "required": true } ],
  "next": "Develop",
  "branch": { "branches": [ { "conditions": [ { "attribute": "sample_needsstrategy", "operator": "Equal",
                                                "value": { "kind": "literal", "literal": "true" } } ],
                              "next": "Strategy" } ],
              "else": "Develop" } },
{ "name": "Strategy", "entity": "opportunity", "relationship": { "name": "opportunity_originating_lead" },
  "steps": [ { "attribute": "description" } ], "next": "end" }

Relationship

FieldMeaning
nameSchema name of a 1:N relationship from the table the process comes from to this stage's table, e.g. opportunity_originating_lead. bpf_find_relationships(fromEntity, toEntity) lists the candidates; so does the fix of BPF040.
attributeThe lookup on this stage's table (e.g. originatingleadid). Filled in from metadata when omitted.
fromStageThe stage the process comes from. Leave it out: the relationship then covers every way into this stage from that table — e.g. two branches that merge into the stage. Set it only to restrict it to one way (BPF045).

Triggered workflow

FieldMeaning
workflowIdAn activated, on-demand classic workflow on the stage's table (stage level) or the primary table (process level).
onStage level: stageEnter, stageExit. Process level: applied, reactivated, finished, abandoned.
triggerIdGUID of the trigger inside the process. Keep it; assigned when absent.

Validation codes

BPF0xx are model checks, BPF3xx checks against live metadata. Every finding names a path and a fix.

CodeMeaningFix
BPF000Definition missing or not valid JSONPass the definition; check the JSON
BPF001No primaryEntitySet it
BPF002No stagesAdd at least one
BPF003Stage without nameSet name
BPF004First stage not on the primary tableRemove its entity or change primaryEntity
BPF005Key or id used twiceMake them unique
BPF006Id is not a GUID, or a step id equals a stage idRemove it to have one assigned
BPF007Unknown stage categoryUse a listed category or leave it out
BPF008primaryEntity differs from the existing processKeep it; create a new process instead
BPF009uniqueName invalid or taken (error), or without the solution publisher's prefix (warning)<prefix>_<name>, lowercase, unused
BPF010next names no stageUse key, name, id or "end"
BPF011Stage leads to itselfPoint next elsewhere
BPF012Branch target names no stage, or else is "end"Fix the reference; end the path on the target stage instead
BPF013Branching without cases, or a case without comparisonsAdd them, or remove branch
BPF014Case without nextSet it
BPF015Case leads back to its own stagePoint it elsewhere
BPF016Unknown logical operatorAnd / Or (any case)
BPF017Comparison without attributeSet attribute
BPF018Comparison or compared value reads another table (entity, via, fromStep, a fields entry with another table's prefix)Compare the stage's own columns
BPF019Operator not available, value missing/ignored, or value kind other than literal/fieldSee the operator list
BPF020Unknown step kindfield, action, flow
BPF021Data step without attributeSet attribute
BPF022Stage without steps — the platform refuses it (0x80060416)Add a step
BPF023Action/flow step or trigger without a valid process idSet processId / workflowId
BPF024Condition on a field that is no data step of the stageAdd the data step, or compare another field
BPF025Trigger event not allowed at this levelStage: stageEnter/stageExit; process: applied/reactivated/finished/abandoned
BPF026Condition without else (warning)Add an else stage if the designer must still open it
BPF027Flag ignored on this step kind (warning)Remove it
BPF028Branch reads a field that is not required (warning)Make the data step required
BPF029A case leads where else leads anyway (warning)Point it elsewhere or remove it
BPF030More than 30 stages on one tableSplit the process
BPF031More than 30 steps in a stageMove steps to another stage
BPF032More than 5 tablesSplit the process
BPF040A way into the stage comes from another table, but the stage has no relationshipAdd one of the relationships the fix lists
BPF041Relationship without nameSet name
BPF042fromStage names no stageFix or remove it
BPF043Relationship starts at a stage on the same table (warning)Remove it or set fromStage
BPF044Stage without entity reached from stages on different tablesSet entity
BPF045Ways in from two tables (error), or fromStage leaves out another way from the same table (warning)Route through one table; remove fromStage
BPF050Stage unreachable (warning)Point next or a branch at it, or remove it
BPF051The main path loopsEnd the path; use "end"
BPF052A branch or next leads back to an earlier stagePoint it forward; move instances back with bpf_instance_move
BPF053A stage named "end" — next: "End" ends the path instead of naming it (warning)Give it a key, or rename it
BPF060A removed stage still has active instances (error; warning with allowStageRemoval) — or finished/aborted ones that could be reactivated onto it (warning)Keep its stageId if renamed; else move the instances first
BPF061Current process has parts this server does not understand (warning)They are dropped on write — check unrecognised
BPF062A stage looks renamed without its id (warning)Set the stageId the fix names
BPF300Table does not existCheck the logical name
BPF301Column does not existSee the suggestions; table_get lists the columns
BPF302Column type cannot be shown in a data stepPick another column
BPF303Relationship does not exist or is not 1:NUse a 1:N relationship
BPF304Relationship does not connect the two tables, or attribute mismatchesUse the relationship from the previous table to this one
BPF305Table not enabled for business process flowstable_update with IsBusinessProcessEnabled = true — irreversible
BPF306Literal does not fit the column's type (dataType wrong, or e.g. a label for a choice)See the literal table; the fix lists a choice's options
BPF307Referenced workflow/action/flow does not existCheck the id
BPF308Referenced process of the wrong kind (or not on-demand)See the step kind's requirement
BPF309Referenced process not activatedActivate it
BPF310Referenced workflow/action runs on another tableUse one on the stage's (or primary) table
BPF311Flow step on a flow that starts on its own — schedule, row change, e-mail, HTTP (warning)Use an instant flow
BPF312Choice compared with a number that is no option (warning)Use one of the listed options
BPF313Data step on a column users cannot change (warning)Pick an editable column, unless showing it is the point

Platform facts worth knowing

  • Create needs scope = 4. Without it the platform's own validation throws a NullReferenceException, surfaced as 0x80040216 An unexpected error occurred. bpf_create sets it.
  • Errors come in two layers: the Web API returns the generic 0x80040216; the SOAP endpoint carries the server stack trace (BpfEntityAttributeValidationStep, UIDataGenerator.ReadControlStep) — useful when something new fails.
  • Delete: an activated process cannot be deleted (0x8004500f); deactivate first. Deleting takes two to three minutes; the instance table disappears asynchronously afterwards.
  • Export in a solution: a process exports only together with its instance table — so a process that was never activated cannot be exported (0x80060376). Activate it once, then add both (solution_add_component: the workflow as type 29, the table as type 1).
  • Unknown properties are refused (BPF000 with the path): a typo such as requried would otherwise be dropped silently.
  • Actions are stored by their SDK message name (sample_NotifyOwner), not by the workflow's unique name; the server resolves it.
  • The designer saves through an internal endpoint (ProcessControl.asmx), not the Web API. Writing the xaml column through the Web API produces the same uidata as a designer save — verified by comparing both.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.