agentleFS
hydrhydr/dataverse-modelling-mcp/skills/classic-workflows/SKILL.md

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.

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
  1. Distinctive:

    Read the tail of the report.

    line 58
  2. Very specific:

    If fullyUnderstood is false, stop and tell the user which parts are unsupported.

    line 73
  3. Very specific:

    Verify afterwards rather than assuming: read the definition back and diff it against what you meant to write (step ids are regenerated, so …

    line 97
  4. Very specific:

    When the branch does not run, the variable is Nothing, and the Add behind concat tolerates that — the same way an optional field read …

    line 382

≈ “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

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

IntentTool
What does this workflow do?workflow_explain
Get the logic as editable JSONworkflow_get_definition
Check a definition before writingworkflow_validate_definition
Write logicworkflow_set_definition
Create a new (empty) workflowworkflow_create
Triggers, mode, scope, subprocessworkflow_update
Activate / deactivateworkflow_set_state
Raw XAML for backup or diffingworkflow_export_xaml
Undo a changeworkflow_restore_xaml
Delete a workflow (and its activation copies)workflow_delete
Find out why a definition will not activateworkflow_diagnose_activation
Change the ownerworkflow_assign
Check an existing workflow (not a definition)workflow_validate
Available code activitiesworkflow_list_activities
Parameters of a code activityworkflow_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=true

If 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:

DirectionParameterOn
Definition indefinitionFileworkflow_set_definition, workflow_validate_definition, workflow_diagnose_activation
Previous XAML outbackupFileworkflow_set_definition
XAML back inxamlFileworkflow_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:

Intentworkflow_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

kindPurposeRequired fields
conditionIf/then/otherwise, or an if/else-if chainconditions + then, or branches; plus optional else
waitWait until a condition holds (background workflows only)like condition
stageGrouping. If one step is in a stage, all must bechildren
createRecordCreate a record of any tableentity, attributes
updateRecordUpdate the triggering recordattributes
assignRecordChange ownerownerId, optional ownerType
changeStatusSet statecode/statuscodestate and/or status
customActivityRun a code activityassemblyQualifiedName, optional inputs/outputs
startChildWorkflowStart another workflowchildWorkflowId
stopWorkflowEnd the workflowoptional outcome, reason
sendEmailCompose and send an e-mailattributes (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

GroupOperators
EqualityEqual, NotEqual
Emptiness (take no value)Null, NotNull
TextContains, DoesNotContain, BeginsWith, DoesNotBeginWith, EndsWith, DoesNotEndWith
NumbersGreaterThan, GreaterEqual, LessThan, LessEqual
SetsIn, NotIn — use literals for the values
RangesBetween, NotBetween
Dates, with a valueOn, OnOrAfter, OnOrBefore — often against {"kind":"now"}
Dates, without a valueToday, 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

kindMeaningExample
literalConstant{"kind":"literal","literal":"Active","dataType":"String"}
literal with literalsA set of constants, for In/NotIn{"kind":"literal","dataType":"OptionSetValue","literals":["1","2","3"]}
fieldOne or more fields, first non-empty wins, optional fallback{"kind":"field","fields":["lead.websiteurl","lead.emailaddress1"],"fallback":"unknown"}
stepOutputOutput of an earlier code activity{"kind":"stepOutput","stepOutput":"Domain"}
nowCurrent date and time, evaluated at run time{"kind":"now","dataType":"DateTime"}
concatSeveral 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 literal with no literal value. 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 in unrecognised, 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 fromKeyExample
A directly linked record (one level)via = the lookup attribute leading there{"fields":["opportunity.sample_salesrep"],"via":"opportunityid"}
A record an earlier createRecord step madefromStep = its step id or the created entity{"fields":["email.activityid"],"fromStep":"email"}
The record behind a code activity's outputfromStepOutput = 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:

  1. Model — completeness and consistency of the definition.
  2. 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).
  3. 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

CodeMeaning
WF000 / WF001definitionJson is not valid JSON, or the definition is null
WF002 / WF003primary entity or steps missing
WF010–WF012step kind missing, unknown, or not generatable
WF013 / WF014stage nested, or empty
WF015stage without a description (warning — stages are the outline in the designer)
WF020 / WF021create without entity; update targeting a different table
WF030–WF032assign step: owner missing or malformed
WF040change-status without state/status
WF050 / WF051child workflow id missing or malformed
WF060stop step with an unknown outcome (use "succeeded" or "cancelled")
WF070–WF076condition: no comparisons, missing attribute/operator/value, no branches
WF079comparison reads another table without via, fromStep or fromStepOutput
WF077 / WF078condition on a step output: no parameter named, or no earlier step declares it
WF080–WF084code activity: AssemblyQualifiedName missing/malformed, PublicKeyToken=null, empty parameter name
WF085–WF089code 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–WF092attribute assignments: none, unnamed, duplicated
WF100–WF102value missing, unknown kind, unknown data type
WF110–WF114literal null, ignored fields, null entry in literals, ignored fields on now, concat without parts
WF120–WF122field value: no fields, bad reference format, non-primary entity
WF130–WF132stepOutput: missing, malformed, or no matching earlier output
WF140branches and conditions used in the same condition step
WF200–WF202generated XAML failed self-check (internal defect — report it)
WF210workflow is activated; deactivate or pass reactivate=true
WF300 / WF301table 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.TargetType of 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_definition returns the previous XAML in backup, or writes it to backupFile if you give it a path — do give it one, both to keep the response readable and because workflow_restore_xaml can then take xamlFile and 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_delete takes them along; it refuses an activated workflow unless deactivateFirst=true.
  • Don't create workflows with record_upsert. A create without valid xaml is rejected with 0x80045040. workflow_create supplies a valid skeleton, so use it.
  • 0x80045040 on 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 from workflow_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.
  • updateRecord writes to the triggering record only. It uses a temporary entity internally and writes the result back.
  • wait steps require background mode (mode=0). In a real-time workflow they will not work.
  • Set mode before 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 stale Persist elements behind; write the logic again afterwards.
  • Activation errors say nothing useful. 0x80040216 is literally "an unexpected error occurred", and 0x80048455 names the composite but not the reason. Do not guess: call workflow_diagnose_activation with 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_definition then validates and reports in diff what would change — including a warning if the current logic contains constructs that would be dropped.
  • Environment write policy: contoso-dev is the safe write target. Confirm with the user before writing to contoso-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.

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.