Push Publishing Filters documentation for the dotCMS Content Management System

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

PropertyData TypeDefault ValueDescription
titlestringNoneThe name of the filter that will be displayed to users in the back-end UI.
defaultbooleanfalseIf 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.
rolesstringNoneA 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.
filterspropertiesNoneA 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.

ConditionSample ValueDescriptionExcludes
Dependencies
Excludes
Explicit
Selections
excludeQuery+contentType:A Lucene query specifying what content to exclude (enclosed in double quotes).YesYes
excludeClasses[Host,​Workflow,​ContentType,​User,​OSGI,​Language]A comma-separated list of object types to exclude (enclosed in square brackets).
Please see below for a list of valid values._
YesYes
dependenciestrueIf false, will not include dependencies.YesNo
excludeDependencyQuerynullA Lucene query specifying what content to exclude from being included by dependency (enclosed in double quotes).YesNo
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.
YesNo
forcePushfalseIf 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.
NoNo
relationshipstrueIf 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 OnlyNo

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 ExcludeClass Name
CategoriesCategory
ContainersContainers
Content (content items, including files)Contentlet
Content TypesContentType
FoldersFolder
LanguagesLanguage
Menu LinksLinks
RulesRule
SitesHost
TemplatesTemplate
WorkflowsWorkflow

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 RoleRole KeyDescription
All User AccountsUserAny valid user who is logged into the back-end UI.
(the “Logged In User” Role)
AdministratorCMS AdministratorA system administrator.
Anonymous UserCMS AnonymousAn unauthenticated user (a site visitor who is not logged in).
Content OwnerCMS OwnerThe owner (creator) of the content or object to be pushed.
Back-end UserDOTCMS_BACK_END_USERA user with the “Back-end User” property on their account set to true.
Front-end UserDOTCMS_FRONT_END_USERA user with the “Front-end User” property on their account set to true.
Login AsLogin AsAny 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.

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.