Content re-use and automated publishing via Confluence Command Line Interface

This post is about the Confluence Command Line Interface, a tool developed by Bob Swift, and the way we’ve used it to solve a tricky requirement. We needed to copy a large amount of existing documentation for a number of products, and make that documentation available to a specific set of customers. We needed only part of the existing documentation for each product, and we needed to copy it regularly and repeatedly after major or minor updates. A prime candidate for content re-use and automation.

Our target audience is the customers who use our ‘OnDemand’ line of products: pre-installed and configured sites in the cloud. Therefore, large parts of the documentation for each product are applicable to these customers, but a small proportion of the documentation is irrelevant to them. For example, they don’t need to know how to install the product, and some of the configuration options are not available to them. This means that we needed conditional publishing as well as content re-use. We have used the Confluence Command Line Interface (CLI) to craft a solution. This is a specific use case, but I think the CLI is an excellent tool with wide application. So I’m writing to let you know about it. :)

The past

Until last week, our OnDemand documentation space contained just the introductions and overviews for people using the cloud-based products. For the product-specific documentation, we gave people a set of links to click, which sent them to the full set of documentation for each product.

When people went to the JIRA OnDemand user’s guide, for example, they would click a link and find themselves in the full JIRA documentation. They clicked happily around, searched with enthusiasm, and started reading about features that are not relevant to OnDemand sites.

The present

The OnDemand space now includes copies of all relevant pages from the Confluence, JIRA, Bamboo, FishEye and Crucible spaces. Pages that are irrelevant (such as the installation and plugin guides) are not included.

How did we do it? We used Bob Swift’s Confluence CLI to push the required pages to the OnDemand space. The CLI is a command line client that you run from your own computer. Just unzip it, give it the address of the Confluence server and a username/password to work with, and Bob’s your uncle. (wink) It uses Confluence’s remote API to access and update the data. One of the things that the CLI can do is copy pages from one space to another. If the page does not exist in the destination space, the CLI will add it. If it does exist, the CLI will update the page by adding a new version of the page. Upon request, the CLI will handle attachments in a similarly sensible way.

We have a number of batch files, one for each product, each containing a list of commands that copy all the relevant pages from the product documentation space to the OnDemand space. We built the batch files by hand, from our knowledge of the pages that are applicable to the OnDemand customers.

The future

In the medium term, we will continue using the CLI solution to update the OnDemand docs. For each product release, we will:

  • Update the CLI commands as required, adding new pages that need to be copied and occasionally removing pages that we don’t need any more. Note: We can leave all the pages in the list, whether they’ve been updated for the new release or not.
  • Run the CLI batch file when the new release has been published in the product documentation space. This will copy across all the updated pages for the new release into the OnDemand space.

We’ll also use the CLI solution to update the OnDemand pages at random times, when we’ve made valuable changes to the product docs during routine maintenance or in response to requests from customers or support.

More conditional publishing coming soon. The CLI allows us to pick and choose the pages that we copy to the OnDemand documentation space, simply by including or excluding the page from the CLI batch file. But there are times when just part of a page needs to be different in the OnDemand documentation and the product documentation. We’ll do that via inclusions. For example, this set of navigation instructions is re-used in a number of pages: Navigating to the Administration Console. We’ll be able to have different instructions in the OnDemand space and the Confluence space, to reflect the fact that the navigation menus are slightly different in the cloud-based products.

You can already see some examples of this method of conditional publishing via inclusions. For example, the Confluence documentation has a re-usable page about prerequisites for the Confluence Office Connector. The OnDemand page is shorter than the full product page, because some of the configuration is done automatically for OnDemand sites.

And soon after that… This new solution also puts us in a good place for the implementation of the Scroll Versions plugin, which will bring us more conditional publishing features as well as sophisticated version control. While implementing the CLI solution, we’ve learned a lot about the effects of having duplicate page content in two spaces, and figured out how to find duplicate page names across spaces. We’ve formulated our content re-use strategy, and made design decisions such as changing the search function so that it displays results from a single space only. We’ve also learned more about our content, which has to be a good thing!

References

An earlier post introduces the Confluence Command Line Interface and how to use it: Confluence CLI for bulk actions like deleting or publishing pages.

The CLI documentation includes some useful examples and a list of all the available actions and parameters.

The batch files for our CLI solution are on Bitbucket: AOD CLI.

We make frequent use of the Include Page macro for content re-use, by including the content of one page into another. This dovetails neatly with our new CLI solution. I’ll write a more detailed post about this some time.

Thank you to Bob Swift for the awesome Confluence CLI! And kudos to our technical writers, who have undertaken a gleeful transmogrification into the Tech writing AOD bot.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 16 September 2012, in Confluence, technical writing and tagged , , , , , , . Bookmark the permalink. 16 Comments.

  1. This looks very promising!!! great article!!!
    We have similar issues and this solution looks perfect.
    I’m interested also with what you wrote at the end “made design decisions such as changing the search function so that it displays results from a single space only”
    How did you do it? what you had to use? what were the necessary requirements?

  2. Hallo Lukasz

    I’m glad this solution looks promising for you too! We’re using the Confluence Documentation theme. One of the options in the theme configuration is to restrict the search to the current space. That just means that by default the search returns results from the current space only. People can select another space or the entire site when they see the search results.

    Cheers, Sarah

  3. Hallo Lukasz

    There’s an option in the Documentation theme config that you can use to restrict the search to the current space. That config affects the search box at top right of the screen. The option is only in effect when someone is looking at a page in the space, so it is not in effect when they are on the dashboard.

    This is different from the search box that the Documentation theme puts in the left-hand navigation panel.

    Cheers, Sarah

    • Yeap, but I’m referring to a fact that in the search located on dashboard you will somehow get these duplicated page. Is it a risk you just accept or you have some ideas for that?

      Cheers,
      Lukasz

  4. Hi Sarah, thank you for the insightful article. I’d like to know if Confluence supports (either natively through macros or through marketplace plugins) conditional publishing. For example, whilst crossreferencing, I’d like to include both the section heading and page number in PDF outputs; however, I’d like to suppress/exclude page numbers in the Wiki/online outputs. Is this possible?

    Also, in a page of content that addressed the requirements of multiple operating systems, can I profile content by OS and publishing content based on OS profile? Similarly, can I tag review comments and questions so that when publishing the customer-facing version, they are never visible.

    These features are par for the course in FrameMaker and DITA-based authoring tools. I’d love to find out that they are available in Confluence as well.

  5. hi Sarah
    I’m already using the CLI Interface for Conflunce. Now I would like to use it to change the Content of a page. I don’t understand the -modifyPage command. When I try the command:
    –action modifyPage –space “GLO” –title “Chair” –findReplace “proddate:productiondate” –comment “productiondate introduced”
    I get a java runtime exception.
    Christian

  6. Hi Sarah,

    Awesome post.

    You say that “this new solution also puts us in a good place for the implementation of the Scroll Versions plugin, which will bring us more conditional publishing features as well as sophisticated version control.” I’ve been testing Scroll Versions, and though it seems to work well for major releases, it doesn’t easily accommodate minor versions or bug fixes where you need to pick and choose the pages that get published. Your CLI process seems to handle such cases well. How are you planning to get around that limitation?

    Thanks,
    Jesse

    • Hallo Jesse

      Great question! Before I left Atlassian, we were well into the design of the process for using Scroll Versions for both major and minor version management. Since I left, the Atlassian technical writing team have put the process into production. It involves tracking both major and minor versions as a “version” branch in Scroll, and merging the branches at strategic points to ensure the changes were present in the right versions.

      I’ll ping the K15t team and the Atlassians, to see if they’d like to provide more details.

      Cheers
      Sarah

    • Hi Jesse,

      We (and most of our users) define a versions for major releases and schedule the changes to those major releases. When we have bug-fixes and improvements that will be shipped in minor releases (we call them actually “patch releases”), we just make them in the major version and re-publish that version. Scroll Versions will take care to only publish those pages that have been updated.

      That said, there is an improvement request for publishing individual pages: https://k15t.jira.com/browse/VSN-1219 Please feel free to sign up to vote, watch and comment.

      Cheers,
      -Stefan

  7. Thanks, Sarah and Stefan.

    I’d love to hear more from the Atlassian folks about their process. At my company, many people outside the Docs team are making occasional, minor updates, and there are frequent, somewhat unpredictable feature releases happening throughout each month, so I’m not yet clear how we could define versions so that people know exactly which version to update. Merging might help, but even then, it seems that when you merge version 1 with version 2, say, all updates from version 1 get merged.

    The easiest solution for us, I think, would be defining a single version to draft new and update existing content and, at publish time, having the ability to choose which pages get pushed live (ideally based on status). Stefan, would the improvement request you mention above allow such a process? In any case, thanks very much for pointing it out. I’ll certainly, vote and watch.

    Best,
    Jesse

    • Hi Jesse,

      let me quickly come in here.

      In the first step we’ll focus on implementing the functionality to publish single pages (planned to be implemented in Scroll Versions 2.2).
      Afterwards we’ll have a deeper look how we can link this functionality with the workflow feature, or with the label-functionality from Confluence (e.g. publish several pages with a specific label).

      I hope this helps.

      As customer feedback and ideas are very welcome here at K15t, it would be great if you would give us some more information about your specific use case in your support-ticket. Then we can discuss your requirements with our delevopers and see what we can do.

      Cheers,
      Nils – K15t Software

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 1,499 other followers

%d bloggers like this: