Automate Your Exports Using the REST API
This page describes how to export content using the REST API. There are two ways to do this: synchronously and asynchronously.
- Synchronous exports are easier, and are recommended for the majority of use cases. You simply build the URL for the export parameters you want (template ID, page ID, etc.), and then you can download the exported file like any other file on the web using a web browser or a tool like curl or wget.
- Asynchronous exports are useful if your exports are extremely large or if you want to start the export job from a script and track its progress.
Synchronous export
Prepare the export URL
- Open Space Tools > Add-ons > Scroll Word Exporter.
- Find the template you want to use, open the actions dropdown menu, and click Template Information. This will open the template information dialog.
- Copy the URL from the REST URL field.
- Replace
PAGE-ID
with the ID of the page you want to export. - (Optional) If required, you can add Export parameters as query parameters.
Example export URL:
http://example.com/confluence/plugins/servlet/scroll-office/api/public/1/export-sync?templateId=205721cc-6689-47ac-ae43-a98cf7f1d9ec&pageId=12345&scope=current
Use the export URL
There are many tools to request data from HTTP servers. Here are some examples using popular tools.
Make sure to check the Authentication section below.
Asynchronous export
To export content asynchronously, you have to
- Start the export job (the server will return the ID of the job).
- Fetch the status of the export job at regular intervals.
- Download the Word file when the export job has finished.
For more details, read on or take a look at the example scripts:
- async-export-python3.py - for Python 3 (tested with Python 3.9)
- async-export-python2.py - for Python 2 (tested with Python 2.7)
Start the export job
Send a POST request to the URL <base-url>/plugins/servlet/scroll-office/api/public/1/exports
. The body of the request must contain the export parameters in a JSON object, for example:
{
"pageId":"557060",
"scope":"current",
"templateId":"com.k15t.scroll.office.default-template-1"
}
You can find the templateID
by clicking Space Tools > Add-ons > Scroll Word Exporter, finding the template you want to use and clicking Template Information in the actions dropdown menu. Export parameters are supported.
The server will return a JSON object that contains the ID of the export job, for example:
{
"jobId": "f3c7c62b-30fb-4260-a323-10779a2b72a3"
}
Monitor the status of the export job
Fetch the status of the export job at regular intervals (we recommend every two seconds) until the job is complete. To get the status, send a GET request to the URL <base-url>/plugins/servlet/scroll-office/api/public/1/exports/<job-id>/status
. The response contains a JSON object describing the status of the export job, for example:
{
"status": "incomplete",
"step": 2,
"totalSteps": 3,
"stepProgress": 75,
"downloadUrl": null
}
The status
property is set to either
incomplete
(the export is still running)complete
(the export has finished successfully)error
(the export stopped with an error)cancelled
(the export was cancelled)
The step
and totalSteps
properties show how many of the steps of the export job are done. The stepProgress
property indicates the progress of the current step, from 0 to 100.
Download the Word File
As soon as the status is complete
, the downloadUrl
property will contain the URL where the Word file can be downloaded.
Cancelling a running or queued export
It is possible to cancel exports that are still queued or are currently being processed by sending a DELETE request without body to <base-url>/plugins/servlet/scroll-office/api/public/1/exports/<job-id>
.
Please note that the status retrieved by GET requests to <base-url>/plugins/servlet/scroll-office/api/public/1/exports/<job-id>/status
will not immediately reflect that the job has been cancelled if the job is still queued but not currently processed.
Exporting as anonymous user
If you intend to perform an asynchronous export as anonymous user you must include the session cookie returned in the start request's response into all subsequent requests (polling and download). This is required for permission checks.
We recommend to use a dedicated user for exports, though.
Authentication
The following authentication methods are available for the REST API.
Authentication Method | Usage | Compatibility |
---|---|---|
Manual Login BROWSER ONLY | Log in via the Confluence login page.
| All Confluence versions |
HTTP Basic Authentication | Add
CODE
| Starting with Confluence 7.16 administrators can disable Basic Authentication. |
URL Parameters | Add both username and password as URL parameters:
CODE
| Not available since Confluence 7.10 unless manually enabled. See the Confluence 7.10 Upgrade Notes for instructions. |
Personal Access Tokens RECOMMENDED | Create a token in your user profile, then add it as request header:
CODE
| Confluence 7.14 and later due to certain limitations after introduction of access tokens in Confluence 7.9 |
Export parameters
Please make sure to follow the capitalization as stated in this table
Name | Required/ Optional | Description | Possible values |
---|---|---|---|
pageId | REQUIRED | The ID of the page or blog post to be exported. | |
templateId | REQUIRED | The ID of the export template to use. | |
scope | OPTIONAL | Controls whether the child pages of the exported page should be exported, too. |
|
locale | OPTIONAL | The locale of the exporting user. This only has an effect if the template's locale is set to User Language. You can also specify the locale through an Accept-Language header, but the locale in the export request has precedence if provided. If neither the export request nor the Accept-Language header contains an explicit locale, 'en' is used. | A valid BCP 47 language tag, e.g. 'en-US' or 'de'. |
versionId | OPTIONAL | Only use if Scroll Versions' version management functionality is activated in the space you are exporting from. The ID of the version of the content to be exported (default value: currently published version). You can find the Please note that this parameter does not have a default value when exporting with a deprecated template and needs to be specified. | |
variantId | OPTIONAL | Only use if Scroll Versions' variant management functionality is activated in the space you are exporting from. The ID of the variant of the content to be exported (default value: 'all'). You can find the Please note that this parameter does not have a default value when exporting with a deprecated template and needs to be specified. | |
languageKey | OPTIONAL | Only use if Scroll Versions' variant management functionality is activated in the space you are exporting from. For use with Scroll Translations! The language key of the translation to be exported (default value: the space's default language). Please note that this parameter does not have a default value when exporting with a deprecated template and needs to be specified. |