Remote Publishing / Bundle API

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 https://demo.dotcms.com/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 "Authorization:Bearer $TOK" --referer example.com -XPOST https://demo.dotcms.com/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle?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

In each example, the data payload is submitted via query parameters on the API call.

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 "Authorization:Bearer $TOK" -H 'Origin: https://demo.dotcms.com' -XPOST  https://demo.dotcms.com/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle?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 "Authorization:Bearer $TOK" -H 'Origin: https://demo.dotcms.com' -XPOST  https://demo.dotcms.com/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle?query=contenttype:news&bundleId=01E1YNZBZWWNVHJBK5KFVNF8ZZ

Add a Site by Site ID

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 "Authorization:Bearer $TOK" -H 'Origin: https://demo.dotcms.com' -XPOST  https://demo.dotcms.com/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle?query=+identifier:fabeb9c7-4de2-4e97-b570-4ad667181474&bundleName=testSupportSiteID

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 "Authorization:Bearer $TOK" -H 'Origin: https://demo.dotcms.com' -XPOST  https://demo.dotcms.com/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/pushBundle?&filterKey=Intelligent.yml&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

Finding the UUID of an Environment

An Environment UUID can be found in the following ways.

• API, using the following call:

  /api/environment/loadenvironments/roleId/{SYSTEM_ROLE_ID}
  

  So, using a call against the dotCMS Demo Site as an example:

  curl --user admin@dotcms.com:admin -XGET https://demo.dotcms.com/api/environment/loadenvironments/roleId/e7d4e34e-5127-45fc-8123-d48b62d510e3
  

  Retrieving the role ID can be performed, for example, with this call:

  curl --user admin@dotcms.com:admin -XGET https://demo.dotcms.com/api/v1/users/current
  

• Database query:

  SELECT * FROM publishing_environment order by name
  

• Browser dev tools:
  • Navigate to the Publishing Environments Tab
  • Right-click over the Edit Environment button and select Inspect
  • The ID is visible inside of a goToEditEnvironment() call in the <a> tag, like so:

    <a style="cursor:pointer" onclick="goToEditEnvironment('XXXXXXX-XXXX-XXXXXX')" title="Edit Environment">
    

An option to view the UUID as a user-interface element is forthcoming.

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 "Authorization:Bearer $TOK" -H 'Origin: https://demo.dotcms.com' --output my-bundle.tar.gz -XPOST https://demo.dotcms.com/DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/downloadUnpushedBundle?bundleId=01E1YNZBZWWNVHJBK5KFVNF8ZZ&paramOperation=publish