classic-workflows
Skill8 starsChanged 41 days agoMITView on GitHub
Read, explain, edit and create Classic Workflows (Dataverse "Prozesse" of category Workflow) via the dataverse-modelling-mcp server. Covers the declarative definition model, the JSON shape for steps and values, validation codes and their fixes, custom code activities, and the architecture behind the format (server-rendered designer, incremental saves, naming conventions). Use when the user asks about classic workflows, background/real-time workflows, workflow XAML, or wants to understand or change an existing process.
In this repository7 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- business-process-flowsSkill
- cloud-flowsSkill
- command-bar-buttonsSkill
- form-authoringSkill
- modeling-patternsSkill
- solution-pipelinesSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 58
Read the tail of the report.
- Very specific: line 73
If fullyUnderstood is false, stop and tell the user which parts are unsupported.
- Very specific: line 97
Verify afterwards rather than assuming: read the definition back and diff it against what you meant to write (step ids are regenerated, so …
- Very specific: line 382
When the branch does not run, the variable is Nothing, and the Add behind concat tolerates that — the same way an optional field read …
≈ “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.
Files
Classic Workflows on Dataverse
Classic Workflows store their logic as WF4 XAML in workflow.xaml. You never write that XAML by
hand. You describe the logic as a JSON definition; the server generates conventional XAML from it.
Full format reference: docs/classic-workflows-reference.md in this repository.
Related records and the 87 activities of msdyncrmWorkflowTools: see workflow-tools.md next to
this file. Read it before concluding that something "cannot be done with classic workflows" —
team membership, N:N checks, multi-select fields, FetchXML queries and deletes are all available
through that assembly.
Why the definition model exists
The classic designer is server-rendered: every edit is a SOAP call that rewrites the XAML
server-side and returns HTML for display. The designer rebuilds its view from the XAML alone
(clientdata is always null), and it does so by relying on naming conventions — step ids,
DisplayName values and variable names. Hand-written XAML that breaks a convention produces
0x80045037 and the process can no longer be opened.
workflow_set_definition owns all naming, so that class of error cannot occur. Everything else is
caught by validation before anything is written.
Tool map
| Intent | Tool |
| What does this workflow do? | workflow_explain |
| Get the logic as editable JSON | workflow_get_definition |
| Check a definition before writing | workflow_validate_definition |
| Write logic | workflow_set_definition |
| Create a new (empty) workflow | workflow_create |
| Triggers, mode, scope, subprocess | workflow_update |
| Activate / deactivate | workflow_set_state |
| Raw XAML for backup or diffing | workflow_export_xaml |
| Undo a change | workflow_restore_xaml |
| Delete a workflow (and its activation copies) | workflow_delete |
| Find out why a definition will not activate | workflow_diagnose_activation |
| Change the owner | workflow_assign |
| Check an existing workflow (not a definition) | workflow_validate |
| Available code activities | workflow_list_activities |
| Parameters of a code activity | workflow_get_activity_parameters |
Standard workflows
Explaining an existing workflow
workflow_list (filter) → workflow_explain(workflowId)Read the tail of the report. A "Not understood" section means the XAML contains constructs the
parser cannot map. The explanation is then incomplete — and you must not rewrite that workflow with
workflow_set_definition, because the unmapped parts would be dropped.
Changing an existing workflow
1. workflow_export_xaml → keep as restore point
2. workflow_get_definition → check "fullyUnderstood": true
3. modify the JSON → with a script, in a file, never by retyping it
4. workflow_validate_definition → definitionFile=…, fix all errors
5. workflow_set_definition → definitionFile=…, backupFile=…, writes only when clean
6. workflow_set_state activate=trueIf fullyUnderstood is false, stop and tell the user which parts are unsupported. Offer to make the
change in the designer instead.
Never pass a real definition inline
definitionJson and xaml exist for small, hand-written payloads. Everything read out of a live
workflow is not that: a definition whose e-mail body carries a base64 signature image runs to ~28.000
characters, its XAML to ~180.000. Reproducing that corrupts it. Characters flip, and nothing
catches it — the JSON stays valid, all three validation gates pass, and the damage sits in the payload
the string transports. In August 2026 exactly this destroyed the signature logo in two dunning
workflows; it only surfaced when the PNG chunk checksums were recomputed.
So keep the content on disk and pass paths:
| Direction | Parameter | On |
| Definition in | definitionFile | workflow_set_definition, workflow_validate_definition, workflow_diagnose_activation |
| Previous XAML out | backupFile | workflow_set_definition |
| XAML back in | xamlFile | workflow_restore_xaml |
A too-large tool result is already written to a file for you, so the round trip needs no copy at any point: read the definition, edit the file with a script, pass its path back. Delegating the write to a subagent does not help — it has the same context window and makes the same mistake.
Verify afterwards rather than assuming: read the definition back and diff it against what you meant to
write (step ids are regenerated, so ignore stepId/branchId), and for an embedded image decode the
base64 and check the PNG chunk CRCs.
Creating a new workflow
1. workflow_create(name, primaryEntity) → draft with empty skeleton
2. workflow_set_definition(id, definition) → the logic
3. workflow_update(id, {"triggeroncreate": true, "createstage": 40}) → trigger (required!)
4. workflow_set_state(id, activate=true)Step 3 is not optional. Dataverse refuses to activate an automatic workflow that has no trigger
(0x80045018). Pick one:
| Intent | workflow_update payload |
| On create | {"triggeroncreate": true, "createstage": 40} |
| On change of specific fields | {"updatestage": 40, "triggeronupdateattributelist": "field1,field2"} |
| On delete (e.g. to prevent it) | {"triggerondelete": true, "deletestage": 20} |
| Started manually | {"ondemand": true} |
| Called by another workflow | {"subprocess": true} |
Stage 20 = pre-operation (inside the transaction, can block the operation), 40 = post-operation.
Blocking an operation additionally requires a real-time workflow ({"mode": 1}) and a
stopWorkflow step with outcome: "cancelled".
The definition shape
{
"primaryEntity": "lead",
"steps": [
{
"kind": "condition",
"description": "Only for German leads",
"conditions": [
{ "attribute": "address1_country", "operator": "Equal",
"value": { "kind": "literal", "literal": "Germany" } }
],
"then": [
{
"kind": "updateRecord",
"description": "Fill the domain",
"attributes": [
{ "attribute": "sample_domain",
"value": { "kind": "field", "fields": ["lead.websiteurl", "lead.emailaddress1"],
"fallback": "unknown" } }
]
}
],
"else": [
{ "kind": "stopWorkflow", "outcome": "succeeded",
"reason": { "kind": "literal", "literal": "Not a German lead" } }
]
}
]
}Step kinds
kind | Purpose | Required fields |
condition | If/then/otherwise, or an if/else-if chain | conditions + then, or branches; plus optional else |
wait | Wait until a condition holds (background workflows only) | like condition |
stage | Grouping. If one step is in a stage, all must be | children |
createRecord | Create a record of any table | entity, attributes |
updateRecord | Update the triggering record | attributes |
assignRecord | Change owner | ownerId, optional ownerType |
changeStatus | Set statecode/statuscode | state and/or status |
customActivity | Run a code activity | assemblyQualifiedName, optional inputs/outputs |
startChildWorkflow | Start another workflow | childWorkflowId |
stopWorkflow | End the workflow | optional outcome, reason |
sendEmail | Compose and send an e-mail | attributes (at least to and subject) |
performAction is read-only: it is reported by workflow_explain but cannot be generated —
configure it in the designer.
Sending an e-mail
A sendEmail step composes an email record and sends it; the attributes are those of email.
The recipient fields (from, to, cc, bcc) are party lists, so they take
dataType: "PartyList" — a fixed recipient as "systemuser:<guid>", a dynamic one as a field:
{
"kind": "sendEmail",
"description": "Report assignment",
"attributes": [
{ "attribute": "from", "value": { "dataType": "PartyList", "literal": "systemuser:<guid>" } },
{ "attribute": "to", "value": { "kind": "field", "dataType": "PartyList", "fields": ["lead.ownerid"] } },
{ "attribute": "subject", "value": { "literal": "New lead assigned" } },
{ "attribute": "description", "value": { "kind": "concat", "parts": [
{ "literal": "Lead: " }, { "kind": "field", "fields": ["lead.companyname"] } ] } },
{ "attribute": "regardingobjectid",
"value": { "kind": "field", "dataType": "EntityReference", "fields": ["lead.leadid"] } }
]
}regardingobjectid links the e-mail to the triggering record — without it, the e-mail does not
appear in any timeline. For an HTML body, description is a concat of text fragments and fields.
The standard step cannot resolve an e-mail to a team; for that there is
msdyncrmWorkflowTools.Class.EmailToTeam (see workflow-tools.md).
The definition also carries realtime, but you do not set it: the server takes it from the workflow
record, because a real-time process must not contain persistence points and the generated XAML
therefore differs by mode.
Several cases in one condition
The designer allows an if / else-if chain: one condition step with several branches, each with its
own comparisons, tested in order — the first that holds runs, the rest are skipped. Use branches
instead of conditions/then; else is the default case either way:
{
"kind": "condition",
"description": "Check prerequisites",
"branches": [
{ "conditions": [ { "attribute": "sample_invoicenumber", "operator": "Null" } ],
"steps": [ { "kind": "stopWorkflow", "outcome": "cancelled" } ] },
{ "conditions": [ { "attribute": "sample_reminderdate", "operator": "NotNull" } ],
"steps": [ { "kind": "stopWorkflow", "outcome": "cancelled" } ] }
],
"else": [ { "kind": "updateRecord", "attributes": [ … ] } ]
}This is not the same as nesting conditions inside else: it produces the shape the designer
produces, one condition step with N branches. The typical use is a guard clause per precondition, each
with its own exit — that is how the payment reminder workflow is built (six cases).
Mixing branches with conditions/then in the same step is rejected as WF140.
Several comparisons in one case are combined with logicalOperator: "And" (default) or "Or".
It sits next to the conditions list — in the short form on the step, in a chain on the branch.
Mixing And and Or: groups
One level combines its comparisons with a single operator, so A And (B Or C) needs a bracket. An
entry of conditions becomes one by carrying conditions of its own plus a groupOperator, instead
of an attribute and an operator:
{
"kind": "condition",
"logicalOperator": "And",
"conditions": [
{ "attribute": "new_paymentmethod", "operator": "In",
"value": {"kind":"literal","dataType":"OptionSetValue","literals":["100000000","100000001"]} },
{ "groupOperator": "Or", "conditions": [
{ "attribute": "new_accountowner", "operator": "Null" },
{ "attribute": "new_bic", "operator": "Null" } ] }
],
"then": [ … ]
}Groups nest to any depth and work in a branches case just as well. Nothing else changes: a level
whose members all share one operator is still written — and read back — as a flat list.
The XAML needs no new construct for this, because the combination has always been a tree:
EvaluateLogicalCondition takes a LeftOperand and a RightOperand, and either may be the result of
another one. A designer-authored example is kept as the condition-group fixture.
Comparison operators
| Group | Operators |
| Equality | Equal, NotEqual |
| Emptiness (take no value) | Null, NotNull |
| Text | Contains, DoesNotContain, BeginsWith, DoesNotBeginWith, EndsWith, DoesNotEndWith |
| Numbers | GreaterThan, GreaterEqual, LessThan, LessEqual |
| Sets | In, NotIn — use literals for the values |
| Ranges | Between, NotBetween |
| Dates, with a value | On, OnOrAfter, OnOrBefore — often against {"kind":"now"} |
| Dates, without a value | Today, Yesterday, Tomorrow, Last7Days, Next7Days, LastWeek, ThisWeek, NextWeek, LastMonth, ThisMonth, NextMonth, LastYear, ThisYear, NextYear |
Anything else is rejected as WF072. An operator that takes no value gets WF074 if you supply one
anyway; one that needs a value gets WF073 if you leave it out.
Value kinds
kind | Meaning | Example |
literal | Constant | {"kind":"literal","literal":"Active","dataType":"String"} |
literal with literals | A set of constants, for In/NotIn | {"kind":"literal","dataType":"OptionSetValue","literals":["1","2","3"]} |
field | One or more fields, first non-empty wins, optional fallback | {"kind":"field","fields":["lead.websiteurl","lead.emailaddress1"],"fallback":"unknown"} |
stepOutput | Output of an earlier code activity | {"kind":"stepOutput","stepOutput":"Domain"} |
now | Current date and time, evaluated at run time | {"kind":"now","dataType":"DateTime"} |
concat | Several values joined into one string | {"kind":"concat","dataType":"String","parts":[{"literal":"No. "},{"kind":"field","fields":["invoice.sample_invoicenumber"]}]} |
concat is what an e-mail body is made of: constants and field values in order, nested as deep as
needed. now works both as a written value and as the right-hand side of a date comparison
(OnOrAfter, OnOrBefore, …).
A deadline: offset
Any date value may carry an offset, which is how the designer computes a due date. The dunning
workflows use it to set the next dunning level's deadline a week out:
{"kind":"now","dataType":"DateTime","offset":{"days":7}}offset takes years, months, days, hours and minutes; anything omitted is zero, and negative
values move the date backwards. It also applies to a field, which then shifts that field's date
instead of the current time.
An empty date is not an offset and not a special kind — it is a
literalwith noliteralvalue. That is how "clear this field" is expressed, and the reader distinguishes it from a value it failed to understand: an unresolvable expression is reported inunrecognised, a deliberate clear is not.
dataType defaults to String. Others: Integer, Boolean, DateTime, Decimal, Double,
Money, OptionSetValue, EntityReference, Guid. Set it whenever the target field is not text —
for a plain field a wrong type produces a runtime failure; on a code activity's input it is caught as
WF086.
An EntityReference literal is written as "<entity>:<guid>", e.g.
"team:11112222-3333-4444-5555-666677778888".
Field references are always entity.attribute with logical names. Which record they are read from
depends on one of three keys — without any of them, only the triggering record is readable:
| Read from | Key | Example |
| A directly linked record (one level) | via = the lookup attribute leading there | {"fields":["opportunity.sample_salesrep"],"via":"opportunityid"} |
A record an earlier createRecord step made | fromStep = its step id or the created entity | {"fields":["email.activityid"],"fromStep":"email"} |
| The record behind a code activity's output | fromStepOutput = the parameter name | {"fields":["systemuser.fullname"],"fromStepOutput":"InitiatingUser"} |
via reaches one level only; deeper paths need a child workflow or
msdyncrmWorkflowTools.QueryValues (see workflow-tools.md). With fromStepOutput the server emits
the record load itself, so the output being a mere reference is not a problem. All three work in
conditions[] as well.
Code activities
workflow_list_activities(nameFilter) → pick the pluginTypeId
workflow_get_activity_parameters(pluginTypeId)Take assemblyQualifiedName verbatim from the result — it carries the assembly's real
PublicKeyToken, and a wrong one makes the workflow fail to load. Use each parameter's
dependencyPropertyName as the key in inputs/outputs, not its display name (Email, not
E-Mail). Each parameter reports the dataType to use, and a lookup reports its allowed
entityNames.
You do not have to get the types right by inspection: the server reads the activity's real signature
before writing and reports a wrong name, a wrong dataType, a missing required input or a lookup on
the wrong table as WF085–WF089. Only what it cannot know statically — the target of a lookup
taken from a field — still surfaces at runtime.
Outputs of a step are referencable by later steps as <stepId>.<ParameterName> or by the bare
parameter name, which is usually what you want: step ids are assigned by the builder, so you cannot
know them when writing the definition. They come back in stepIds and are assigned in document
order, so a step can only use outputs of steps declared before it.
A value that exists only during the run
There is no "set variable" step, so a value that has to be computed in one place and used in another looks at first like it needs a helper column. It does not. An activity's output is a workflow variable, scoped to the single run, and it is empty when the activity did not execute. That gives you a conditional text block without persisting anything:
condition (payment method in …)
└─ then: customActivity StringFunctions
inputs.InputText = {"kind":"concat", …} ← the builder concatenates
outputs: ["TrimmedText"] ← the same text back out
…
createRecord email
description = {"kind":"concat","parts":[ …, {"kind":"stepOutput","stepOutput":"TrimmedText"} ]}msdyncrmWorkflowTools.StringFunctions is a pure pass-through here — InputText in, TrimmedText
out. Take the concatenation itself from the builder (concat), not from the activity: it cannot
concatenate. Note that the activity computes all of its outputs on every run, so give the
substring, padding and replace inputs values that cannot throw (a substring of length 1, padding to
length 0, a non-empty ReplaceOldValue).
When the branch does not run, the variable is Nothing, and the Add behind concat tolerates that
— the same way an optional field read without fallback does. So the else branch needs no step at all.
Reading back works too: workflow_get_definition reduces an input argument to the value it was built
from, even though the XAML stores only a reference into a chain of preparation activities
([DirectCast(Step1_1_converted, …)]). Fixed record references come back as "entity:guid", field
reads with their via, and an earlier activity's output as stepOutput. If a chain cannot be
reduced, that input is listed in unrecognised and fullyUnderstood is false — then change the step
in the designer rather than rewriting it.
Validation
workflow_validate_definition and workflow_set_definition run the same three gates:
- Model — completeness and consistency of the definition.
- Metadata — every table and attribute must exist in the environment, and the arguments of a code activity must match its real signature (both live lookups).
- Generated XAML — well-formed, all variables declared, step ids unique.
Nothing is written unless all three pass. Each issue carries code, path, problem and fix.
Issue codes
| Code | Meaning |
WF000 / WF001 | definitionJson is not valid JSON, or the definition is null |
WF002 / WF003 | primary entity or steps missing |
WF010–WF012 | step kind missing, unknown, or not generatable |
WF013 / WF014 | stage nested, or empty |
WF015 | stage without a description (warning — stages are the outline in the designer) |
WF020 / WF021 | create without entity; update targeting a different table |
WF030–WF032 | assign step: owner missing or malformed |
WF040 | change-status without state/status |
WF050 / WF051 | child workflow id missing or malformed |
WF060 | stop step with an unknown outcome (use "succeeded" or "cancelled") |
WF070–WF076 | condition: no comparisons, missing attribute/operator/value, no branches |
WF079 | comparison reads another table without via, fromStep or fromStepOutput |
WF077 / WF078 | condition on a step output: no parameter named, or no earlier step declares it |
WF080–WF084 | code activity: AssemblyQualifiedName missing/malformed, PublicKeyToken=null, empty parameter name |
WF085–WF089 | code activity checked against its real signature: unknown input (WF085), dataType not matching the parameter (WF086), required input missing (WF087), lookup pointing at a table the parameter does not accept (WF088), unknown output (WF089) |
WF090–WF092 | attribute assignments: none, unnamed, duplicated |
WF100–WF102 | value missing, unknown kind, unknown data type |
WF110–WF114 | literal null, ignored fields, null entry in literals, ignored fields on now, concat without parts |
WF120–WF122 | field value: no fields, bad reference format, non-primary entity |
WF130–WF132 | stepOutput: missing, malformed, or no matching earlier output |
WF140 | branches and conditions used in the same condition step |
WF200–WF202 | generated XAML failed self-check (internal defect — report it) |
WF210 | workflow is activated; deactivate or pass reactivate=true |
WF300 / WF301 | table or attribute does not exist (includes name suggestions) |
Rules and pitfalls
- A cancellation message that shows only the step name means the message was empty. Dataverse
falls back to the display name. The cause is a field read inside the message that names a target
type: for anything that is not text — a date above all — it comes back empty and takes the sentence
with it. The builder now reads untyped there, matching the designer. If you see it again, compare
the
GetEntityProperty.TargetTypeof that read against a designer-authored workflow. - Active workflows cannot be changed. Either deactivate first or pass
reactivate=true. If re-activation fails after writing, the response says so and the workflow stays a draft — never assume it is active again. - Keep the backup.
workflow_set_definitionreturns the previous XAML inbackup, or writes it tobackupFileif you give it a path — do give it one, both to keep the response readable and becauseworkflow_restore_xamlcan then takexamlFileand restore it without a copy. - Activating leaves a second row behind. Dataverse stores an activation copy (
type=2) that neither deactivating nor deleting the definition removes — an environment used for testing fills up with them.workflow_deletetakes them along; it refuses an activated workflow unlessdeactivateFirst=true. - Don't create workflows with
record_upsert. A create without validxamlis rejected with0x80045040.workflow_createsupplies a valid skeleton, so use it. 0x80045040on a write means "XAML not accepted", not "wrong access path" — even though the message talks about being "created outside of the web application". If you ever see it fromworkflow_set_definition, that is a builder defect worth reporting; the tool normally catches such cases beforehand.- Activation does not validate the logic. A step with missing configuration activates happily and fails at runtime. Validation in this server is stricter than Dataverse on purpose.
updateRecordwrites to the triggering record only. It uses a temporary entity internally and writes the result back.waitsteps require background mode (mode=0). In a real-time workflow they will not work.- Set
modebefore writing the logic. A real-time workflow must not contain persistence points, so the generated XAML differs by mode. Switching a workflow to real-time after writing leaves stalePersistelements behind; write the logic again afterwards. - Activation errors say nothing useful.
0x80040216is literally "an unexpected error occurred", and0x80048455names the composite but not the reason. Do not guess: callworkflow_diagnose_activationwith the same definition — it writes subsets into throwaway workflows until the culprit step (and case) is isolated, then deletes them again. - On a workflow you did not author, start with
dryRun=true.workflow_set_definitionthen validates and reports indiffwhat would change — including a warning if the current logic contains constructs that would be dropped. - Environment write policy:
contoso-devis the safe write target. Confirm with the user before writing tocontoso-prod(production).
Choosing between classic workflow and cloud flow
Classic workflows are legacy but still the right tool when: the logic must run synchronously
inside the transaction (real-time, pre-operation), it must prevent an operation by throwing, or
it calls an existing custom code activity. For anything else prefer a cloud flow — see the
cloud-flows skill.
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
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.

