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

Magnolia uses commands to publish and unpublish content, send email, flush cache, take backups, import and export data and for many other tasks. Commands can perform duties within the system or connect to external resources. Commands are typically executed by actions or scheduled for execution by the Scheduler module

Characteristics of commands:

  • Independent of the UI
  • Back-end executable
  • Executed by UI (for example by an action), Web services or other modules such as the Workflow and Scheduler

You can write your own custom commands and execute them on-demand or scheduled.

Commands consist of a command definition and Java business logic. Since the business logic is written in Java, you can perform basically any task that Java allows.

Command definition

A command definition makes the command available to the system.

Here are the command definitions for the basic commands that are used throughout Magnolia, configured in Configuration > /modules/ui-admincentral/commands/default.

Node nameValue
 ui-admincentral
 

 commands

 

 default

 

 markAsDeleted

 

 class

info.magnolia.commands.impl.MarkNodeAsDeletedCommand

 enabled

true

 export

 

 class

info.magnolia.importexport.command.JcrExportCommand

 import

 

 class

info.magnolia.importexport.command.JcrImportCommand

 delete

 

 deactivate


 class

info.magnolia.module.activation.commands.DeactivationCommand

 enabled

true

 delete


 class

info.magnolia.commands.impl.DeleteCommand

 enabled

true

 restorePreviousVersion


 class

info.magnolia.commands.impl.RestorePreviousVersionCommand

 enabled

true

 exportYaml


 class

info.magnolia.commands.ExportJcrNodeToYamlCommand

Catalogs

Commands are organized into catalogs. A catalog is an intermediate folder in the configuration hierarchy. It resides under the commands folder and contains commands. Catalogs are used to distinguish multiple commands with the same name. For example, the activation module has two command catalogs: default and versioned. This configuration is in the Configuration app > /modules/activation/commands.

Node nameValue
 activation
 

 commands

 

 default

 

 activate

 

 versioned

 

 activate

 

 deactivate

 

The advantage of using a catalog is that you can have identically named commands. You might want two activate commands – one for pages and another for assets. To call a command that resides in a catalog, use the catalog name followed by a hyphen, then the command name. For example, you would distinguish the two activate commands by calling one with workflow-activate and the other with default-activate.

Catalog names have to be unique across the system. Magnolia will not merge commands with same name from various catalogs. It will load commands only from one of them. Since the ui-admininterface module has a default catalog, the name is already taken. If you created a default catalog the names would conflict and the system would not load your command. Choose a catalog name that characterizes its commands, such as "messaging" for commands that send emails and notifications. See Querying for catalogs and commands how to check for currently used names.

Chaining commands

Commands can be grouped and executed as a chain. When you call the parent node its child commands are executed one-by-one in the node order from top down.

The activate command in the versioned catalog is an example of this.This configuration is in the Configuration app > /modules/activation/commands/versioned.

It is a group of two commands that are executed one after the other

  1. version creates a new version of the node.
  2. activate delegates to the activate command configured in the default catalog. (warning) Note the use of the commandName property in the <catalog>-<command name> format.
Node nameValue
 activation
 

 commands

 

 default

 

 activate

 

 class

info.magnolia.module.activation.commands.ActivationCommand

 deactivate

 

 versioned

 

 activate

 

 version

 

 class

info.magnolia.commands.impl.VersionCommand

 enabled

true

 activate

 

 class

info.magnolia.commands.DelegateCommand

 commandName

default-activate

 deactivate

 

 

Executing commands with actions

In the UI commands are executed by actions. Here's an example action definition for the activate action in the Pages app. You can find it in Configuration > /modules/pages/apps/pages/subApps/browser/actions/activate. See Dialog action definition for the properties and their values.

Node nameValue

 modules

 

 pages

 

 apps

 

 pages

 

 subApps

 

 browser

 

 actions

 

 activate

 

 catalog

website

 class

info.magnolia.ui.framework.action.ActivationActionDefinition

 command

activate

 icon

icon-publish

Scheduling

You can use the Scheduler module to execute commands at a given time. You could for example activate a press release on a certain day, take a weekly backup of content, or synchronize a taxonomy of terms with an external source. There is an example configuration in the Configuration app > /modules/scheduler/config/jobs/demo that you can adapt to suit your needs

  • params: Parameters passed to the command. Depends on the command. For example, the activate command expects to receive a repository name and a content path as parameters.
  • catalog: Name of the catalog where your command resides.
  • command: Name of the command.
  • description: Describes the job, for example "Send an email message on the hour"
  • cron: Schedule that indicates the execution time, written as a CRON expression. For example 0 0 1 5 11 ? 2010 means "run on November 5 at 01:00 am". Cronmaker is a useful tool for building expressions.
  • active: Set value to true to activate the job.
Node nameValue
 scheduler
 

 config

 

 jobs

 

 demo

 

 params

 

 path

/news

 repository

website

 active

 false

 catalog

 website

 command

 activate

 cron

 0 0 * * * *

 description

 activate each hour the page news.html

Observation

You can use the Observation module to listen to events in the repository and execute a command in reaction.

Use observation to automate tasks such as publishing newly added assets or sending an email notification when a comment is added.

See Observation module for usage examples.

Querying for existing catalogs and commands

To query for existing commands:

  1. Go to Tools > JCR Queries.
  2. In the Query area, select config repository, sql query language and nt:base result item type.
  3. Paste the following query into the box: "select * from nt:base where jcr:path like '%/commands/%'".
  4. Click Execute.

The result looks like this. Path notation: /modules/moduleName/commands/catalog/command.

71 nodes returned in 24ms
/modules/activation/commands/default
/modules/activation/commands/default/activate
/modules/activation/commands/default/deactivate
/modules/activation/commands/versioned
/modules/activation/commands/versioned/activate
/modules/activation/commands/versioned/activate/version
/modules/activation/commands/versioned/activate/activate
/modules/activation/commands/versioned/deactivate
/modules/activation/commands/versioned/deactivate/version
/modules/activation/commands/versioned/deactivate/deactivate
/modules/ui-admincentral/commands/default
/modules/ui-admincentral/commands/default/markAsDeleted
/modules/ui-admincentral/commands/default/export
/modules/ui-admincentral/commands/default/import
/modules/ui-admincentral/commands/default/delete
/modules/cache/commands/cache
/modules/cache/commands/cache/flushAll
....

Executing a command in the Groovy console

Use the Groovy console to execute command business logic manually, in ad hoc fashion. This is a quick way to test a custom command before you compile it as a Java class.

  1. Go to Dev > Groovy.
  2. Issue the following commands in the console:
cm = info.magnolia.commands.CommandsManager.getInstance()
command = cm.getCommand('activate') 
command.setRepository('website') 
command.setPath('/travel/about/careers') 
command.setRecursive(true)
command.execute(ctx) 

This example activates the page /travel/about/careers. You can test it by making a small change on the careers page, executing the Groovy commands, and viewing the modified history page on the public instance.

The execute() method is passed a Magnolia context instance ctx which is an implicit object the console always puts at your disposal.

 

Executing a command as a Groovy script

You can also save a command as a Groovy script. This is more comfortable than writing and executing one line at a time in the console. Groovy scripts can be run from the dialog used to edit them.

  1. Go to Dev > Groovy.
  2. Click New Script.
  3. Double-click the script name to change it.
  4. Double-click the script icon to edit it.
  5. Paste the example activation commands from above into the Source box.
  6. Check the Is a script? box.
  7. Check the Enabled box.
  8. Click Run.

Creating a custom command

You can write your own custom commands and execute them either on demand or scheduled. For example, you could execute the standard Magnolia sendMail command when a page is activated. This way you can send an email notification to a user who needs to review the page.

Definition

To create a command definition:

  1. Create a commands folder in the configuration hierarchy of your module.

  2. Create a catalog subfolder under the commands folder. Choose a catalog name that characterizes its commands, such as messaging for commands that send emails and notifications.

  3. Create a content node under the catalog. This is the name of your command in Magnolia. If you did not create a catalog make sure that your command name is unique across Magnolia.
  4. Create a class property. Set its value to the fully-qualified name of the Java class that contains the command logic such as info.magnolia.module.mail.commands.MailCommand. The Java class should reside inside the module JAR.
Node nameValue

 modules

 

 myModule

 

 commands

 

 myCatalog

 

 myCommand

 

 class

com.example.modules.acme.commands.MyCommand

You don't necessarily need to create a new module if you just want to add a command. You can put the command definition into any existing module and copy the class file to WEB-INF/classes under the Magnolia webapp. However, it is easier to maintain your own classes, templates and configuration when you organize them in a module rather than leaving them scattered around.

Class

A command is typically implemented as a Java class. You probably want to extend BaseRepositoryCommand which provides useful methods for working with the repository.

MyCommand.java
public class MyCommand extends BaseRepositoryCommand {
  public boolean execute(Context context) {
    // Your command logic goes here.
  }
}

See the commands in the info.magnolia.commands.impl package for examples.