Remote Publishing / Bundle API

Last Updated: Sep 10, 2020
documentation for the dotCMS Content Management System

Bundles can be used for multiple purposes, such as Push Publishing, backup and restore, and as assets in CI/CD processes. The Bundle API provides methods which allow you to create, publish, and manage bundles through an API interface.

Setup

Before you can perform bundle operations with these endpoints, you must perform the following setup.

Retrieve and Store the Authorization Token

The first thing you must do is retrieve the authorization token, which you will then use to perform all the other API operations. The following example uses the Linux export command and a simple Python command to store the Auth token for later use:

export TOK=`curl -H "Content-Type:application/json" -s -X POST http://localhost:8080/api/v1/authentication/api-token -d  '
{ 
    "user":"admin@dotcms.com", 
    "password":"admin", 
    "expirationDays": 1, 
    "label":"for testing" 
}'  | python -c 'import json,sys;print json.load(sys.stdin)["entity"]["token"]'`

Choose a Method to Specify a Referer

By default, for security purposes, these endpoints do not work without a “referer” header. This means that to use these endpoints (including all of the examples below), you must do one of the following:

  • Include a referer header in the request.
    • If you choose this method, then you must include a referer header in each request. Example:
      curl -H "Content-Type: application/json" -H "Authorization:Bearer $TOK" --referer example.com -XPOST  http://localhost:8080/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle -d '
{
    "assetIdentifier": "71bf1747-56b9-41ca-a3fa-1fc7b8471dba",
    "bundleName":"testing",
    "bundleId":"01E1YNZBZWWNVHJBK5KFVNF8ZZ"
}
  • Disable referer checking for these endpoints.
    • To disable the requirement for a referer in the request header, add the class for these methods to the IGNORE_REFERER_FOR_PATHS property:
      IGNORE_REFERER_FOR_PATHS=*DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle
    • Important: This approach reduces the security of the endpoints

Operations

Add an object to bundle by Identifier

Note: Any object can be added to a bundle, not just content.

This creates or appends an asset to a bundle with the name and/or id specified. The following example creates a new Bundle and adds the home page Template to the Bundle.

curl -H "Content-Type: application/json" -H "Authorization:Bearer $TOK" -XPOST  http://localhost:8080/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle -d '
{
    "assetIdentifier": "71bf1747-56b9-41ca-a3fa-1fc7b8471dba",
    "bundleName":"testing",
    "bundleId":"01E1YNZBZWWNVHJBK5KFVNF8ZZ"
}
'

Add Content Using a Query

You can add content to a Bundle using a Lucene query; all content matching the query is added to the Bundle. When content is added to a Bundle, the Content Types of the content are added by dependency.

curl -H "Content-Type: application/json" -H "Authorization:Bearer $TOK" -XPOST  http://localhost:8080/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle -d '
{
    "query": "+contenttype:news",
    "bundleId":"01E1YNZBZWWNVHJBK5KFVNF8ZZ"
}
'

Add a Site by Name

You can also add a Site to a bundle using a content query. When a site is added to a bundle, all the content/templates and containers beloging the site are added by dependency.

curl -H "Content-Type: application/json" -H "Authorization:Bearer $TOK" -XPOST  http://localhost:8080/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle -d '
{
    "query": "+host.hostname:demo.dotcms.com +live:true",
    "bundleName":"testing"
}
'

Push a Bundle

THe following example pushes a Bundle to two different Push Publishing Environments. The assetIdentifier is the identifier of the Bundle to be pushed, and the whoToSend is the environments to send to, specified as a comma separated list of Identifiers (UUIDs) of the Environments to send to.

curl -H "Content-Type: application/json" -H "Authorization:Bearer $TOK" -XPOST  http://localhost:8080/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/pushBundle -d '
{
    "assetIdentifier": "01E1YNZBZWWNVHJBK5KFVNF8ZZ",
    "remotePublishDate":"2001-01-01",
    "remotePublishTime":"10-00",
    "remotePublishExpireDate":"2051-01-01",
    "remotePublishExpireTime":"10-00",
    "iWantTo":"publish|expire",
    "whoToSend":"UUID-prod-environ1,UUID-prod-environ2",
    "forcePush":true|false
}
'

Download a Bundle

You can download a bundle as a .tar.gz file, either for publish or unpublish. The following example downloads the bundle from the above examples, for publishing.

curl -H "Content-Type: application/json" -H "Authorization:Bearer $TOK" -XPOST  --output my-bundle.tar.gz http://localhost:8080/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/downloadUnpushedBundle -d '
{
    "bundleId":"01E1YNZBZWWNVHJBK5KFVNF8ZZ",
    "paramOperation": "publish"
}
'

On this page