This page describes the process how to publish a Scroll Version using Scroll Versions' REST API. This is very useful if you want to automate the process and publish your content, e.g. daily.

MethodURLDescription
GET/versions/{spaceKey}Returns an array of Version objects.
GET/publish/{spaceKey}/{type}/newReturns a default request entity object which can be used for further publishing requests.
POST/publish/{spaceKey}/{type}/previewCreates a preview of the publish request. Returns a reference to an asynchronous task.
POST/publish/{spaceKey}/{type}/publishPublishes the Version data based on the publish request. Returns a reference to an asynchronous task.
GET/async-tasks/{taskId}Returns status and result data for an asynchronous task.


Publish a Version 

The following steps describe how you can publish a Version.

  1. First it's necessary to retrieve the Version information to get the ID of your desired Version. 
  2. You have to prepare your publish request. Optionally you can get a default request entity as a template and ask for a preview of the publish request.
  3. After preparing the publish request, you're able to access the endpoint to publish this Version. As a response you will get an ID for the asynchronous task which has been started in the background. 
  4. Now you just have to wait for the result by pulling the Asynchronous Task endpoint a few times until it returns a positive result.

The following subchapters describe the steps in more detail and contains request and response examples.

Retrieve Version Information 

GET /versions/{spaceKey}

This request will return an array of Version objects. Each Version contains an id, name, description and some other fields. You have to store the Version ID of your desired Version which you want to publish.

URL ParameterDescriptionDefaultRequired
spaceKeyKey of the Confluence space, e.g. ds for "Demonstration Space", from where the Version should be retrieved.-(tick)

Example Request

curl -H "Accept:application/json" "http://www.example.com/confluence/rest/scroll-versions/1.0/versions/VSN"
CODE

Example Response

[
    {
        "id": "C0A81281015668F1AE5D463C4F5DC0FD",
        "name": "1.0",
        "description": "Version for Release 1.0",
        "releaseDate": null,
        "precedingVersionId": null,
        "archived": false,
        "color": "#999999",
        "runtimeAccessible": false
    },
    {
        "id": "C0A812810156699DA0172F4218C867C7",
        "name": "2.0",
        "description": "Version for Release 2.0",
        "releaseDate": null,
        "precedingVersionId": "C0A81281015668F1AE5D463C4F5DC0FD",
        "archived": false,
        "color": "#999999",
        "runtimeAccessible": false
    }
]
CODE

Optional: Get a Default Request Entity 

GET /publish/{spaceKey}/{type}/new

Retrieve a default request entity. The response can then be extended and used for further requests to the other publishing endpoints.

URL ParameterDescriptionDefaultRequired
spaceKeyKey of the Confluence space, e.g. ds for "Documentation Space", from where the publish request should be initiated.-(tick)
type

Type of the publish request. Allowed values:

  • to_same (the data will be published to the space, specified by spaceKey)
  • to_new (the data will be published to a new space, specified by the request entity)
  • to_existing (the data will be published to an existing space, specified by the request entity)
-(tick)

Example Request

curl -H "Accept:application/json" "http://www.example.com/confluence/rest/scroll-versions/1.0/publish/ds/to_new/new"
CODE

Example Response

The endpoint will automatically generate a targetSpaceKey and targetSpaceName for you. The versionId has the value "current" by default, but you should change it to an existing Version ID which you have retrieved in the first step.

{
    "versionId": "current",
    "targetSpaceKey": "ds10",
    "targetSpaceName": "Demonstration Space 1.0",
    "treeProviderName": "",
    "languageKey": "all",
    "copyLabels": false,
    "keepAuthorsAndDates": false,
    "removeAttachments": false,
    "sendEmail": true,
    "keepPermalinks": false,
    "onlyPagesInFinalState": false,
    "onlyPagesInFinalStateProcessChildren": false,
    "publishHierarchy": false
}
CODE

Optional: Create a Preview 

POST /publish/{spaceKey}/{type}/preview

Creates a preview of your publish request. A preview makes sense if you'd like to know what will be published before you actually publish it.

URL ParameterDescriptionDefaultRequired
spaceKeyKey of the Confluence space, e.g. ds for "Documentation Space", from where the publish request should be initiated.-(tick)
type

Type of the publish request. Allowed values:

  • to_same (the data will be published to the space, specified by spaceKey)
  • to_new (the data will be published to a new space, specified by the request entity)
  • to_existing (the data will be published to an existing space, specified by the request entity)
-(tick)

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs the following parameter:

Entity ParameterTypeDescriptionDefaultRequired
versionIdStringThe generated ID of the Version which should be published.-(tick)
targetSpaceKeyStringKey of the Confluence space, e.g. ds for "Documentation Space", to where the Version should be published.-(tick)
targetSpaceNameString

Name of the Confluence space to where the Version should be published.

Only necessary for publish type to_new

-((tick))
targetSpaceBaseUrlString

Base URL of the space to where the Version should be published. Example: http://host[:port]/[contextPath]

Only necessary for remote publishing.

-((tick))
treeProviderNameStringDescribes the Variant which the pages need to be published. If empty, it means pages can have any or no Variant.- 
languageKeyStringLanguage key for the language which should be published. If key is equal to "all", it means pages can be in any language. Example: en for English-(tick)
remoteSystemIdString

ID of the remote system to where the Version should be published. Only necessary for remote publishing.

Please retrieve the ID from your Application Links from the Confluence Administration.

-((tick))
copyLabelsBooleanOption indicating to copy labels of all pages and the space itself to the new space.false 
keepAuthorsAndDatesBooleanOption indicating to keep the author and dates of all pages.false 
removeAttachmentsBooleanOption indicating to remove historical and deleted attachments from all pages, i.e. only the latest version of attachments will be published.false 
sendEmailBooleanOption indicating to send a notification when a page was updated.false 
keepPermalinksBooleanOption indicating to keep the permalinks of the original language of all pages.false 
onlyPagesInFinalStateBooleanOption indicating to only publish pages which have the workflow status Complete assigned. ??false 
onlyPagesInFinalStateProcessChildrenBooleanOption indicating to also publishes children of pages where the parent pages are not in the workflow status Complete. ??false 
publishHierarchyBooleanOption indicating to publish the page hierarchy to the target space, i.e. the parent child relationship of pages and the order of child pages.false 

Example Request

The following code will execute an example request to the preview endpoint. Here we're sending the JSON data inline with the curl command, but you should consider using a file for it (or if you're creating a script, put it into a variable/object). This increases readability of the command.

curl -H "Accept:application/json" -H "Content-Type:application/json" -X POST
"http://localhost:1990/confluence/rest/scroll-versions/1.0/publish/ds/to_new/preview?os_authType=basic" 
--data '{"versionId":"C0A81281015668F1AE5D463C4F5DC0FD", "targetSpaceKey":"ds10", "targetSpaceName":"Demonstration Space 1.0", "treeProviderName":"", "languageKey":"all", "copyLabels":false, "keepAuthorsAndDates":false, "removeAttachments":false, "sendEmail":true, "keepPermalinks":false, "onlyPagesInFinalState":false, "onlyPagesInFinalStateProcessChildren":false, "publishHierarchy":false}' 
CODE

Example Result

The endpoint will start an asynchronous task in the background to calculate the preview for your request. You then receive a JSON response containing an ID and some status properties. The ID must be used to pull the status of the asynchronous task.

 {
    "id": "C0A812810156745B7C614B0332962415",
    "clusterNo": -1,
    "started": false,
    "cancelled": false,
    "hasFailed": false,
    "finished": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task 'Preview' is currently queued.",
    "resourceLocation": null
}
CODE

Publish a Version 

POST /publish/{spaceKey}/{type}/publish

Publishes your request to the target space specified in the request entity (see entity parameter below).

URL ParameterDescriptionDefaultRequired
spaceKeyKey of the Confluence space, e.g. ds for "Documentation Space", from where the publish request should be initiated.-(tick)
type

Type of the publish request. Allowed values:

  • to_same (the data will be published to the space, specified by spaceKey)
  • to_new (the data will be published to a new space, specified by the request entity)
  • to_existing (the data will be published to an existing space, specified by the request entity)
-(tick)

In order to access the endpoint successfully, you need to provide a request entity as JSON. This entity needs the following parameter:

Entity ParameterTypeDescriptionDefaultRequired
versionIdStringThe generated ID of the Version which should be published.-(tick)
targetSpaceKeyStringKey of the Confluence space, e.g. ds for "Documentation Space", to where the Version should be published.-(tick)
targetSpaceNameString

Name of the Confluence space to where the Version should be published.

Only necessary for publish type to_new

-((tick))
targetSpaceBaseUrlString

Base URL of the space to where the Version should be published. Example: http://host[:port]/[contextPath]

Only necessary for remote publishing

-((tick))
treeProviderNameStringDescribes the Variant which the pages need to be published. If empty, it means pages can have any or no Variant.- 
languageKeyStringLanguage key for the language which should be published. If key is equal to "all", it means pages can be in any language. Example: en for English-(tick)
remoteSystemIdString

ID of the remote system to where the Version should be published. Only necessary for remote publishing.

Please retrieve the ID from your Application Links from the Confluence Administration.

-((tick))
copyLabelsBooleanOption indicating to copy labels of all pages and the space itself to the new space.false 
keepAuthorsAndDatesBooleanOption indicating to keep the author and dates of all pages.false 
removeAttachmentsBooleanOption indicating to remove historical and deleted attachments from all pages, i.e. only the latest version of attachments will be published.false 
sendEmailBooleanOption indicating to send a notification when a page was updated.false 
keepPermalinksBooleanOption indicating to keep the permalinks of the original language of all pages.false 
onlyPagesInFinalStateBooleanOption indicating to only publish pages which have the workflow status Complete assigned. ??false 
onlyPagesInFinalStateProcessChildrenBooleanOption indicating to also publishes children of pages where the parent pages are not in the workflow status Complete. ??false 
publishHierarchyBooleanOption indicating to publish the page hierarchy to the target space, i.e. the parent child relationship of pages and the order of child pages.false 

Example Request

The following code will execute an example request to the publish endpoint. Here we're sending the JSON data inline with the curl command, but you should consider using a file for it (or if you're creating a script, put it into a variable/object). This increases readability of the command.

curl -H "Accept:application/json" -H "Content-Type:application/json" -X POST -u admin:admin 
"http://localhost:1990/confluence/rest/scroll-versions/1.0/publish/ds/to_new/publish?os_authType=basic" 
--data '{"versionId":"C0A81281015668F1AE5D463C4F5DC0FD", "targetSpaceKey":"ds10", "targetSpaceName":"Demonstration Space 1.0", "treeProviderName":"", "languageKey":"all", "copyLabels":false, "keepAuthorsAndDates":false, "removeAttachments":false, "sendEmail":true, "keepPermalinks":false, "onlyPagesInFinalState":false, "onlyPagesInFinalStateProcessChildren":false, "publishHierarchy":false}'
CODE

Example Result

The endpoint will start an asynchronous task in the background to calculate the preview for your request. You then receive a JSON response containing an ID and some status properties. The ID must be used to pull the status of the asynchronous task.

{
    "id": "C0A812810156747CDAFC88250411F484",
    "clusterNo": -1,
    "started": false,
    "cancelled": false,
    "hasFailed": false,
    "finished": false,
    "failureMessage": null,
    "progress": 0,
    "message": "The task 'Publish' is currently queued.",
    "resourceLocation": null
}
CODE

Wait for the Result  

GET /async-tasks/{taskId}

Gets status information about the task with the specified task ID. The individual endpoint should be sent every few seconds, e.g. 2 seconds, because it's the client's responsibility to collect the preview or publish result. The result will be saved for 30 seconds by default. After that it will be removed from memory and can't be accessed anymore.

URL ParameterDescriptionDefaultRequired
taskIdThe ID of the task. You will get the ID from the response of the preview or publish request.-(tick)

Example Request

curl -H "Accept:application/json" "http://localhost:1990/confluence/rest/scroll-versions/1.0/async-tasks/C0A812810156747CDAFC88250411F484"
CODE

Example Response

#1 example: the task has been started, but is still in progress.

{
    "id": "C0A812810156747CDAFC88250411F484",
    "clusterNo": -1,
    "startTimestamp": 1470831751208,
    "started": true,
    "cancelled": false,
    "hasFailed": false,
    "finished": false,
    "failureMessage": null,
    "progress": 0,
    "message": "Analysing the pages to be published: 10",
    "resourceLocation": null
}
CODE

#2 example: the task has been started and finished successfully. In this example an additional result parameter has been added to the response. This result contains some information about the published space and pages.

{
    "id": "C0A812810156747CDAFC88250411F484",
    "clusterNo": -1,
    "startTimestamp": 1470833154820,
    "completionTimestamp": 1470833157943,
    "started": true,
    "cancelled": false,
    "hasFailed": false,
    "finished": true,
    "failureMessage": null,
    "progress": 0,
    "message": "Flushing queue ...",
    "resourceLocation": null,
    "result": {
        "publishSpecSummary": {
            "versionId": "C0A81281015668F1AE5D463C4F5DC0FD",
            "targetSpaceKey": "ds10",
            "targetSpaceName": "Demonstration Space 1.0",
            "targetSpaceBaseURL": "http://localhost:1990/confluence",
            "treeProviderName": "",
            "languageKey": "all",
            "copyLabels": false,
            "keepAuthorsAndDates": false,
            "removeAttachments": false,
            "sendEmail": true,
            "keepPermalinks": false,
            "onlyPagesInFinalState": false,
            "onlyPagesInFinalStateProcessChildren": false,
            "publishHierarchy": false,
            "type": "to_new",
            "sourceSpaceKey": "ds"
        },
        "spaceKey": "ds10",
        "spaceName": "Demonstration Space 1.0",
        "versionId": "C0A81281015668F1AE5D463C4F5DC0FD",
        "status": {
            "messages": [],
            "isDirty": false,
            "isUndone": false,
            "publishedPages": [
                {
                    "type": "add",
                    "hasChanges": false,
                    "isContentChanged": true,
                    "isScrollPageTitleChanged": true,
                    "isMoved": false,
                    "isSequenceOfChildrenDifferent": false,
                    "hasAttachmentChanges": false,
                    "hasRestrictionChanges": false,
                    "hasUnchangedRestrictions": false,
                    "hasAddedRestrictions": false,
                    "hasRemovedRestrictions": false,
                    "originalPageLabels": [],
                    "originalPageContainsInlineComments": false,
                    "pageRestrictions": [],
                    "newPageId": 820647,
                    "newPageTitle": "Welcome to Confluence",
                    "newScrollPageTitle": "Welcome to Confluence",
                    "newVersionName": "Currently Published",
                    "abbreviateNewVersionName": "Currently Published",
                    "newPageLabels": [],
                    "attachments": [],
                    "newPageRevision": 1
                }, {...}
            ]
        }
    }
}
CODE