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" }
- 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_PATHS
property: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
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"
}
'