Exporting to PDF with K15t PDF Exporter

Overview

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

Once installed, the Comala pdf-export macro can 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, 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.

This Confluence error message is also 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 might not appear on the transition to the Published state, as the PDF export is an asynchronous event and can 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 can 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.

pageapproved event trigger is still used to activate the pdf-export macro and add the on-screen message
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 is still activated on the successful export of the PDF

Create an 'error' state

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

The transition to the Error state is 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.

You can:

Use the same approval name as the Review state approval, and the pageapproved trigger listens for the approval event in each state approval

Customize the content review buttons displayed in the workflow state dialog box 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 document activity report includes 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}