Push Publishing Filters: The P.P.F. F.A.Q.

What Are Push Publishing Filters in dotCMS?

Push publishing is a powerful feature in dotCMS that allows users to push content, files, and assets from one dotCMS instance to another — whether it's from a staging environment to production, or across multiple distributed servers.

Push publishing filters serve as an essential mechanism for refining what content is transferred during the publishing process. These filters allow to configure precise conditions, ensuring that only relevant content is pushed while unnecessary or incomplete items remain behind.

Before we begin, it is important to note that push publishing filters need to be in sync between all environments.

Why Are Push Publishing Filters Important?

1. Content Governance & Quality Control

Push publishing filters help maintain content integrity by ensuring only approved and relevant content gets published. This prevents accidental publication of drafts or incorrect versions of content.

2. Optimized Performance

By filtering out unnecessary content, push publishing processes run more efficiently, reducing server load and publishing time. This is particularly useful for large-scale deployments where frequent updates are required.

3. Improved Security & Compliance

Organizations handling sensitive or region-specific content can use filters to ensure compliance with data policies. For example, a filter can prevent unpublished or restricted content from being pushed to public-facing servers.

4. Better Content Organization

Filters help streamline content workflows by ensuring that only the right content reaches the right environment. This is crucial for multi-site management where different content needs to be pushed to different locations.

How is a Push Publishing Filter Structured?

title: Everything and Dependencies
sort: 3
default: true
roles: "DOTCMS_BACK_END_USER"
filters:
   excludeQuery: ""
   excludeClasses: []
   dependencies: true
   excludeDependencyQuery: ""
   excludeDependencyClasses: []
   forcePush: false
   relationships: true

• Title: Name of the filter that will be shown in the UI.

• Sort: Order in which the filters appear in the UI; if they share the same sort number it will arrange the common-numbered ones alphabetically.

• Default: This will be the pre-selected filter. If more than one filter is set as default, then the system will pre-select the first of them it finds.

• Roles: A comma-separated list of Roles that have permission to use this filter.

• Filters: List of conditions that will be applied to the bundle objects:

  • ExcludeQuery: Lucene query; any matched content will be explicitly excluded from the bundle.

  • ExcludeClasses: List of dotCMS objects that will be excluded from the bundle. Examples include: ContentType, Template, Containers, Folder, Host, Links, Workflow, Language, Rule, Contentlet, Category, User, OSGI.

  • Dependencies: If set to true, dotCMS will find and add any dependencies of the content included in the bundle.

  • ExcludeDependencyQuery: Lucene query; any matched content will be excluded from being added as a dependency.

  • ExcludeDependencyClasses: List of dotCMS objects that will be excluded from being added to the bundle as a dependency. (See ExcludeClasses for examples.)

  • ForcePush: If set to true, this ignores the push history; objects will be pushed even if they have not been changed since the last time they were pushed to the receiver.

  • Relationships: If true, dotCMS checks all content relationships in the bundle, and updates the related content on the receiver.

How Do I Manage Push Publishing Filters?

dotCMS has a set of CRUD (create, read, update, delete) methods for managing your push publishing filters by API.

List Available Push Publishing Filters

Retrieves all push publishing filter descriptors accessible by the user.

Endpoint:

GET /api/v1/pushpublish/filters

Get a Specific Push Publishing Filter

Retrieves a specific push publishing filter descriptor using its unique key — i.e., its YAML filename, such as ContentOnly.yml.

Endpoint:

GET /api/v1/pushpublish/filters/{{filterKey}}

Create a Push Publishing Filter (JSON)

Creates a new push publishing filter using a JSON payload.

Endpoint:

POST /api/v1/pushpublish/filters

Request Body:

{
    "key": "NoWorkflow.yml",
    "title": "Push without Workflows",
    "defaultFilter": "false",
    "roles": "DOTCMS_BACK_END_USER",
    "filters": {
        "excludeQuery": "",
        "excludeClasses": ["Host", "Workflow", "OSGI"],
        "dependencies": true,
        "excludeDependencyQuery": "",
        "excludeDependencyClasses": ["Host", "Workflow"],
        "forcePush": false,
        "relationships": false
    }
}

Create a Push Publishing Filter (YML)

Creates a new push publishing filter by uploading a YAML file.

Endpoint:

POST /api/v1/pushpublish/filters

Request Body:

--form 'file=@"resources/TestPPFilter.yml"'

Update a Push Publishing Filter (JSON)

Updates an existing push publishing filter using a JSON payload.

Endpoint:

PUT /api/v1/pushpublish/filters

Request Body:

{
    "key": "NoWorkflow.yml",
    "title": "Push without Workflows",
    "defaultFilter": "false",
    "roles": "DOTCMS_BACK_END_USER",
    "filters": {
        "excludeQuery": "",
        "excludeClasses": ["Host", "Workflow", "OSGI"],
        "dependencies": true,
        "excludeDependencyQuery": "",
        "excludeDependencyClasses": ["Host", "Workflow"],
        "forcePush": false,
        "relationships": false
    }
}

Update a Push Publishing Filter (YML)

Updates an existing push publishing filter by uploading a YAML file.

Endpoint:

PUT /api/v1/pushpublish/filters

Request Body:

--form 'file=@"resources/TestPPFilter.yml"'

Delete a Push Publishing Filter

Deletes a push publishing filter using its unique key.

Endpoint:

DELETE /api/v1/pushpublish/filters/{{filterKey.yml}}