Note that the Snapshots feature described below is in development and not yet released for customer use.
Background
Confluence pages are dynamically rendered when viewed. When pages are used as controlled documents in eSign Document Management (eDoc), the page contents and attachments are locked down for review, approval and document release. This prevents the stored content of the page from being changed, and the users will only be able to view the document that was approved.
Confluence pages may contain dynamic content macros. These macros may insert information from outside the current page. Examples include:
Include Page Macro - Includes content from another Confluence page
Jira Macro - Includes current content from Jira
iframe Macro - Includes content from an external web site into the page
If these macros are used in the Confluence pages that need to be controlled documents, Confluence will always display the latest information from these dynamic macros. Rendering new or different information to the users is generally not acceptable for controlled documents from a compliance perspective.
In this scenario, locking down the Confluence page content itself does not prevent the users from seeing new or imported content.
Approaches
There are two general approaches to resolve this challenge
Avoid including dynamic content macros within controlled documents
Use eSign Document Snapshots
The remainder of this how to provides a walkthrough of eSign Document Snapshots.
Snapshot Overview
Snapshots provide an option to embed a static point-in-time revision of a document for review, approval and release. With a Snapshot, the output of dynamic content macros is frozen prior to document approval, meaning that the document when viewed by users will not change, even if it contains external content.
Technically the Snapshot is a PDF copy of the page. The eDoc app manages the Snapshots during the Review, Approval and Release process. Snapshots are displayed within an embedded Adobe PDF rendering frame that provides a virtually identical reading experience to a standard Confluence page.
Snapshot Workflow
Step 1 - Enable Snapshots
Snapshots can be enabled on any open Working Copy. Ensure the page has the eSign Document Header macro.
Step 2 - Generate Snapshot
When the draft page is ready for review, Use the Confluence - Export to PDF function to generate a PDF export of the draft Working Copy.
Download the resulting PDF file from Confluence and then upload it into eSign Documents (Draft tab).
When complete, close and refresh the page to see the Active Snapshot embedded in the Working Copy. The Working Copy will show both the snapshot content AND the original content, separate by blue lines. On Release, only the Snapshot is published to the Release Copy.
When Snapshot mode is enabled, the eSign Document Header will be hidden during PDF export. The eSign Header will be visible in the released document to reflect current status of the document at all times.
TIP - TODO - minimize page margins
Step 3 - Document Review and Approval
Proceed with standard eDoc review and approval. Note that the reviewers should focus on the snapshot content within the blue lines as that is what will be approved and published.
Edit the confluence page content as required, generate and upload new snapshots as necessary.
As the snapshots are stored as attachments within the working copy, replacement snapshots will show as a document modification and require re-approval.
Step 4 - Document Release
After approval, proceed with the standard release workflow. With Snapshot mode enabled, eDoc will perform some additional work to the release copy. Visually only the Snapshot content will be displayed.
Released Documents will contain the standard eDoc header and the immutable embedded snapshot content.
