Page tree
Skip to end of metadata
Go to start of metadata

Freeze allows you to stop all publication activity on a Magnolia author instance temporarily. Authors can continue to work in the system during the freeze but they cannot version content or publish content. Freeze is useful when you want to swap author instances or you want to make sure that public instances stay in sync during an upscaling event.

The Freeze module provides commands for managing a global freeze flag. Using these commands it's possible to set and unset the freeze flag.

JIRAFREEZE
Gitfreeze

Installation

With version 2.0, the Freeze module was reorganized into several separate modules: 

  • magnolia-freeze: the core Freeze module with minimal dependencies on other Magnolia modules (just Magnolia v5.7 or later, Magnolia publishing v1.0 or later and Magnolia REST v2.1 or later
  • magnolia-freeze-apps: integration of publication freeze checks into the Magnolia Assets, Pages and Stories apps
  • magnolia-freeze-personalization: integrate of publication freeze checks into the Magnolia Personalization publication commands

Maven is the easiest way to install the Freeze modules.

Add the following dependency to your bundle to use the basic Freeze functionality:

<dependency>
  <groupId>info.magnolia.freeze</groupId>
  <artifactId>magnolia-freeze</artifactId>
  <version>${freezeVersion}</version>
</dependency>

Add the following dependency to add publication freeze checks to the publication actions in the Pages, Assets and Stories apps:

<dependency>
  <groupId>info.magnolia.freeze</groupId>
  <artifactId>magnolia-freeze-apps</artifactId>
  <version>${freezeVersion}</version>
</dependency>

Add this dependency to add publication freeze checks to activation commands in Magnolia's Personalization module:

<dependency>
  <groupId>info.magnolia.freeze</groupId>
  <artifactId>magnolia-freeze-apps</artifactId>
  <version>${freezeVersion}</version>
</dependency>

Versions

2.0Magnolia 5.7+
1.8.1Magnolia 5.6+

Usage

The module provides a set of commands useful for controlling and reading the freeze flag. These command can be used in a variety of ways to create a freeze event.

A freeze is cumulative: successive calls to a freeze start must be followed by the same number of calls to stop before the freeze is lifted.

Configuration

Global publication freezes are enforced at two levels: 

  • In availability rules for actions that trigger publications
  • In publication commands

Both are configured through extending or modifying standard Magnolia configuration but not every action or command has been modified. If you want to enforce a publication freeze in your own app or command, you must configure it.

Action configuration

You can control the availability of actions according the state of a publication freeze by using this availability rule: info.magnolia.services.freeze.availability.IsNoGlobalFreeze.

Adding IsNoGlobalFreeze as an availability rule to an action will disable the action if a global publication freeze is active and enable it (depending on other availability rules) if there is no global publication freeze. 

Installing the Freeze apps module will modify the availability rules in the following apps: 

  • Pages app: availability of the publish, publish recursive and unpublish actions
  • Assets app: availability of the publish, publish recursive and unpublish actions
  • Stories app: availability of the publish, publish recursive and unpublish actions

IMPORTANT: other Magnolia apps and your own custom apps can launch publications. You'll have to add IsNoGlobalFreeze to their availability rules to check for publication freezes.

Command configuration

You can interrupt the execution of command chains carrying out a publication by adding the checkGlobalFreeze command. This command checks for a current global publication freeze, and if one is present, will return false. This will stop the execution of a command chain. 

Note that checkGlobalFreeze should be placed before any other command in the chain to stop execution. 

Installing the Freeze module will modify the commands defined in the following modules: 

  • publishing-core: the default-publish, default-unpublish, versioned-publish and versioned-unpublish commands

Installing the Freeze personalization module will modify the commands defined in the Magnolia personalization module

  • personalization-core: the default-personalizationActivation command
  • personalization-integration: the default-personalizationActivation command

If you have your own commands that publish content that should respect a global publication freeze, you should add checkGlobalFreeze to their command chains to prevent executing them during a publication freeze.

IMPORTANT: checkGlobalFreeze should be placed before any command in the chain. checkGlobalFreeze will stop the execution of the command chain if a publication freeze is in effect.

Commands

All the freeze commands can be found in the freeze catalog: /module/freeze/commands/freeze:

startGlobalFreeze

Start a global freeze, or continue a global freeze.

If called multiple times without a corresponding calls to stopGlobalFreeze or toggleGlobalFreeze, the freeze will stay in place until the same number of calls to stopGlobalFreeze are executed or a single call to toggleGlobalFreeze is made.

stopGlobalFreeze

Attempts to stop a global freeze.

The outcome of the attempt is dependent on sequence factors. The index in which the stop is called makes a difference in the default use case. However, using the force parameter in the command context can be used to end a freeze immediately. Set the boolean parameter to true to force the stop to be final.

toggleGlobalFreeze

Toggles the state of the flag.

Will start a global freeze if a freeze is not active or end a global freeze is one is currently active.

Using toggleGlobalFreeze will always start or stop a freeze, even if a freeze has been invoked multiple times.

checkGlobalFreeze

Check the state of the freeze flag.

Will return false if a global freeze is active and true if not. You can use this command in command chains to check if a global freeze is in place.

REST APIs

You can start, stop and get information about the current freeze state through two REST APIs: 

Both APIs provide exactly the same functionality: starting a global freeze, stopping a global freeze, toggling a global freeze and checking on the global freeze state. Both APIs return exactly the same information: the current global freeze state and the global freeze count. 

So which REST API should you use? Whichever you prefer, but if you would like to customize the handling of global freezes, the REST command API is more flexible. 

The enabled commands defined in the command endpoint (at /modules/rest-services/rest-endpoints/commands/enabledCommands) can be modified. You can use a different command to be invoked through the command endpoint or use a command chain to customize the actions taken when managing a global freeze.

REST Command Endpoint

Using Magnolia's REST API it's possible to start. stop, or toggle a freeze. The command endpoint makes this possible. After installation of the freeze module you should see the commands enabled under rest-services.

Freeze REST API

POST

Start or augment a global publication freeze

Returns the status of the global publication freeze.

Note that you can request more than one global publication freeze at the same time. This will increase the "freezeCount" result returned (see below). Multiple freeze requests can be stopped by: 

  • the toggle command immediately stops all freeze requests
  • the stop command with the force parameter: immediately stops all freeze requests
  • the stop command will stop one freeze request, the same number of stop requests as start requests must be sent to stop a global publication freeze

Request URL

/.rest/freeze/v1/start

Returns the status of the freeze request with: 

  • freezeState - if a global freeze is currently in place, normally true, but may return false if an error occurred
  • freezeCount - the freeze count, the number of freeze requests currently active, should be 1 or more, will be 0 if an error occurred

Returns an HTTP status of: 

  • 200 - the global publication freeze was started

POST

Stop or decrement a global publication freeze

Returns the status of the global publication freeze.

If force = false and multiple publication freezes have been requested, stop will decrement the freezeCount returned and the global publication freeze will remain in place.

If force = true and multiple publication freezes have been requested, stop will end the global publication freeze.

Request URL

/.rest/freeze/v1/stop

Parameters

Parameter

Description

Parameter type

Data type

force

optional,  default is false.

Stops any ongoing global publication freeze regardless of the number for freeze requests.

queryboolean

Returns the status of the freeze request with: 

  • freezeState - false if a global freeze is currently in place, true if a global freeze is still active
  • freezeCount - the freeze count, the number of freeze requests currently active, 0 if no freeze is active, 1 or more if still active

Returns an HTTP status of: 

  • 200 - the global publication freeze was modified or stopped

POST

Start or stop a global publication freeze

Returns the status of the global publication freeze.

If a global publication freeze is active, the freeze will be stopped. 

If a global publication freeze is not active, a freeze will be started. 

Request URL

/.rest/freeze/v1/toggle

Returns the status of the freeze request with: 

  • freezeState - true, if a global freeze was started, false if a global freeze has been stopped
  • freezeCount - the freeze count, the number of freeze requests currently active, 1 if a global freeze was started, will be 0 if a global freeze was stopped

Returns an HTTP status of: 

  • 200 - the global publication freeze was started or stopped

Warnings

  • This module is at INCUBATOR level.
  • Versions prior to 1.3
    • Used a different groupid and artifactId. Please make note of the change.

Changelog

  • Version 2.0
    • Reorganized module: magnolia-freeze (no decorations, minimal Magnolia module dependencies), magnolia-freeze-apps (decoration of publication actions in Pages, Stories and Assets apps) and magnolia-freeze-personalization (integrated freeze check with personalization activation commands)
    • Removed unused decorations causing warnings
    • Added warning messages for the Stories app when "Save and Publish" actions fail due to a publication freeze
  • Version 1.9
    • Standalone REST API
    • Added notifications when using the toggleGlobalFreeze command
    • Corrected configuration of request context parameter definitions for enabled freeze commands in the REST command endpoint
  • Version 1.8.1
    • Version 1.8 does not correctly upgrade from earlier versions. Use v1.8.1 instead of 1.8 when updating an installed Freeze version.
  • Version 1.8
    • Fixed  FREEZE-5 - Getting issue details... STATUS
    • Fixed  FREEZE-6 - Getting issue details... STATUS
    • Fixed  FREEZE-7 - Getting issue details... STATUS
    • Fixed  FREEZE-8 - Getting issue details... STATUS
    • Fixed  FREEZE-9 - Getting issue details... STATUS
  • Version 1.7
    • Fixed  FREEZE-4 - Getting issue details... STATUS
  • Version 1.6
    • added notifications when freeze is started and ended
  • Version 1.5
    • Fixed widgetset warnings
  • Version 1.4
    • Freeze state now exposed through MgnlContext.
    • Commands changed to update freeze state parameter.
    • Rest endpoints update for freeze state parameter.
  • Version 1.3 - Initial release of the extensions version of the module.

3 Comments

  1. The required Maven-repo currently seems to be https://nexus.magnolia-cms.com/content/repositories/magnolia.incubator.releases/

    It would be nice if that info was included in this page...

    1. I added a note to the bottom of the installation section of each module.

    2. Just to let you know. It's no longer required to do this. Recently we made some adjustments in the nexus. It does not hurt to have that repo listed in your settings file but now it would be redundant.