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
- If you choose this method, then you must include a referer header in each request. Example:
- 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_PATHSproperty:IGNORE_REFERER_FOR_PATHS=*DotAjaxDirector/com.dotcms.publisher.ajax.RemotePublishAjaxAction/cmd/addToBundle - Important: This approach reduces the security of the endpoints
- To disable the requirement for a referer in the request header, add the class for these methods to the
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:
So, using a call against the dotCMS Demo Site as an example:/api/environment/loadenvironments/roleId/{SYSTEM_ROLE_ID}
Retrieving the role ID can be performed, for example, with this call:curl --user admin@dotcms.com:admin -XGET https://demo.dotcms.com/api/environment/loadenvironments/roleId/e7d4e34e-5127-45fc-8123-d48b62d510e3curl --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¶mOperation=publish
