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.

...

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

...

The remainder of this how to provides a walkthrough of eSign Document Snapshots.

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.

...

...

Image Added

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 linesAlternate export tools (e.g. Scroll PDF) can also be used.

...

Image Added

After the PDF is downloaded, use the “New Snapshot” link in the eSign Header to upload the Snapshot into eSign Document Management.

...

Once uploaded, eSign will display the new PDF snapshot inline at the top of the Working Copy. Note the original Confluence text will still be displayed at the bottom of the page. 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 marginsNote that the eSign Header data is included in the PDF to identify Document ID and Revision. In the example below the eSign Signature Block and History macro are being used. At this point there are no approvals yet.

...

Tip - The default confluence PDF export adds 1” margins around exported PDF files. The export margins can be changed to minimize extra whitespace for online viewing. See more in the Appendix below.

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.After all approvals have been completed, the page will be finalized to Approved.

At this point the Document Owner may do a final snapshot refresh to include the completed signature block and revision history.

...

Step 4 - Document Release

After approval, proceed with the standard release workflow. With Snapshot mode enabled, eDoc eSign 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.

...

On the released document, all persistent information (document type, ID and revision) is embedded in the PDF snapshot. This allows the document identification to be retained in the event the PDF file is downloaded/printed.

The online eSign Header continues to show dynamic info (e.g. Training is Due, Document is in Pre-Training, etc). The current status is always in the page byline.

...

The embedded Adobe PDF viewer has a download file option for users to take an offline copy of the PDF. Alternately, the PDF snapshot is stored as an attachment on the release copy so is available from the Page>Attachments page.

...

Appendix - Additional Resources

A. Document Control and Publishing for External PDF Documents

The Snapshot feature can also be used to route, review, approve and publish any external PDF file as a controlled document. This may be useful for teams whose document sources are in alternate formats and they do not want to convert or edit them in Confluence. If the source can be converted to PDF, it can be uploaded to eDoc as a Snapshot.

B. Tuning the PDF Export

Atlassian Confluence cloud has limited support for customizing the PDF page export. For example the default margins of the generated PDF can be reduced to have the snapshot PDF have less white space around it.

...

Apply custom PDF export configuration in Confluence Space Settings > Look and Feel > PDF Export > PDF Stylesheet for the space your working copies are stored.

Confluence New PDF Export Engine

/* Adjust PDF export to reduce page margins for eDoc Snapshots */
@page {  
  margin: 0mm;   
}  

Confluence Legacy PDF Export Engine

/* Adjust PDF export to reduce page margins and hide title for eDoc Snapshots */
@page {  
  margin: 0mm; 
  /* including this forces Confluence to fall back to legacy engine */
  @top-center    { font-size: 8pt;  }  
}  
.pagetitle h1 { display: none; }  /* hide the page title */  

Notes

• See https://support.atlassian.com/confluence-cloud/docs/customize-exports-to-pdf/ for more information on supported PDF customizations.

• Atlassian is working on improving the new engine.

• Known Limitations: The Jira macro only renders an table of Jira issues in the New PDF engine.

Alternative PDF Export Apps

There are additional PDF Export apps available in the marketplace that may provide additional options if the built-in PDF export does not meet your team’s needs.

...