Document Governance for Audit-Ready Workflows: SharePoint + Dataverse Linking (Version-Proof Evidence)

Author: Forrest Zhang

Implementation Track: Post C (Audit-Ready Modernization)

Related series:
• Framework 1: Audit-Ready by Design
• Framework 2: RBAC That Scales (Role × Scope × Authority)
• Framework 3: From One-Off to Repeatable Platforms

Implementation Track:
• Post A: Controlled Transitions (Custom API + Guard Plugin)
• Post B: Workflow Event Log (what to capture) 
• Post C (this post): Document Governance (SharePoint + evidence versioning) – [add link]
• Post D: Audit-ready operational reporting

Why “document governance” matters more than “document storage”

In regulated workflows, documents are not just attachments. They are evidence. The audit question is rarely “do you have a file?” It is:

  • Which document was used to make the decision?
  • Which version of that document was used at that moment?
  • Who had access to it, and was that access appropriate?
  • How do we prove integrity (no silent changes after the decision)?

This post explains a practical, repeatable pattern using:

  • SharePoint for document storage, versioning, retention, and access management
  • Dataverse for workflow records, governance logic, and audit-ready event logging
  • Linking rules that make evidence “version-proof” (so your audit story doesn’t collapse later)

The two golden rules

Rule 1: Store documents in SharePoint, not in your event log

Dataverse can store files, and there are cases where that is fine. But in most regulated business systems, SharePoint is the better place for:

  • Version history
  • Retention policies
  • Information protection / sensitivity labels (if used)
  • Document collaboration and previews
  • Scalable storage and governance

Rule 2: For decisions, always store a reference to the exact version used

Linking to “the file” is not enough. The file can be updated. You need an evidence reference that answers: “Which version did you use?”

The simplest defensible reference is:

  • SharePoint file identifier (or URL)
  • version label (e.g., 3.0, 7.0)
  • file name (human readability)
  • optional: last modified timestamp and modified by (helps explain changes)

Recommended architecture (what goes where)

Dataverse (governance + workflow)              SharePoint (documents + versions)
---------------------------------              --------------------------------
Case / Application / Request record  <----->   Case folder + evidence files
Workflow Event Log (decision ledger)          Version history + retention
Document Reference table (optional)           Permissions groups

Key idea: Dataverse records drive the process. SharePoint stores evidence. The Workflow Event Log ties a decision to evidence pointers (including version).

Step 1 — Define your document taxonomy (keep it simple)

A taxonomy is just a controlled way of classifying documents so people (and auditors) can find them.

Start with 6–10 document types max:

  • ID Verification
  • Contract / Agreement
  • Invoice / Receipt
  • Supporting Evidence
  • Approval Memo / Decision Note
  • External System Export (if applicable)

Why not create 30 types? Because people will pick the wrong one, and your reports become useless. You can always refine later.

Step 2 — Decide the SharePoint folder strategy

You need a predictable folder structure so your system can link documents consistently.

Recommended folder pattern:

/Shared Documents/
  /Cases/
    /CASE-000123 - [Case Name]/
      /Evidence/
      /Decisions/
      /Exports/

Why this works:

  • Easy for humans to navigate
  • Easy for automation to find
  • Supports separate permission patterns if needed (e.g., Exports)

If you have multi-tenant boundaries (e.g., different programs/clients), include a tenant or program folder above Cases:

/Shared Documents/
  /Program-A/
    /Cases/
  /Program-B/
    /Cases/

Step 3 — The “Document Reference” record (optional but powerful)

You can link documents to Dataverse in two ways:

  • Lightweight approach: only store evidence references inside the Workflow Event Log (JSON references)
  • Structured approach: create a “Document Reference” table in Dataverse

If you want stronger governance and reporting, use a structured table. Example: new_documentreference with:

  • new_targetlogicalname + new_targetid (or a lookup to Case)
  • new_documenttype (Choice: ID, Invoice, Contract, etc.)
  • new_sharepointfileurl (Text)
  • new_sharepointuniqueid (Text) – if you capture it (best)
  • new_currentversionlabel (Text)
  • new_filename (Text)
  • new_status (Choice) – Draft / Final / Superseded
  • new_uploadedby (Lookup)
  • new_uploadedon (DateTime)

How this table is used:

  • The Case page can show all evidence documents (by type)
  • The Workflow Event Log can reference the Document Reference record (stable pointer)
  • You can enforce prerequisites: “Approved requires ID Verification + Contract (Final)”

Step 4 — How to capture the SharePoint version used as evidence

This is the core audit-ready requirement. Here are three practical options, from simplest to strongest.

Option A (Simplest): Store file URL + version label at decision time

When a critical transition happens (e.g., Submitted → Approved), your transition handler gathers evidence references and stores them in the Workflow Event Log:

  • file URL
  • file name
  • version label

How to get version label? Typically via SharePoint APIs / connector calls from your transition service layer. The key is: store the version label at the moment of decision.

Pros: easy, good enough for many audits.
Cons: relies on URL stability and correct retrieval of version label.

Option B (Better): Store SharePoint UniqueId + version label

SharePoint files have stable identifiers. Storing UniqueId + version label makes your evidence reference more robust than URL alone (URLs can change if files are moved).

Pros: more stable, better for long-term governance.
Cons: requires you to capture UniqueId reliably.

Option C (Strongest, for high-stakes): Store version label + immutable artifact reference

For the highest stakes, you can “lock” evidence by producing an immutable artifact at decision time (e.g., a stamped PDF copy, hash, or archived version) and store a reference to that artifact.

This is heavier and usually only needed for extreme compliance settings.

Step 5 — How to prevent “silent evidence changes” after approval

Auditors sometimes ask: “Could someone change the document after approval and make the decision look justified?”

You can address this with a combination of controls:

Control 1: Separate “Draft” vs “Final” evidence types

Allow edits to drafts, but require final evidence for approval. Example:

  • ID Verification (Final)
  • Contract (Final)

Approval transition enforces: required documents must be in Final state.

Control 2: Permission tightening after approval

When a Case is approved/closed, reduce who can modify evidence folders. This can be done by:

  • SharePoint groups per case/program, or
  • Folder-level permission rules for high-risk folders (Decisions/Exports), or
  • Standard approach: allow additions, restrict edits/deletes for non-admin roles

Important: be careful with per-folder unique permissions at large scale—too many unique permissions can become hard to manage. Prefer group-based models.

Control 3: Make decisions reference versions, not “latest”

Even if evidence changes later, your event log still points to the version used. That is often the most defensible approach.

Step 6 — Permission model: tie documents to RBAC and scope

Document governance should follow the same access boundaries as your Dataverse records.

Practical principle: If a user cannot access a Case record, they should not access the Case’s evidence folder.

How to implement (high-level options):

  • Program/site-based separation: separate SharePoint sites by program/tenant and align groups to Dataverse teams
  • Library-level separation: separate libraries for different sensitivity (Evidence vs Exports)
  • Folder-based separation (use carefully): for special cases only

Start with the simplest model that fits your risk profile. Over-engineering permissions early often creates operational pain.

Step 7 — How to link documents into your Workflow Event Log

If you followed Implementation Post B, your event log supports an evidence JSON field (or references to Document Reference records).

At decision time (Custom API transition), your handler should:

  1. Identify which documents are required for this transition
  2. Retrieve the current evidence set (Document Reference records, or SharePoint folder listing)
  3. Validate prerequisites (presence + state + type)
  4. Build an evidence reference list that includes version label
  5. Write it into the Workflow Event record

Example evidence JSON stored in the Workflow Event Log:

[
  {
    "type": "SharePointDocument",
    "docType": "Contract",
    "fileName": "ServiceAgreement.pdf",
    "fileUniqueId": "c9b8e2c2-....",
    "fileUrl": "/Shared Documents/Cases/CASE-000123/Evidence/ServiceAgreement.pdf",
    "versionLabel": "4.0",
    "capturedOn": "2026-02-04T18:15:10Z"
  },
  {
    "type": "SharePointDocument",
    "docType": "IDVerification",
    "fileName": "ID-Scan.jpg",
    "fileUniqueId": "b2b912a1-....",
    "fileUrl": "/Shared Documents/Cases/CASE-000123/Evidence/ID-Scan.jpg",
    "versionLabel": "2.0",
    "capturedOn": "2026-02-04T18:15:10Z"
  }
]

Step 8 — Predictable audit reports you can build from this model

Once documents are governed and linked to decision events, you can answer common audit questions quickly:

  • “Show evidence used for all approvals in January”
    Filter events where eventtype=StatusTransition and toStatus=Approved, then show evidence JSON.
  • “Which cases were approved without required documents?”
    Your transition handler should block these, but if you’re in a phase-in stage, report on missing document types.
  • “Which version of the contract was used?”
    Read versionLabel from evidence references.
  • “Who changed the document after approval?”
    Use SharePoint version history; your event log shows the baseline version used at approval.

Practical rollout plan (avoid breaking current operations)

Document governance can be rolled out in phases, similar to the transition control pattern:

  1. Phase 1: Standardize folder structure + document type taxonomy
  2. Phase 2: Start capturing evidence references (URL + version) into Workflow Event Log for approvals
  3. Phase 3: Enforce prerequisites for approvals (block approval if required evidence missing)
  4. Phase 4: Tighten permissions post-approval for high-risk folders

This approach improves governance step-by-step without forcing a big-bang change.

Closing

Audit-ready document governance is not about storing more files. It’s about being able to prove—later and quickly—exactly what evidence supported a decision, which version of that evidence was used at the time, and who had appropriate access throughout the process.

The most important mindset shift is this: don’t treat documents as “attachments.” Treat them as decision evidence. That means your system should make it easy to answer:

  • Which evidence was used for this approval/closure?
  • Which exact SharePoint version was referenced?
  • Were required document types present and in the right state (Draft vs Final)?
  • Did access boundaries remain consistent with the case RBAC scope?

When you combine:

  • Post A: controlled transitions (Custom API + guard plugin)
  • Post B: a consistent workflow event log (who/what/when/why + evidence pointers)
  • Post C: version-proof evidence linking (SharePoint URLs/IDs + version labels)

…you end up with a governance foundation that is practical to operate, repeatable across deployments, and much easier to defend during audits—because the “decision story” is built into the data model, not reconstructed after the fact.

Optional next step: Post D covers audit-ready operational reporting—the exact views, exception lists, and KPIs that answer predictable audit questions before anyone asks (approvals register, overrides/reopens, prerequisite compliance, export monitoring, and more).

at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)