Push Publishing Dependencies

dotCMS simplifies your Content publishing by automatically ensuring that any time you push Content to another server, the Content displays properly and all code works correctly on the receiving server. In other words, you don't need to understand how your changes might affect other portions of your site; all you need to do is author and push your desired Content.

This is accomplished through the use of dependencies. When you push any Content to another server, dotCMS automatically determines the dependencies of that Content, which includes all other Content needed to ensure that the item you're pushing will display and work properly. dotCMS then also automatically pushes everything your pushed Content is dependent on.

For example, if you create a new Folder and add a new Page in that Folder, then the Page is dependent on the Folder. So when you push the Page, dotCMS will also automatically push the Folder.

Change Detection

dotCMS always checks all dependencies when you push your Content. However, to limit the amount of network traffic, by default dotCMS only actually pushes Content dependencies which have changed since the last time they were pushed to the receiving server. So even if your pushed Content depends on a second item, the second item will not be pushed if it has not changed on the sending server since the last time it was pushed to the receiving server.

For example, if a folder was pushed 5 days ago, and you push a change to a Page within that folder, the folder will only be pushed if it has been modified within the past 5 days (since the previous push). If the folder has not been modified since it was last pushed, the Page will be pushed, but the folder will not be pushed again.

Force Push

You may force dotCMS to push dependencies regardless of when they were last pushed or changed by specifying the Force Push option. Please see the Push Publishing Content documentation for more information.

Dependencies List

The following table displays the dependencies for each Content Type:

Note: The Global Language Variables are pushed when a Language is pushed; they are considered part of the language for push publishing purposes.

Tags

Whenever Content is pushed to a Dynamic Endpoint, all new Tags added to that content are also pushed.

Each Tag on the Content is compared to existing Tags on the Endpoint; if the Tag already exists on the Endpoint it is associated with the pushed Content, otherwise the Tag is created on the Endpoint and then associated with the pushed Content.

Note: Tags are dynamic content, and thus are not pushed to Static Endpoints. For more information, please see the Static and Dynamic Publishing documentation.

Categories

Whenever Content is pushed to a Dynamic Endpoint, all new Categories added to that content are also pushed.

Each Category on the Content is compared to existing Categories on the Endpoint; if the Category already exists on the Endpoint it is associated with the pushed Content, otherwise the Category is created on the Endpoint and then associated with the pushed Content. In addition, parent categories are also created to preserve the Category hierarchy.

Note: Categories on content ony push the categories on the content and required parent categories. Sibling categories at the same level are NOT pushed unless specifically applied to the content being pushed. Also not that Categories are dynamic content, and thus are not pushed to Static Endpoints. For more information, please see the Static and Dynamic Publishing documentation.

Relationships

In addition to the core dependencies shown above, whenever you push content to a Dynamic Endpoint that has Relationships to other Content, dotCMS also pushes the related Content.

For example, if you have a Comment contentlet which is linked to a Blog contentlet through a Relationship, when you push the Comment contentlet, the related Blog contentlet will also be pushed. All related content is checked, and if necessary created on the receiving server before being related to the pushed Content on the Endpoint.

Dependencies based on Relationships link Content through 1 level of Relationships. However Relationship dependencies also cascade. So for example if you have a parent-child Relationship with multiple levels, when you push Content at the bottom level of the Relationship tree, it's parent Content, grandparent Content, etc. will be pushed all the way up the relationship tree.

Note: Relationships are dynamic content, and thus are not pushed to Static Endpoints. For more information, please see the Static and Dynamic Publishing documentation.

Files, Images, and WYSIWYG Fields

Files and Images

If you add a file or image to a content item using a File field or an Image field, the content item containing the File or Image field becomes a dependency of the linked file or image. This means that:

• If you push the file or image linked to, the content item that links to it will also be pushed (if it has changed).
• If you push the content item that links to the file or image, the file or image will also be pushed (if it has changed).

WYSIWYG Fields

However this is not true for files and images included in WYSIWYG fields. Content of any kind added through a WYSIWYG field is not counted as a dependency of the content item containing the WYSIWYG field. This means that if you add a file or image to the content in a WYSIWYG field, changing the file or image will not cause the content item containing the WYSIWYG field to be pushed, and changing the content item will not cause the file or image to be pushed (even if it has changed). Therefore if you reference a file or image within a WYSIWYG field, you must do one of the following:

1. Manually push the image or file when the content is pushed.
2. Include the image or file in a bundle with the content item, and push the bundle instead of the individual content item.
3. Create a file or image field in your content type, and use Velocity to reference that field from within the WYSIWYG field (rather than referencing the file or image path directly).

Optional Dependency: Push All Folder Pages

By default, when you push content located in a Folder, all Pages in the parent Folder of the Content are also pushed. However you may prevent pages in the parent Folder from automatically being pushed with Content by setting the PUSH_PUBLISHING_PUSH_ALL_FOLDER_PAGES configuration property to false in the dotmarketing-config.properties file.

Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties file extension.

Cascading Dependencies

The dependencies cascade, to ensure that any objects your pushed content depends on also has access to it's own dependencies. So when you push an item that depends on a second object, and the second object also depends on a third object, all three objects are pushed.

For example, when you push a single Page, the Host, Parent Folder, content, and direct Relationships of the page are also pushed. In addition, since the content on the page is pushed, the Content Type of each piece of content on the Page is also pushed.

In addition, if you have different working and live versions of Content, dotCMS will automatically push all dependencies for both the working and live versions of the Content.

Static Publishing

A number of types of dotCMS objects are dynamic content, which is not pushed directly to a Static Endpoint. When you push any content to a Static Endpoint that depends on any of these types of dynamic content, dotCMS will still check the dependencies of all the dynamic content (and appropriately cascade the dependencies of those items). However dotCMS will not actually send any dynamic content to the Static Endpoint.

From a user standpoint this means you don't need to worry about whether you're pushing content to a Dynamic or Static Endpoint (or bundling it for later publishing or unpublishing on another server); dotCMS automatically handles Push Publishing dependencies, regardless of the final server that will receive the push or bundle.

Limitations

Whenever your content has explicit links, dotCMS automatically determines the dependencies and pushes all dependencies of that content. However in some cases dotCMS can't automatically determine which objects your content depends on, and in these cases you must manually identify and push the appropriate content to ensure that all appropriate content is pushed. The following are the most common cases where this may be necessary:

Content pulled or included via Velocity code

Due to the potential complexity of the relationships among content when using Velocity code, Push Publishing does not recognize dependencies that your content has on anything which is included in your content via Velocity code. This means that if you use Velocity code to reference another dotCMS object, changes to that object will not cause your content to be automatically pushed by dependency.

Content Pulls

You may perform dynamic content pulls in Velocity code (such as when using Widgets or within Container code). However since the content which is pulled varies, dotCMS can not automatically determine which content items are pulled, and content items will not automatically be included in the dependencies.

Included Files

You may include the content of files within your content using the Velocity #dotParse directive or the $import.read() function. However your content and any files included using Velocity code are not linked via dependency, so if you push your content, the included files will not also be pushed, even if they have changed since the last time they were pushed. You must manually push any included files after they are changed.

Common page elements when pushing to a Static Endpoints

When you push Pages to a Static Endpoints, the static page is built using all common page elements (such as headers, footers, navigation, Containers, Templates, etc.) as they exist at the time the Page is pushed. If the common elements are later changed, but the content of the Page itself has not changed, dotCMS will not automatically re-push the page.

To ensure that all Pages on the Static Endpoint are updated properly when a common page element is changed, you must do one of the following:

• Manually identify and push the affected Pages.
• Force Push the common element that was changed.
• Force Push the entire site (recommended).