Exporting via the REST API

This page describes how to create an export using the REST API. This might be useful, if you want to automatically create documentation with every nightly build. For more information about using the REST API in Confluence see: Using the REST APIs.

All Scroll Exporter are supporting the REST API. By using the REST API, you can automatically start your exports. For example, you can do an export with every nightly build.

Getting the URL 

Before you begin: Before getting the URL, you have to  export your content to HTML. Confluence Administrators and Space Administrators require access to the REST URL which can then be inserted into a script.

To get the URL:

1. Click Page Tools (•••) > Export to HTML.

   
   The screen Export to HTML and the existing export schemes are displayed.

2. Select the wanted export scheme and click Start Export.
   The progress bar is displayed.

3. Click REST URL, copy the displayed URL and click Close.

The REST URL is copied and can now be used in your script, see the curl and wget examples below.

Using the URL

The URL can be used with different tools.

Authentication

The following authentication methods are available for the REST API.

Authorization: Basic <username:password>

...&os_username=admin&os_password=admin

Authorization: Bearer my-token

If you want to use some non-browser tool like wget or curl, you probably have to use either HTTP basic authentication or URL parameters.

curl 

Curl is a command line tool for transferring data with URL syntax. It is preinstalled on MacOS X and available for all Linux distributions using the package manager. There are also builds for Windows available. You can use curl using the command line as follows. On MacOS X and Linux please make sure to place the URL in double quotes as otherwise the "&" character inside the URL will break the command.

HTTP basic authentication:

curl --remote-header-name --remote-name -u admin:admin "http://www.example.com/confluence/rest/scroll-html/1.0/sync-export?exportSchemeId=7F00000101316644174326E600DED2BA&pageId=32769&os_authType=basic"

URL parameter based authentication:

curl --remote-header-name --remote-name "http://www.example.com/confluence/rest/scroll-html/1.0/sync-export?exportSchemeId=7F00000101316644174326E600DED2BA&pageId=32769&os_username=admin&os_password=admin"

wget 

wget is another command line tool for transferring data with URL syntax. It is available for all major platforms. You can use wget using the command line as follows. On MacOS X and Linux please make sure to place the URL in double quotes as otherwise the "&" character inside the URL will break the command.

HTTP basic authentication:

wget --content-disposition --http-user=admin --http-password=admin "http://www.example.com/confluence/rest/scroll-html/1.0/sync-export?exportSchemeId=7F00000101316644174326E600DED2BA&pageId=32769&os_authType=basic"

URL parameter based authentication:

wget --content-disposition "http://www.example.com/confluence/rest/scroll-html/1.0/sync-export?exportSchemeId=7F00000101316644174326E600DED2BA&pageId=32769&os_username=admin&os_password=admin"

Other Tools 

If you use other tools, you can compose the URL as described below.

HTTP basic authentication:

[http://www.example.com/confluence/rest/scroll-html/1.0/sync-export?exportSchemeId=7F00000101316644174326E600DED2BA&pageId=32769&os_authType=basic]

URL parameter based authentication:

[http://www.example.com/confluence/rest/scroll-html/1.0/sync-export?exportSchemeId=7F00000101316644174326E600DED2BA&pageId=32769&os_username=admin&os_password=admin]

Asynchronous Export

Sometimes it might be necessary to asynchronously trigger the export. We recommend to use this API if you want to expect a large number of pages - we have included a link to an example script below.

To asynchronous export your content

1. Check out the

   example script here

2. Open the script with a text-editor

3. Edit the following values:

   Value	Description
   host	Enter your Confluence server URL.
   exportSchemeId	Enter the exportSchemeId.
   rootPageId	Enter the Id of the page you want to start the export from.
   username	Enter the username of the user performing the export.
   password	Enter the password of the user performing the export.
   product	Enter the plugin-key of your exporter:  scroll-html
   versionId	This value only works when Scroll Versions is also activated in the space Enter the Id of the version you would like to export
   variantId	This value only works when Scroll Versions is also activated in the space Enter the Id of the variant you would like to export.  Or use variantId=all for all variants.

   
   

4. Save the file - after this you can use this script to automatically start your exports.

Exporting without saved Export Scheme

You can also perform an export without saving an Export Scheme first. This is helpful if you do not want the specific Export Scheme to appear on the Confluence UI, or if your export settings are generated dynamically. This works by POSTing the Export Scheme data to the export REST endpoint, instead of specifying a saved Export Scheme. You have to first prepare the Export Specification file before being able to perform the export.

Preparing the Export Specification File

The Export Specification File must be stored in JSON format and must contain the root page of the export, the Export Scheme data and (optional) details from Scroll Versions / Scroll Translations to export the correct version, variant, or language.

To prepare the Export Specification File:

1. Create a temporary Export Scheme with your settings and save it for now.

2. Get the ID of the temporary Export Scheme from the REST URL (

   described here

   ).

3. Download the Export Scheme as file using the following curl command:

   curl -H "Accept:application/json" "http://localhost:1990/confluence/rest/scroll-html/1.0/export-scheme/-C0A81178014CC162A59E7BAB1D2F8FBA" --output export-scheme.json
   

   
   

4. If you do not need the temporary Export Scheme, delete it.

5. Create your Export Specification File as a new text file with the following content: 

   {
   "rootPageId": "<ROOT_PAGE_ID>",
   "versionId": "<VERSION_ID>",
   "variantId": "<VARIANT_ID>",
   "languageKey": "<LANGUAGE_KEY>",
   "exportScheme": <EXPORT_SCHEME_DATA>
   }
   

   
   

6. Enter the details in this file:

   1. Replace <ROOT_PAGE_ID> with the ID of the Confluence page that your export should start on.
      This is required.

   2. Replace <VERSION_ID>, <VARIANT_ID> and <LANGUAGE_KEY> with the respective values from the REST URL.
      All of these fields are optional. If you don't need them remove the respective lines.

   3. Replace <EXPORT_SCHEME_DATA> with the contents of the export scheme file.
      This is required.
      

     Your export spec file should now look like this:
   

   {
   "rootPageId": "10158113",
   "versionId": "AE5345ASFD3231",
   "variantId": "CF34B56543AED1",
   "languageKey": "en",
   "exportScheme": {
   "id": "C0A81178014CC162A59E7BAB1D2F8FBA",
   "name": "My temporary Export Scheme",
   "pageSelectionStrategy": { ... },
   "pageBuilder": { ... },
   "exporter": { ... },
   "exportAdhocPublishedOnly": false
   }
   }
   

   
   

Performing the Export

Use curl to perform the export and specify the Export Specification File to upload using the following curl command:

curl -H "Content-Type:application/json" --data-binary @/path/to/export-spec.json --remote-header-name --remote-name -u admin:admin "http://localhost:1990/confluence/rest/scroll-html/1.0/sync-export?os_authType=basic"

This posts the data from the referenced Export Specification File to the REST endpoint and performs the export with these settings. It is also possible to POST this data to the asynchronous REST API.

OpenAPI Specs

The API specs below represent the lastest API provided by the Server and Data Center versions of Scroll HTML Exporter. You may download the OpenApi spec file specific for your app version at:

<BASE_URL>/download/resources/com.k15t.scroll.scroll-html/api-docs/1/openapi.yaml