Automating Scroll Exports With The REST Interface
This blogpost explains how to automatically obtain the latest PDF export files, Word documents, or any other supported export format using the Scroll Exporters' REST interface.Did you know that K15t's Scroll Exporters for Confluence are not only convenient for human users, but also for machines and for continuous integration?
Many of our customers have been using the Scroll Exporters successfully for a long time now. They export their Confluence content to beautifully styled MS Word documents with Scroll Office, publish their manuals to PDF documents with Scroll PDF Exporter, or create context-sensitive help with Scroll EclipseHelp Exporter.
Recently, we introduced Export Schemes that allow you to define all export settings at once, and access them with a single click when you export Confluence content.
But it seems that most people have yet to discover another great feature of the Scroll Exporter add-ons for Confluence: obtaining the most recent export automatically, simply by calling a certain URL.
Accessing the 'Hidden' Feature
I have to admit that this feature is a bit hard to find. After all, it's not something you'll need every day. But no matter which Scroll Exporter you use, it takes only two steps to get there:
- From Confluence's Tools menu, select any export format, e.g. Export to Word.
The Export to Word screen and all available default and custom export schemes are displayed.
- Select an export scheme and click Start Export.
The progress bar is shown until the Export Result page appears.
And right in the middle of it, you'll notice a button called REST URL.
Wait, What's a REST URL?
Both Confluence and Scroll Exporters provide a second interface in addition to the well-known web user interface. The REST interface allows systems to interact with and automate certain activities by sending requests to the web server and handling incoming requests. In most cases, this is done via HTTP, the most commonly used web protocol.
The simplest request would be to access a URL and then obtain a result, which might be a web page, a Word document, or a PDF file. And this is where it starts to get interesting for our Scroll Exporters.
When you click on the REST URL button, you'll be shown an URL like this one:
Let's take a quick look at this web address that provides access to the Scroll Exporters REST interface:
This URL contains all of the settings that were defined during the previous export run:
- The selected custom or default export scheme to be used for publishing (defined via the exportSchemeId parameter)
- The Confluence page on which you started the export (rootPageId)
- Additional Scroll content management values to define the page's release version and content variant filter (defined by Scroll Versions) and the page content's language (defined by Scroll Translations).
Download the Latest Export In One Click
You can also provide the readers of your Confluence-based documentation with the REST URL as a hyperlink. Your colleagues and fellow Confluence users can then export the content by themselves – simply by clicking on this link.
In this example, the link has been placed within a Panel macro that is located in the right sidebar column of the Confluence page layout.
Nightly Builds of Your Documentation – Ready to Go
For all of us who practice Continuous Integration of their software, the Scroll Exporters' REST interface is a great help for consistently including the latest documentation in nightly builds. It's now really simple to trigger an automatic export of your documentation.
All you need to do is embed this REST URL provided by a Scroll Exporter into your build script via Wget, cURL, etc. And if your build environment needs to authenticate to Confluence and the Scroll Exporter's REST interface, you can also provide authentication within the URL or via HTTP basic authentication.
Please check out the Scroll Exporter support docs for more details, where you'll discover that it's possible to trigger an asynchronous export, too.
What's in it for the REST of Us?
Quite a lot! Even regular Confluence users and technical writers can benefit from the REST feature. If a colleague asks you for the latest documentation as a PDF, a Word document, or in any other Scroll Exporter output format, there's now an easy answer. Just send them the corresponding REST URL and they can get it themselves – any time, anywhere.
And you can finally have some rest, or spend your time doing more productive work. Isn't that great?