You may create Push Publishing filters to control which content is pushed from your sending server to your receiving server. The filters allow you to have fine-grained control over what content does and does not get pushed, whether intentionally (when specifically selected) or by dependency.
You may create as many filters as you wish. You can specify permissions for the filters, allowing you to control what content and objects different users and Roles may push. For example, you can allow users with a specific Role to only push content of a specific Content Type, or only push content in a specific location.
- Filter Files
- Access Permissions
Each Push Publishing filter is defined in a YAML (.yml) configuration file. Filter files are located in the
assets/server/publishing-filters/ folder in your dotCMS distribution. Upon startup, dotCMS automatically loads all filter files found in this folder.
|Property||Data Type||Default Value||Description|
|string||None||The name of the filter that will be displayed to users in the back-end UI.|
|string||None||A comma-separated list of Roles that have permission to use this filter.|
|properties||None||A list of filter conditions to apply to the content and objects when this filter is selected by a user.|
The following filter conditions may be specified in the filter file. Content which matches any of these filter conditions will not be pushed. With some of these conditions, content which matches the condition will not be pushed even if it is specifically selected to be pushed by the user.
|A Lucene query specifying what content to exclude (enclosed in double quotes).||Yes||Yes|
|A comma-separated list of object types to exclude (enclosed in square brackets).|
Please see below for a list of valid values._
|A Lucene query specifying what content to exclude from being included by dependency (enclosed in double quotes).||Yes||No|
|A comma-separated list of object types to exclude from being pushed as dependencies (enclosed in square brackets).|
Please see Object Classes below for a list of valid values.
|If set to ||No||No|
|If set to ||Related Content Only||No|
By default, when you push content, dotCMS also sends all content which the pushed content is dependent on, as defined by the Push Publishing dependencies. This means that, if you have changed objects that the content you're pushing depends on to display properly (such as Templates, Containers, or related content), those objects will also be pushed; the pushing of dependencies ensures that the content that was explicitly pushed will display properly on the receiving server, even if you do not explicitly push everything else that content depends on.
However there are times when you may with to push content without pushing all of the other objects that content depends on. You may configure your push publishing filters to prevent the inclusion of dependencies by using an appropriate filter condition.
Content and objects which are excluded via filter conditions based on dependencies (including the
relationships conditions) will not be excluded if the content is explicitly pushed (or explicitly added to the bundle). To exclude these objects and content from the bundle even when they are explicitly added, use the
excludeClasses conditions instead.
The following object classes may be specified in the
|Object Types to Exclude||Class Name|
|Content (content items, including files)|
excludeDependencyClasses conditions are used, all objects of these types are excluded from the push. If you wish to exclude only specific objects of these types (such as specific Content Types, or objects in specific folders), use the
excludeDependencyQuery conditions instead.
For a user to be able to view and use a Push Publishing filter, both of the following must be true:
- The user must have permission to use the Push Publishing Environment they wish to push content to.
- The user must be assigned one or more of the Roles specifies in the
rolesproperty of the Push Publishing filter.
The one exception to this is if a user does have access to a Push Publishing Environment, but does not have access to any Push Publishing filters. In this case, the user will not be able to see or select any filter in the Push Publishing popup, but the default Push Publishing Filter will be used automatically (even though the user does not have explicit permission to use that filter).
Any authenticated user who has been assigned one of the Roles specified in a filter may view and use that filter. In the
roles property, you may specify one or more Role Keys for any Role defined in your dotCMS instance.
In addition to any Roles you create, you may specify the following keys to denote System roles:
|System Role||Role Key||Description|
|All User Accounts||Any valid user who is logged into the back-end UI.|
(the “Logged In User” Role)
|Administrator||A system administrator.|
|Anonymous User||An unauthenticated user (a site visitor who is not logged in).|
|Content Owner||The owner (creator) of the content or object to be pushed.|
|Back-end User||A user with the “Back-end User” property on their account set to true.|
|Front-end User||A user with the “Front-end User” property on their account set to true.|
|Login As||Any user with permission to Login As (impersonate another user).|
The standard dotCMS distribution ships with several filters to use as examples, based on some of the most common needs for Push Publishing control. By default, these filters are available to all users that have permission to push to any Push Publishing Environment; you may, however, modify the permissions of these files to allow different users access to different filters.
|Dependency Classes |
|Content and Relationships||No||Yes||Yes||No|
|Force Push Everything||No||None||Yes||None||Yes||Yes|
|Everything and Dependencies||Yes||None||Yes||None||Yes||No|
|Only Selected Items||No||None||No||None||No||No|
|Content, Assets and Pages||No||Yes||Yes||No|
Prevent Push of Specific Content
The following file creates a filter which prevents the push of any content which contains a Tag named
DoNotPush. This filter allows you to prevent specific content from being pushed by adding a new tag to it named “DoNotPush”. The filter is configured to prevent this content from being pushed either if it's specifically selected, or as a dependency to other content which is pushed.
title: Protected Push default: true roles: DOTCMS_BACK_END_USER filters: ## Content to be excluded (even if explicitly added to the bundle). Lucene query; any content which matches the query will be excluded. excludeQuery:"tags:*DoNotPush*" ## List of classes that should never be pushed (possible classes: ContentType, Template, Containers, Folder, Host, Links, Workflow, Language, Rule, Contentlet, Category, User, OSGI) excludeClasses:[Host,Workflow,ContentType,User,OSGI,Language] ## Check for dependencies: If false, will not bundle dependencies (either normal or through relationships) dependencies: true ## Content to be excluded from dependencies; content which matches will not be added as a dependency (but will be pushed if explicitly added to the bundle). ## This is a Lucene query; any content which matches the query will be excluded. excludeDependencyQuery:"tags:*DoNotPush*" ## List of classes that should never be pushed as dependencies (possibe classes: ContentType, Template, Containers, Folder, Host, Links, Workflow, Language, Rule, Contentlet, Category) excludeDependencyClasses: [Host,Workflow,ContentType,Language] ## Force push behavior: If true will push regardless the pushed asset history forcePush: false ## Push relationships: If false neither the Relationship object nor the related content nor the related content type will be pushed) relationships: true
Note: You may only have one default filter on the system. Therefore, any time you add a filter which you wish to specify as the default filter, you must edit the existing filters to make sure none of them are also specified as the default.