Freeze module

Edition

Incubator (services)

Issues

FREEZE

Git

Git

Latest

2.0

Compatible with Magnolia 6.2, 6.1, 5.7, 5.6.

The Freeze module 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. With these commands, it’s possible to set and unset the freeze flag.

This module is at the INCUBATOR level.

If you are using a version prior to 1.3, the groupId and artifactId are different.

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

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

<dependency>
  <groupId>info.magnolia.freeze</groupId>
  <artifactId>magnolia-freeze</artifactId>
  <version>2.0</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>2.0</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-personalization</artifactId>
  <version>2.0</version>
</dependency>

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

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.

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.
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:

Command Description

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.

rest services freeze enabled

A command issued as a cURL REST call with the POST method must contain a data body too, otherwise the call will fail and return the error 500.

You can use an empty body in this case, for example:

curl -X POST \
 -u <user>:<pass> \
 -H 'Content-Type: application/json' \
 --data '{}' \
 https://<magnolia-url>/.rest/freeze/v1/start

Changelog

Version Notes

2.0

Several updates.

  • 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

1.9

Several updates.

  • 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

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.

1.8

Several fixes.

1.7

Fixed FREEZE-4

1.6

added notifications when freeze is started and ended

1.5

Fixed widgetset warnings

1.4

Several updates.

  • Freeze state now exposed through MgnlContext.

  • Commands changed to update freeze state parameter.

  • Rest endpoints update for freeze state parameter.

1.3

Initial release of the extensions version of the module.
Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Freeze module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules