Exporting to PDF with K15t PDF Exporter

Owned by
Robert Alexander Marshall
Dec 14, 2023
6 min read

Overview

This example requires the install of the Scroll PDF Exporter app.

Once installed, the Comalatech {pdf-export} macro can then be used as an action in a trigger macro to export a page or blog post in pdf format. The exported pdf is added to the page as an attachment.

Basic Example

{workflow:name=PDF export}
    {description}
        Pdf export macro example workflow
    {description}
    {state:Review|approved=Published|rejected=Review}
        {approval:Approve For Export}
    {state}
    {state:Published|final=true|submit=Review}
    {state}
    {trigger:pageapproved|approval=Approve For Export}
        {pdf-export}
    {trigger}
{workflow}

In this example, the approved decision will transition the content to the Published state.

When the Approve for Export content review is approved, the content is also exported as a pdf file and added to the content as an attachment

The transition does not wait for the pdf export of the content as a pdf and its addition as an attachment.

The export may take some time - it is queued in Confluence.

  • the successful completion of the pdf export will be seen when the pdf is added as an attachment



Using pdf-export macro events

The pdf-export macro action generates the workflow event  pdf-export-success. This event occurs when the pdf export is successful.

This workflow event can be used to help confirm the success of the pdf export.

A simple way is to add an on-screen message when the event is triggered.

{trigger:pdf-export-success}
        {set-message:style=info|duration=PT1M}
        ||PDF export completed|@datetime@|
        ||See| @attachmentURL@|
        {set-message}
{trigger}

This would display a confirmation message together with the attachment URL and the date and time the export was completed.

A second workflow event can also be generated by the pdf-export macro, the pdf-export-error event.

This event occurs if the pdf export fails.

Again this can be used, for example, to generate a custom notification.

{trigger:pdf-export-error}
        {set-message}
        There was an error in the pdf export @errormessage@
		{set-message}
{trigger}

The value reference @errormessage@ in the set-message content displays the value for actual error recorded by Confluence.

Note that this same Confluence error message will also be displayed but can be removed by a user.

In this simple example

  • the actions of the  pdf-export macro are not recorded in the page activity report for the content


  • the on-screen message notifications may not appear on the transition to the Published state as the pdf export is an asynchronous event and may take some time to be completed

Manage the pdf export and add details to the page activity report

The pdf-export macro events can be used in one or more triggers to

  • display a notification that content is being exported
  • add details of the pdf export to the page activity report
  • transition on the success of the pdf export

Remove the approval transition for the approved decision from the Review state. 

{state:Review|rejected=Review}
        {approval:Approve For Export}
{state}


An approved decision for the Approve for Export approval will now NOT action a content review transition. 

The pageapproved event trigger is still used to activate the pdf-export macro but before the pdf-export macro, an on-screen message notification is added.

{trigger:pageapproved|approval=Approve For Export}
		{set-message}
		This content is currently being exported to pdf
		{set-message}
        {pdf-export}
{trigger}

The content now remains in the Review state after an approved decision.

A transition  is set to occur as an action in a pdf-export-success event trigger.

{trigger:pdf-export-success}
	{set-message:style=success|duration=PT2M}
	 PDF export completed!
	{set-message}
	{set-state:Published|comment=Approved page exported as pdf - see @attachmentURL@}
{trigger}

Completion of the pdf export causes the pdf-export-success event trigger to transition the content to the Published state using the {set-state} macro.

The page activity report includes details of the pdf export that were added as the comment parameter value for the {set-state} macro.

Create a 'waiting' state for pdf export

Exporting to PDF can take some time, you may find it useful to have a 'waiting' state - a workflow state to wait for the completion of the pdf export.

{state:Review|approved=Export PDF|rejected=Review}
        {approval:Approve For Export}
{state}
{state:Export PDF|submit=Published|description=Content is being exported to pdf, please wait ...|hideselection=true}
{state}

The approved decision in the Review state now causes the content to transition to the Export PDF state.

  • the pageapproved event trigger is still used to activate the pdf-export macro and add the on-screen message
  • The pdf-export-success event trigger is still used to transition the content to the Published state and add the details of the pdf export to the page activity report

A user can also simply move of this waiting state by choosing Submit to transition to the Published state. The pdf-export-success event trigger will still be activated on the successful export of the pdf.


Create an 'error' state

If the pdf export fails - for example, the K15t app may be disabled for the instance or space - it may be useful to create and use a workflow state to manage the export error.

The transition to the Error state will be set to only occur if the pdf-export-error event occurs.

{trigger:pdf-export-error}
        {set-message}
        PDF export failed
		{set-message}
		{set-state:Error|comment=PDF export failed - @errormessage@}
{trigger}


The Error state will need to be added to the workflow. A review can be added to allow a user to decide if the export should be tried again or the error ignored and transition to the Published state.


  • use the same approval name as the Review state approval and the pageapproved trigger will listen for the approval event in each state approval
  • customize the content review buttons displayed in the workflow popup to help the user understand the content review decisions

{state:Error|approved=Export PDF|rejected=Published|description=PDF export failed. What do you want to do?|hidefrompath=true|color=#ff0000}
	{approval:Approve for Export|approvelabel=Retry Export|rejectlabel=Ignore Error}
{state}


The page activity report will include details from the comment parameter value for the {set-state} macro.

Example complete workflow with 'waiting' and 'error' states

{workflow:name=Pdf Export workflow}
    {description}
        Pdf export macro example workflow with waiting Export for PDF state and Error state
    {description}
    {state:Review|approved=Export PDF|rejected=Review|colour=#0052CC}
        {approval:Approve For Export}
    {state}
    {state:Export PDF|submit=Published|description=Content is being exported to pdf, please wait ...|hideselection=true}
    {state}
    {state:Error|approved=Export PDF|rejected=Published|description=PDF export failed. What do you want to do?|hidefrompath=true|colour=#ff0000}
        {approval:Approve for Export|approvelabel=Retry Export|rejectlabel=Ignore Error}
    {state}
    {state:Published|final=true|submit=Review|updated=Review}
    {state}
    {trigger:pageapproved|approval=Approve For Export}
        {set-message} This content is currently being exported to pdf{set-message}
        {pdf-export}
    {trigger}
    {trigger:pdf-export-success}
        {set-message:style=success|duration=PT2M}
        PDF export completed!
        {set-message}
        {set-state:Published|comment=Approved page exported as pdf - see @attachmentURL@}
    {trigger}
    {trigger:pdf-export-error}
        {set-message}
        PDF export failed
        {set-message}
        {set-state:Error|comment=PDF export failed - @errormessage@}
    {trigger}
{workflow}


See also