×

You're using an outdated browser

For a better experience, keep your browser up to date. Check here for the latest version.

Manual

Publishing via REST API

Roman Serazhiev

Roman Serazhiev Last update: Jul 9, 2018

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.

Method URL Description
GET /versions/{spaceKey} Returns an array of Version objects.
GET /publish/{spaceKey}/{type}/new Returns a default request entity object which can be used for further publishing requests.
POST /publish/{spaceKey}/{type}/preview Creates a preview of the publish request. Returns a reference to an asynchronous task.
POST /publish/{spaceKey}/{type}/publish Publishes 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 Parameter Description Default Required
spaceKey Key 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"

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
    }
]

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 Parameter Description Default Required
spaceKey Key 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"

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
}

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 Parameter Description Default Required
spaceKey Key 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 Parameter Type Description Default Required
versionId String The generated ID of the Version which should be published. - (tick)
targetSpaceKey String Key of the Confluence space, e.g. ds for "Documentation Space", to where the Version should be published. - (tick)
targetSpaceName String

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

Only necessary for publish type to_new

- ((tick))
targetSpaceBaseUrl String

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

Only necessary for remote publishing.

- ((tick))
treeProviderName String Describes the Variant which the pages need to be published. If empty, it means pages can have any or no Variant. -  
languageKey String Language 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)
remoteSystemId String

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))
copyLabels Boolean Option indicating to copy labels of all pages and the space itself to the new space. false  
keepAuthorsAndDates Boolean Option indicating to keep the author and dates of all pages. false  
removeAttachments Boolean Option indicating to remove historical and deleted attachments from all pages, i.e. only the latest version of attachments will be published. false  
sendEmail Boolean Option indicating to send a notification when a page was updated. false  
keepPermalinks Boolean Option indicating to keep the permalinks of the original language of all pages. false  
onlyPagesInFinalState Boolean Option indicating to only publish pages which have the workflow status Complete assigned. ?? false  
onlyPagesInFinalStateProcessChildren Boolean Option indicating to also publishes children of pages where the parent pages are not in the workflow status Complete. ?? false  
publishHierarchy Boolean Option 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}' 

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
}

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 Parameter Description Default Required
spaceKey Key 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 Parameter Type Description Default Required
versionId String The generated ID of the Version which should be published. - (tick)
targetSpaceKey String Key of the Confluence space, e.g. ds for "Documentation Space", to where the Version should be published. - (tick)
targetSpaceName String

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

Only necessary for publish type to_new

- ((tick))
targetSpaceBaseUrl String

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

Only necessary for remote publishing

- ((tick))
treeProviderName String Describes the Variant which the pages need to be published. If empty, it means pages can have any or no Variant. -  
languageKey String Language 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)
remoteSystemId String

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))
copyLabels Boolean Option indicating to copy labels of all pages and the space itself to the new space. false  
keepAuthorsAndDates Boolean Option indicating to keep the author and dates of all pages. false  
removeAttachments Boolean Option indicating to remove historical and deleted attachments from all pages, i.e. only the latest version of attachments will be published. false  
sendEmail Boolean Option indicating to send a notification when a page was updated. false  
keepPermalinks Boolean Option indicating to keep the permalinks of the original language of all pages. false  
onlyPagesInFinalState Boolean Option indicating to only publish pages which have the workflow status Complete assigned. ?? false  
onlyPagesInFinalStateProcessChildren Boolean Option indicating to also publishes children of pages where the parent pages are not in the workflow status Complete. ?? false  
publishHierarchy Boolean Option 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}'

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
}

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 Parameter Description Default Required
taskId The 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"

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
}

#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
                }, {...}
            ]
        }
    }
}

2xlatest
We use cookies to create a secure and effective browsing experience for our website visitors and to understand how you use our site (i.e. Google Analytics). For more information: click here.
Ok