Document Classes and Governance
Introduction
Some documents cannot simply "be edited and saved." An operating procedure, a contract, an engineering drawing, a regulatory report — these move through predefined states for approval, the project's users have defined roles (who drafts, who reviews, who approves), and they require a trail of who did what and when. On top of that, a document under preparation often cannot be seen by someone who should only learn about it after it is approved.
Document Classes are Sutram's layer of formal governance. They turn a record category into a governed flow: a lifecycle with states, roles, controlled transitions, visibility controlled by per-state permissions, and an audit trail. It is the step beyond simple file versioning (draft → published), for when the process itself must be guaranteed.
When to use formal governance
Consider a Document Class when preparing and consuming the content requires:
- Staged approval — draft → review → approve (or more elaborate flows)
- Roles per stage — different people (project users) acting at different moments
- Confidentiality by stage — who can see the document depends on the state it is in within its lifecycle at that moment
- Audit trail — a formal record of each state change, with author and justification
For lighter control — tracking revisions of a file without a formal approval flow — file versioning (draft/published) already does the job. See File Versioning System.
Plan requirement: Document Classes are a Max plan feature.
Key Concepts
Document Class
A Document Class is born from a record category "graduated" into a governed flow. Beyond the metadata fields that every category has, it gains a configurable lifecycle. The default preset for the class roles is author → reviewer → approver, fully adjustable afterward.
Lifecycle
The lifecycle defines how a document moves and who can act. It is made up of:
- States — the stages of the flow (e.g., In preparation → In review → Approved). Normally one state is the initial one (but there can be more than one); some may be terminal.
- Roles — the class roles (e.g., author, reviewer, approver), distinct from the project roles. Once the class roles are defined, the admin can assign one of them to each user. If a user has no role assigned in a given class, it is as if the class did not exist for them (need-to-know).
- Transitions (actions) — the moves allowed between states (e.g., "submit," "approve," "reject"), each with the roles that can trigger it; some transitions require a justification (note). A transition may also optionally require the document to be "ready": that all its files have a published version and/or that there is no open comment.
- Role × state matrix — for each state, who can read and who can write. A missing (state, role) pair means no access.
Governed document
A governed document is an entry that belongs to a Class. It exists as a family with one or more versions (revisions), and each version is always in a state of the lifecycle. Versioned classes (versioning of a class is optional) have a version axis (e.g., rev A, B, C); new revisions are born in an entry state.
Need-to-know visibility
The per-state permissions matrix implements confidentiality by stage: a document is only visible to someone who has at least read access in the current state. In practice, a document under preparation can be invisible to those who should only see it after approval. This also applies to navigation — the Governed Content space shows each person only the classes and documents they can see.
Audit trail
Every transition is recorded: which action, who triggered it, when, and with what justification. It is the formal history that governance requires.
From simple versioning to the governed cycle
Governance and file versioning are two points on the same spectrum — that of "state → transition → audit":
| File versioning | Document Classes | |
|---|---|---|
| Applies to | Any file | Records of a graduated category |
| States | Draft, Published (fixed) | Custom (e.g., In preparation → In review → Approved) |
| How it advances | Checkout/checkin and publish | Named transitions, with roles and note |
| Visibility | Everyone who accesses the file | Need-to-know: by state and role |
| Audit | Version history | Record of each transition |
| Plan | All | Max |
Start with draft/published for simple control; migrate to Document Classes when the process requires formal approvals, dedicated roles, and confidentiality by stage.
Note that the two processes can coexist. For example, a document under preparation can have a file edited and commented on by more than one authorized user. Only when a version of the file is published can the document that contains it advance in its class lifecycle — provided the transition is configured to require a published version.
Roles and Permissions
There are two levels of permission in governance:
- Configuring governance (graduating a category, editing the lifecycle) — restricted to owner and admin, on the Max plan.
- Operating the documents (creating, reading, triggering transitions) — controlled by the role × state matrix defined in each Class. That is, who can approve, reject, or only read depends on the person's role in that class and the current state of the document — not just on the project role.
The visibility of classes is also need-to-know: owner and admin see all of them; members and viewers see only the classes where they have a role.
Frequently Asked Questions
Q: What is the difference between publishing a file version and a Document Class?
A: Publishing a version of a file creates a snapshot within the simple draft → published cycle. A Document Class adds a governed approval flow — multiple states, roles per stage, need-to-know visibility, and an audit trail — for structured records.
Q: Do I need the Max plan?
A: Yes. Graduating categories and configuring lifecycles are Max plan features. Without it, the Document Classes page is visible, but graduation is blocked (with an upgrade notice).
Q: Are class roles the same as project roles?
A: No. Project roles (owner, admin, member, viewer) govern overall access. Class roles (e.g., author, reviewer, approver) are specific to the governed flow and determine who can act in each state.
Q: Can a document under preparation be hidden from part of the team?
A: Yes — that is the purpose of need-to-know visibility. The role × state matrix defines, per state, who reads and who writes; anyone without access in that state simply does not see the document.
Document Version: 1.0 Last Updated: July 2026 Author: Sutram Development Team