Skip to content

Create a New Document Version from Workflow Data

Goal

Generate a PDF from validated workflow data and store it as a new version of an existing document.

What You Will Learn

  • create a document version with $Documents.NewVersion
  • add generated PDF content to that version
  • preserve the stable document identity across revisions

Difficulty and Estimated Time

  • Difficulty: Advanced
  • Estimated time: 25 minutes

Assumed Knowledge

You should understand document archives, file identifiers, postwork scripts, HTML, and XML formatting.

Required Reading

Prerequisites

  • a test document archive and permission to create versions
  • an existing test document ID stored in DocumentId

Example Overview

The form collects a document ID, title, and safe body text. Postwork opens a new version and adds one generated PDF.

Steps

Keep the Stable Document ID

Store the target document's ID in DocumentId. A version receives a new version record, but it remains attached to the same stable document identity.

Create the Version in Postwork

1
2
3
4
var title = $Xml.Evaluate('Title');
var document = $Documents.NewVersion($Xml.Evaluate('DocumentId'), title);
var body = $Xml.Format('<h1>{{Title}}</h1><p>{{Body}}</p>');
document.Files.AddPDF(body, 'generated-document.pdf');

Use a fixed, reviewed template and validate its substituted values before rendering. Keep the returned document/version operation and file creation in one controlled server-side step.

Copy Before Modifying an Uploaded File

When a source upload must remain unchanged, copy it first and store the returned file ID in process data:

1
2
3
4
5
6
var workingCopy = $Files.Copy($Xml.Evaluate('SourceFileId'));
$Xml.SetValue('WorkingFileId', workingCopy.Id);

var input = $Files.GetBase64(workingCopy.Id);
var output = transformWithAReviewedModule(input);
$Files.SetBase64(workingCopy.Id, output);

transformWithAReviewedModule represents a tested script-module function appropriate to the file type; it is not a platform global. Validate the file type and size before loading content, and keep format-specific logic out of task orchestration.

If downstream records already reference a file ID and the requirement is to replace that file's content in place, call $Files.SetBase64(existingFileId, output) with the same authorised ID. This preserves the reference, but it also changes what every holder of that ID reads. Use a copy and update only the intended reference when previous content must remain available.

How It Works

NewVersion targets the existing document identity and creates a new revision. AddPDF renders the supplied HTML and attaches the result to that revision. The previous version remains available according to archive policy.

Verify the Result

  1. Import the definition and enter an accessible test document ID.
  2. Submit a title and body.
  3. Confirm that the document now has one additional version and one PDF file.
  4. Confirm that the previous version is unchanged and a user without archive permission is denied.

Failure and Edge Cases

  • Test a missing or inaccessible document ID and confirm that no orphan file or partial version remains.
  • Retry after an uncertain failure and confirm that the workflow does not create duplicate versions.
  • Test markup-like input and confirm that the validation or sanitization policy handles it as intended.
  • Modify a working copy and confirm that the original upload is unchanged; separately verify that an in-place update preserves the file ID.

Security and Portability Notes

  • Resolve and authorize the document in the current tenant before creating a version.
  • Validate or sanitize untrusted text before PDF rendering and do not load tenant-specific remote assets.
  • Add an idempotency marker before production use when postwork may be retried.
  • Authorize both the source and target file IDs, validate size and MIME type, and never transform arbitrary content with a format-specific writer.

Download and Try It Yourself

Download the document-version definition.

Troubleshooting

  • Document not found: Confirm the ID belongs to an accessible document in the current domain.
  • Duplicate versions: Persist a completion marker and check it before retrying the operation.
  • Unsafe or broken markup: Confirm all substituted values follow the template's validation and sanitization policy.
  • Original upload changed unexpectedly: Confirm the transform targets the ID returned by $Files.Copy, not the source ID.

What to Learn Next