What to Know Before Push Publishing - Documentation topics on: adding a category field,bundles,integrity checker,permissions,push publishing,roles,vanity urls,workflow,.

What to Know Before Push Publishing

Before setting up push publishing environments in dotCMS, it is very important to know best practices for the proper workflow, what can and can't be pushed, potential pitfalls, and how to troubleshoot problems. Knowledge of the following limitations and recommandations is vital to successfully manage push publishing.


Single Authoring Environment

There should only be one Authoring environment.

  • In a push publishing environment, ALL changes to content should be made on the authoring server only, and then pushed to the receiving environment(s).
  • If two objects with the same name are created separately on two different servers, attempts to push the object from one server to the other will create a conflict.
  • Conflicts of this type can be resolved using the Integrity Checker; however these issues should be avoided by only creating and editing content from a single Authoring environment.


Matching Server Versions

Your sending and receiving servers should run similar stacks. In particular, it is very important that the versions (including both release and “flavor”, if appropriate) of all of the following match on all servers in your push publishing environment (both sending and receiving servers):

  • dotCMS
  • Java Virtual Machine (JVM)
  • Database
  • Application server

License Version

To use the push publishing feature, you must run an Enteprise Pro, Enterprise Prime, or Cloud dotCMS license.

In addition, you must ensure that each server in a push publishing environment has its own separate, unique dotCMS license. You cannot perform push publishing in any form unless each server's license is unique and valid.



It is strongly recommended that all publishing environments featuring a production instance run in HTTPS.

Identify High Availability Needs

Whatever your intended use of dotCMS, it is important to identify where your architecture will most benefit from High Availability before you configure and build out your push publishing environment.

  • If you have many content editors editing high volumes of content, it is strongly recommended that you cluster your authoring server environment.
  • If your page traffic is high or front end performance of your site is important, you should consider using a cluster for your Production server environment.
    • For very high traffic or performance needs, consider multiple clustered production environments in different regions and/or datacenters.

Capabilities and Limitations

When using and planning push publishing, it is important to understand the capabilities of the push publishing feature, and what types of objects and content can and can't be pushed.

What Can and Can't be Pushed

What CAN be Pushed

The following items can all be push published, either individually or in bundled groups.

Important Note: Push Publishing Dependencies

When any object is pushed, the needed dependencies to completely create and display that object are also pushed. For example, when you push a page, dotCMS will also automatically push Content on the page, Templates, Containers, and the folder(s) in which it resides, etc., as needed. For more information, please see the Push Publishing Dependencies documentation.

What can be Synchronized

In addition, the following can be push published, but when these types of objects are pushed, the objects on the sending and receiving server are synchronized. This means that all objects of the specified type are pushed to the receiving server, and all objects which exist on the receiving server that do not also exist on the sending server will be removed from the receiving server.

What Can NOT be Pushed

The following dotCMS objects cannot be pushed and will need to be added to each server individually as needed:

  • Vanity URLs
  • Roles and Permissions
    • Note: If you push user accounts, those accounts are pushed to the receiving server without any permissions assigned, and you must manually assign roles and permissions to the user accounts after they have been pushed to the receiving server.

Ways to Push Publish

Push Individual Objects

Individual objects can be pushed to a receiving server one at a time in two ways:

  • Manually push publish a single object.
    • Right-click an object and select Push Publish from the right-click menu.
  • Push Publish via Workflow.

Push Multiple Objects

In addition, multiple objects can be pushed to a receiving server at the same time in all of the following ways:

  • Manually push multiple selected objects.
    • (Select multiple items on a screen, and then press the Push Publish button on the bottom of the screen).
  • Create and push Bundles of objects.
  • Download bundled content from the sending server and upload the bundle on the receiving server.

Note: A bundle which is created and downloaded from one server may only be uploaded to a different server. You can not download a bundle from a server and later upload it back to the same server.

How Push Publishing Permissions Work

The overwhelming majority of push publishing issues can be prevented by setting proper user and Role permissions on your authoring and production servers.

User Permissions

It is important to understand that neither users nor content publisher roles need to exist on receiving server to successfully push objects. Push publishing is designed to work so that if users on the authoring server/environment do not have user accounts on the receiving server/environment, the push will work without errors. In fact, in push publishing is designed so that the chance of conflicts is greatly minimized when users which create and push content on the authoring server(s) do not have user accounts on the receiving server(s).

When a content publisher pushes, the system checks the receiving server for the existence of the user. If the user does not exist on the receiving server, the system pushes the objects successfully using a System User, ensuring that the push is performed with all the necessary permissions.

However, if the pushing user does exist on the receiving server, then the user's roles and permissions on the receiving server are checked and validated. If the user does not have the same permissions and roles on the receiving server that they have on the authoring server, the push will fail. For this reason, it is recommended that you do not push users between servers or reproduce Roles on both the pushing and receiving servers.

Content Locks

Push Publishing does not respect locks of content on the receiving server.

This is intentional. Since content is not intended to be edited on both the sending and receiving servers, if a user has permissions to push content to the receiving server, then the push of that content will succeed even if that content is locked on the receiving server. In this case, lock on the receiving server will be removed and the content will be pushed successfully.

This behavior ensures that pushes of content work based only on the permissions of your users and roles, and not based on the state of the individual pieces of content being pushed. This enables push publishing to “just work” - once you have set up your push publishing connections and permissions, there is no need to inspect or worry about the state of the content on the receiving server.

Permission Recommendations

The following recommendations can help to avoid having to duplicate users and permissions on each server:

  • Do NOT duplicate user accounts on the production server/environment.
    • If the same users must access both the authoring and production servers, it is ideal to create separate user accounts (with separate permissions) on each server, to prevent accidental conflicts.
  • Grant content creation and editing permissions only to Roles on authoring/staging server.
    • If the same Roles exist on both the authoring and production servers, do not grant those Roles content editing permissions on the production server(s).
  • Limit object permissions on the receiving server(s).
    • Permission objects on the receiving server to inherit the minimum needed Role permissions from their parent object.
  • But ensure that parent and child objects on the receiving server have the necessary permissions.
    • Since permissions do NOT push, child objects pushed will automatically inherit permissions from their immediate parent on the receiving server.
    • Make sure that the receiving server parent objects have the desired minimal roles (such as the needed intranet roles or CMS Anonymous if the objects being pushed require front-end login access).
  • Create and train users on a Push-to-Production publishing policy.
    • Ensure that no users edit or publish directly on the production server(s).

How Taxonomies are Pushed

Tags and Relationships

New Tags, and Related Content push publish along with each piece of content that uses them.

The tags/relationships on each piece of content will be compared to existing tags/relationships on the receiving server:

  • If the tags/relationships already exist on the receiving server, they will be associated with the content.
  • If the tags/relationships do not exist on the receiving server, they will be created on the receiving server and then associated with the content.


Category taxonomies in dotCMS cannot be push published individually. When push publishing is performed from the Categories view, ALL of the categories from the sending server are synchronized with ALL of the categories on the receiving server.

Before pushing Content Types that have Category fields which utilize a new category, you must synchronize categories from the sending to the receiving server, to ensure that all categories exist and are up-to-date on the receiving server.

Additional Recommendations

Synchronize Categories Before a Push

Push to synchronize Categories after any new category or subcategories are created, or before any large push.

Categories can not be pushed individually, and a new category will not automatically be pushed when a piece of content that uses that category is pushed. For more information, please see Categories, above.

Don't Modify Workflow on the Production Server

You should never create or modify workflow tasks on the production server when push publishing is configured. The workflow on the production server will be overwritten by the workflow from the authoring server when content is pushed.

Correcting or Reversing an Unwanted Push

If you make a mistake or wish to reverse a push of content, you can make corrections using one of the following methods:

  • Edit the object(s) and push again.
    • Note: You can revert content to a previous version from the Content History tab.
  • Perform a Push to Delete to remove the object from the receiving server.

Important Notes:

  • You should NOT manually unpublish or revert the changes directly on the receiving server.
    • Doing this can cause conflicts that will prevent push publishing from working correctly in the future.
  • Using a Push to Delete removes the selected object(s) from the receiving server.
    • If you wish to revert to the version of the content that existed before the original push, you must edit the object(s) and push again, instead of using Push to Delete.