Document Lifecycle, Files, and Profiles¶
Use this reference when deciding whether to save metadata, create a new revision, or remove a version. All operations below refer to the server script API; the standard document UI's Save path publishes the form's document.
States and Persistence¶
| Operation | Persistence and visibility |
|---|---|
$Documents.New(title, contentType) | Returns a new Draft object with new version and branch IDs; call Save or Publish to persist the record. |
$Documents.NewVersion(branchId, title, versionNumber) | Returns a new Draft with copied metadata, ACL, profile, and independent file copies; call Save or Publish to persist it. |
Save() | Persists changes without changing state or adding folder membership. Saving a new draft alone does not make a folder entry. |
Publish(folderPath) | Saves as Published and adds branch associations to the specified folders. Missing named folders are created. |
Publish() | Saves as Published without adding folder associations; existing family associations remain. |
Unpublish(folderPath) | Saves this version as Draft and removes the named folder associations from the family. Missing paths are ignored. |
Unpublish() | Saves this version as Draft and removes all family folder associations. |
Archive() | Saves this version as Archived, retaining data but excluding it from published lists. |
Delete() | Marks this version Deleted and removes its search entry; retains profile and attached files. Repeated calls preserve the deleted version. |
Purge() | Permanently removes this version and its attached file records, in any state; repeating removal of an absent version has no effect. |
Delete and Purge do not remove sibling versions. Neither provides a user-facing undo or a guarantee of physical erasure from external repositories and backups. See operations and recovery.
Read-Only Content and Editable Metadata¶
IsReadonly is true for Published, Archived, and Deleted versions. In those states, file-content mutation, content-type changes, version-number changes, and creator changes are prohibited. Title, description, profile data, and ACL can still be updated through the script API and persisted with Save(). Saving such metadata does not create a new version or change its current state.
For a content revision, use NewVersion instead of unpublishing the previous record merely to edit its files. The previous published revision can remain available while the new draft is prepared. History lists published versions only.
Files and Independent Copies¶
Document.Files is scoped to one version. A new version copies each source file into a separate file record; editing or deleting that copy does not alter the source version's file. Adding a generated PDF appends another file, so review whether you intend to retain all copied attachments.
Use doc.Files.AddPDF, AddString, or the other Files methods supported for document files. Use file IDs belonging to the target version for operations such as Delete, SetBase64, and Replace. Another version's owned file cannot be attached, consumed as a replacement, or mutated through the target version's collection. Cross-tenant files are rejected.
$Files is the general file API. A file ID stored in process XML is a reference, not ownership of the document. Changing content through a general file operation can affect all readers of that file ID; prefer an independent copy when the source must remain unchanged. Do not use the general API to bypass a document's read-only content rules. Keep file creation and document persistence in a controlled server operation and account for failures; creating a file is not proof that its document was saved or published.
Content Types and Profiles¶
See Content Types and Profiles for form design, publication, and the Contract example.
A published content type attaches a profile form and its data model to a document. The profile is the document-specific structured information defined by that content type, such as a contract number and effective date. Title and description are standard document metadata, separate from the content-type profile.
To give a document a profile, set ContentType when creating the draft, before supplying profile data or publishing. AddProfile copies input XML according to that content type's schema. Use the expected element names, namespaces, and types; arbitrary XML is not a substitute for associating a content type. A document without a content type has no content-type profile form to fill in.
Profile exposes the associated profile data through an XML wrapper and can be null when no profile data exists. Use Save() after changing profile data on an existing version. A profile update can change business information on a published version without replacing the file or creating a new version.
SetSecurityProfile(name) selects a domain security profile by name or ID and updates ACL inheritance. It is independent of ContentType. Save or Publish afterward to persist the change. An empty name clears that inheritance; it does not mean "restore safe defaults." Review explicit ACL entries and resulting reader access.
Folder Membership¶
Publish('Documentation\\Contracts;Documentation\\Reference') accepts one string with semicolon-separated paths, not an array or folder GUID. Backslashes in JavaScript string literals must be escaped. Folder membership is stored for the branch, so unpublishing from one path affects the family's placement there, even when sibling versions are still published.
Publishing and ACL assignment are separate. Adding a folder association does not grant document Read to everyone who can browse that folder. Before using an automatically created path, agree its name and resulting folder ACL with the administrator.
Failure and Retry Handling¶
Document version creation is not inherently idempotent. A retry can create another version and another set of files. For workflow automation, keep a durable operation marker and resulting version ID with the business request. Check it before creating a version, and reconcile the stored result after an uncertain outcome. Use a transaction or an equivalent serialized operation so concurrent retries cannot both pass the check. A field assignment after Publish alone does not prove atomicity across independent persistence systems.
For an authorized existing revision, resolve its version ID with Get, check for null, then use its BranchId with NewVersion. Treat an unknown branch as an error in your application rather than silently starting another family.