Create a New Document Version from Workflow Data¶

Goal¶

Generate a PDF from plain-text workflow fields and publish it as a new version of an existing document, retaining the previous version and its files.

What You Will Learn¶

resolve a version ID to its stable document family ID;
create a draft with independent copies of the source files;
encode text when generating PDF markup and publish the resulting revision;
record the result and understand the limits of a retry marker.

Difficulty and Estimated Time¶

Difficulty: Advanced
Estimated time: 20 minutes

Assumed Knowledge¶

Understand server-side postwork scripts, process XML, document folders, and the document identity and authorization model.

Required Reading¶

Prerequisites¶

An isolated test domain with PDF generation configured and permission to import/run the example process.
A published test document in a document folder; record one version's Id, not its BranchId.
An approved authorization policy restricting who can run this workflow and which document families it may revise. $Documents does not enforce the invoking user's document ACL.
A known test reader and a denied reader for verifying the document's copied ACL.

Example Overview¶

The definition contains one pool, one initiating task, and one form. The form accepts DocumentId, Title, and plain-text Body, and stores ResultVersionId. The initial task uses the initiating user without an external role dependency. It requires an existing test document and the host PDF-generation services; it does not bundle those dependencies.

The source ID selects a particular record. NewVersion then copies the highest existing version in its family, which may differ from that record if the family already has newer revisions. Prepare the fixture accordingly.

Steps¶

Import and Configure the Test Process¶

Download and import the definition below into the test domain.
Restrict process initiation to the intended test operators. Do not expose unrestricted document IDs in a production workflow; add the application's server-side target authorization before doing so.
Publish the process, start Create Version, and enter the existing document version ID, a title, and plain-text body.

Create and Publish the Version in Postwork¶

The downloadable definition uses this script:

var source = $Documents.Get($Xml.Evaluate('DocumentId'));
if (!source) {
    throw new Error('The source document was not found.');
}
if ($Xml.IsEmpty('ResultVersionId')) {
    var document = $Documents.NewVersion(source.BranchId, $Xml.Evaluate('Title'));
    var writer = $Xml.Create();
    writer.StartElement('div');
    writer.Element('h1', $Xml.Evaluate('Title'));
    writer.Element('p', $Xml.Evaluate('Body'));
    writer.EndElement();
    document.Files.AddPDF(writer.ToXml(), 'generated-document.pdf');
    document.Publish();
    $Xml.SetValue('ResultVersionId', document.Id);
}

Get resolves the supplied version ID and returns null for a missing record. Passing source.BranchId to NewVersion keeps the new record in the same family. Files from the latest version are copied; AddPDF appends one additional file. This example deliberately retains all copied attachments, including any earlier generated PDF. For replacement behavior, remove only the superseded copy from the new draft before adding its replacement.

XmlWriter.Element encodes each text value, so < and & in the title or body remain text rather than becoming markup. The fixed structure has no remote resources or user-provided HTML. Publish() persists the revision and reuses the family's existing folder associations. Save() alone would leave it Draft and absent from published folder lists.

Copy Before Modifying an Uploaded File¶

For general upload transformations, use an independent working copy when the source must remain unchanged. Review Files and Independent Copies before mixing general file operations with version-owned files.

Record and Reconcile the Outcome¶

The script records the resulting version ID in ResultVersionId and skips creation when that field is populated. Treat the field as server-owned workflow output. It is not a complete concurrency or crash-recovery solution: if publication commits but the workflow field does not, a retry can still create another revision.

Before production use, make the operation marker and document result part of a controlled transactional or serialized operation. After an uncertain outcome, reconcile the published version before retrying. Do not clear the marker merely to make an error disappear.

Verify the Result¶

Note the source family's version numbers and file count before running the task.
Submit the form once. Confirm the folder lists the new published version and History includes the previous one.
Open the new version. Confirm its copied files plus one new generated-document.pdf are present.
Open the PDF and verify the title/body. Repeat on a fresh fixture with text such as A < B & C; it should appear as text.
Open the earlier version and verify its files are unchanged.
Check that the intended reader can open the result and the denied reader cannot. This tests the resulting ACL, not script-level user authorization.
Inspect the workflow data and confirm ResultVersionId matches the new version's Id. Test the populated-marker branch in a controlled script run and confirm it creates no additional revision.

Failure and Edge Cases¶

Invalid or missing version ID: malformed GUIDs raise a script error; a missing valid ID is rejected by the null check.
Concurrent version creation: a version number may conflict; reconcile the family before retrying.
PDF-generation failure: inspect workflow errors and any created files before retrying; do not assume that file creation and workflow completion always share the same rollback boundary.
No folder entry: confirm the family had a folder association and the new revision is Published.

Security and Portability Notes¶

Use disposable test documents and generic data. Authorize the target on the server; hiding a form field or relying on folder visibility is insufficient. Keep HTML structure fixed, use encoded text, and avoid tenant-specific remote assets. The copied ACL should be reviewed before publication if the revised content has a different audience.

Download and Try It Yourself¶

Download the document-version definition.

Troubleshooting¶

If the workflow fails, collect its error and source/result version IDs. Review the document family and workflow marker before resubmission. If the folder shows an unexpected version, compare published versions with the highest version returned by GetLastVersion; these are different selections.