Push Publishing Filters

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

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.

File Properties

Property	Data Type	Default Value	Description
`title`	string	None	The name of the filter that will be displayed to users in the back-end UI.
`default`	boolean	`false`	If `true`, this filter will be used as the default filter for users with permission to access it. Important: There can be only one filter specified as the default. If more than one filter file has the `default` property set to `true`, the default filter may be applied inconsistently.
`roles`	string	None	A comma-separated list of Roles that have permission to use this filter. Users that have not been assigned a Role in this list will not be able to see or select this filter when push publishing.
`filters`	properties	None	A list of filter conditions to apply to the content and objects when this filter is selected by a user.

Filter Conditions

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.

Condition	Sample Value	Description	Excludes
`excludeQuery`	`+contentType:`	A Lucene query specifying what content to exclude (enclosed in double quotes).	Dependencies and explicit selections
`excludeClasses`	`[Host,Workflow,User,OSGI]`	A comma-separated list of object types to exclude (enclosed in square brackets). Please see below for a list of valid values.	Dependencies and explicit selections
`dependencies`	`true`	If `false`, will not include dependencies.	Dependencies
`excludeDependencyQuery`	`null`	A Lucene query specifying what content to exclude from being included by dependency (enclosed in double quotes).	Dependencies
`excludeDependencyClasses`	`[Host,Workflow,ContentType,Language]`	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.	Dependencies
`forcePush`	`false`	If set to `true`, every push using the filter will be performed as a Force Push This ignores the push history so that the objects will be pushed even if they have not been changed since the last time they were pushed to the receiver. Other conditions are still applied, so content and dependencies which are excluded by the other conditions will still not be pushed.	Nothing
`relationships`	`true`	If set to `false`, content which is related to the pushed content will not be pushed as a dependency. All other dependencies will still be pushed. If this is `false`, neither related content, nor the relationships themselves will be pushed.	Related content only

Dependencies

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 dependencies, excludeDependencyQuery, excludeDependencyClasses, and 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 excludeQuery or excludeClasses conditions instead.

Object Classes

The following object classes may be specified in the excludeClasses and excludeDependencyClasses conditions:

Object Types to Exclude	Class Name
Categories	`Category`
Containers	`Containers`
Content (content items, including files)	`Contentlet`
Content Types	`ContentType`
Folders	`Folder`
Languages	`Language`
Menu Links	`Links`
Rules	`Rule`
Sites	`Host`
Templates	`Template`
Workflows	`Workflow`

When the excludeClasses or 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 excludeQuery or excludeDependencyQuery conditions instead.

Access Permissions

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 roles property 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).

Roles

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.

System Roles

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	`User`	Any valid user who is logged into the back-end UI. (the “Logged In User” Role)
Administrator	`CMS Administrator`	A system administrator.
Anonymous User	`CMS Anonymous`	An unauthenticated user (a site visitor who is not logged in).
Content Owner	`CMS Owner`	The owner (creator) of the content or object to be pushed.
Back-end User	`DOTCMS_BACK_END_USER`	A user with the “Back-end User” property on their account set to true. For more information, please see the Front-end and Back-end Users documentation.
Front-end User	`DOTCMS_FRONT_END_USER`	A user with the “Front-end User” property on their account set to true. For more information, please see the Front-end and Back-end Users documentation.
Login As	`Login As`	Any user with permission to Login As (impersonate another user).

Default Filters

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.

Filter	Default	Classes Excluded	Dependencies & Relationships Included	Dependency Classes Excluded	Force Push
Content and Relationships	No	ContentType Template Containers Folder Host Links Workflow Language Rule User OSGI	Yes	ContentType Template Containers Folder Host Links Workflow Language Rule	No
Force Push Everything	No	None	Yes	None	Yes
Everything and Dependencies	Yes	None	Yes	None	No
Only Selected Items	No	None	No	None	No
Content, Assets and Pages	No	Host Workflow ContentType User OSGI Language	Yes	Host Workflow ContentType Language	No

Example

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.