Document Management¶

Use document management to build collections of business documents with structured profiles, controlled access, and separate versions. A document can be created by a user or produced by a workflow; its record remains distinct from the process instance that created it.

The Document Model¶

Concept	Purpose	Contract example
Document	The business record identified across its revisions.	Sample contract.
Version	A particular revision with its own record ID, files, and creation details.	Versions `1.0.0` and `1.0.1`.
File	An attachment containing the document content or supporting material.	`contract.txt` and `schedule.txt` in the examples.
Standard metadata	Built-in information that identifies a version.	Title, description, version number, creator, and creation date.
Content type	Associates a profile form and its data model with the document.	`Contract`, backed by the `ContractProfile` form template.
Profile	Structured business data entered through that content type's form.	Contract number `EXAMPLE-001` and effective date `2026-01-01`.
Folder	A place to find the published document family.	`Documentation` → `Contracts`.
Document ACL	Access rules for the document, independent of its folder placement.	The `Contract Access` security profile includes reader and editor groups.

A file upload alone is not a document record. The record connects files to metadata, versions, and access rules. A content type adds the document's profile form; without one, the document has standard metadata and files but no associated profile form. A security profile supplies access rules and is separate from a content type.

A document archive is also separate from process-definition Documents, which embed HTML content in a process definition.

Build a Contract Collection¶

The guides use a fictional Sample contract to show the same feature from each audience's perspective:

The developer defines a ContractProfile form template and publishes the Contract content type from its source process definition. The profile contains Number and EffectiveDate.
The administrator prepares the Documentation → Contracts document folder and the Contract Access security profile, with appropriate rules for contract readers and editors.
The user creates Sample contract, selects Contract, enters EXAMPLE-001 and 2026-01-01, and attaches the contract and schedule files. Saving from the document screen publishes the record.
When the contract content changes, the editor creates a new version. The previous published version remains available in History. Updating a profile value alone is a metadata change, not automatic version creation.

See Content Types and Profiles for the developer setup, the administrator example for access configuration, and the user example for the daily procedure. These are example names and values, not built-in types or folders.

Choose an Implementation Path¶

Content Types and Profiles: design a profile, publish its content type, and bind data.
Document Lifecycle, Files, and Profiles: persistence, publication, file ownership, and versions.
Create and Publish Documents: server-side contract examples using the same profile and collection.
Generate a new PDF version from workflow data: a separate workflow tutorial.
Document API and $Documents: generated method and property reference.

Server-Side Automation¶

Use $Documents in server-side scripts to create and retrieve document records. The returned Document exposes files, profile data, security, and lifecycle operations. These are server automation APIs, not browser form globals. Review the authorization rules below before using them with user-supplied targets.

Identity Model¶

Value	Identifies	Use
`Document.Id`	One version record	`$Documents.Get(id)` and links to a specific revision.
`Document.BranchId`	The document family across versions	`$Documents.NewVersion(branchId)` and `$Documents.GetLastVersion(branchId)`.
`Document.Version`	Version number within that family	A `Major.Minor.Revision` string, initially `1.0.0`.
`FileInfo.Id`	One file record	File operations; it is neither a document ID nor a branch ID.
Folder ID	One folder	`$Documents.ListDocuments(folderId)`, which expects a GUID.
Folder path	Named folder hierarchy	`Document.Publish('Documentation\\Contracts')`, using escaped backslashes in JavaScript.

NewVersion creates a fresh version ID and keeps the branch ID. Without an explicit version number, it increments the revision component of the highest existing version. A number already present in the family is rejected. If no version exists for a branch ID, NewVersion creates a first version for that branch; validate that an existing target really exists when your operation is intended only to revise it.

Retrieval and Published Lists¶

Get accepts a version GUID and returns null for a missing record; malformed GUIDs raise a script error. It does not resolve a branch ID as a substitute for a version ID.

GetLastVersion accepts a branch GUID and selects the highest version number across states, including drafts, archived, and deleted versions. It does not mean "latest published version." Folder lists select the highest published version per family and apply document ACL filtering when a user identity is used.

ListDocuments returns a DataTable containing Id, Title, ContentType, CreateDate, CreatedBy, State, and Version. Use the returned version Id with Get to read its BranchId. It is not a recursive traversal of child folders.

Execution Context and Authorization¶

$Documents runs as trusted server automation within the current domain. Even when invoked from a user workflow, its normal retrieval and mutation operations do not apply that user's document ACL. Cross-tenant document targets are rejected. Tenant isolation is not authorization for every record within the tenant.

ListDocuments(folderId, identity) is the explicit exception for listing: it builds a user execution context for that identity and filters returned rows. Omitting identity uses the trusted script context. Passing an identity does not change the security context of later Get, NewVersion, or document mutations.

Before exposing a script through a user action, validate the requested operation and allowed document family using the application's server-side authorization policy. Do not accept an arbitrary document ID merely because it belongs to the current tenant. Browser visibility rules and $Documents.Get are not substitutes for this authorization.

Set the intended document security profile before publication and test resulting UI access using allowed and denied accounts. See administrator access rules.