Remote Publishing Example

Remote publishing requires the Remote Publishing Plugin.

Overview

Let's suppose we have two confluence instances: The research instance, where documents are produced by internal staff, and a public instance, where certain documents are going to be published for a wider audience. We want to publish the documents in the PUBLIC space.

Setting up the public instance

The remote API must be enabled in the public instance (go to Administration > General Configuration > Feature Settings to enable it). We need to set up a user, which would have access only to the PUBLIC space.

To make sure everything is set up properly, we can use a couple of macro in the research instance to test the connection:

{workflowproperties:publishing|url=http://public/rpc/xmlrpc|user=post|password=letmein|space=PUBLIC}
{remotepublishingtest}

If everything is ok, we should get something like:
If successful, it will show something like

logged into http://public/rpc/xmlrpc as post, confirmed that the user can write into space PUBLIC

Defining the workflow

We need the Remote Publishing Plugin which contains the {remotepublish-page} macro.

First we need to provide the remote instance information. We do this using the {workflowproperties} macro to define the
publishing property set. We also need to define an approval. We are going to use the approval name publish.

{workflow}
    {workflowproperties:publishing|url=http://public/rpc/xmlrpc|user=post|password=letmein|space=PUBLIC}
    {approval:publish}
    ...
{workflow}

The properties are defined for the entire workflow.

When a page receives the publish approval, we want to publish to the foo confluence instance.

Publishing requires connection and transmitting data to the other instance, and this could take some time. Because we want to minimize any chance of error or session expiration we are going to queue the request, but we want to let the users know that the pages is going to be published. So we are going to require two actions: one to notify that the page is about to be published, and another to queue the publishing request.

{workflow}
    ...
    {trigger:pageapproved|approval=publish}
        {set-message}Page will be published{set-message}
    {trigger}
    {trigger:pageapproved|approval=publish|queue=true}
        {remotepublish-page}
    {trigger}
    ...
{workflow}

When a trigger action is queued, it will be executed asynchronously within a minute of the request.

We want to be able to notify the users if the page has been successfully published or not. To be able to be notified of the outcome of an action, we need to request the trigger to publish a custom event, when the action is completed, whether is successful or not. To do this, we need to give set newevent=pagepublished in the trigger.

Then, we need two triggers to listen to the pagepublished event: one for success, and one for failure. If the page was successfully published, we want to set a message indicating that, and if not, we want to show a message to the publishing user, and to reject the page:

{workflow}
    ...
    {trigger:pageapproved|approval=publish|queue=true|newevent=pagepublished}
        {remotepublish-page}
    {trigger}

    {trigger:pagepublished|success=true}
        {set-message:style=note}Page Published!{set-message}
    {trigger}

    {trigger:pagepublished|success=false}
        {set-message:user=@user@|style=warning}publishing failed: @errormessage@{set-message}
        {reject-page:publish|comment=Remote Publishing failed}
    {trigger}
    ...
{workflow}

Finally, if a page is rejected, we want to set a message indicating that:

{workflow}
    ...
    {trigger:pagerejected|approval=publish}
        {set-message:style=note}Page has to be published{set-message}
    {trigger}
{workflow}

The Final Workflow

This is the final workflow. It is always recommended to save the workflows in a special space (i.e. WORKFLOWS) and to restrict access to only a few users.

{workflow:space=DRAFTS}
    {workflowproperties:publishing|url=http://public/rpc/xmlrpc|user=post|password=letmein|space=PUBLIC}
    {approval:publish}

    {trigger:pageapproved|approval=publish}
        {set-message}Page will be published{set-message}
    {trigger}

    {trigger:pageapproved|approval=publish|queue=true|newevent=pagepublished}
        {remotepublish-page}
    {trigger}

    {trigger:pagepublished|success=true}
        {set-message:style=note}Page Published!{set-message}
    {trigger}

    {trigger:pagepublished|success=false}
        {set-message:user=@user@|style=warning}publishing failed: @errormessage@{set-message}
        {reject-page:publish|comment=Remote Publishing failed}
    {trigger}

    {trigger:pagerejected|approval=publish}
        {set-message:style=note}Page has to be published{set-message}
    {trigger}
{workflow}