Commands are custom actions executed at pre-defined trigger points. Magnolia CMS uses commands to 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.

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

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
• Catalogs
• Querying for existing catalogs and commands
• Command business logic (Java)
• Chaining commands
• Scheduling
• Executing a command in the Groovy console
• Executing a command as a Groovy script

Command definition

A command definition makes the command available to the system. To create a definition:

1. Create a commands subfolder in the configuration hierarchy of your module.
   /modules/myModule/commands
   
   
2. Create a catalog subfolder under the commands folder. This an optional but recommended step that helps organize commands. Choose a catalog name that characterizes its commands, such as messaging for commands that send emails and notifications.
   /modules/myModule/commands/myCatalog
   
   
3. Create a content node under the catalog. This is the command. If you did not create a catalog make sure that your command name is unique across Magnolia CMS.
   /modules/myModule/commands/myCatalog/myCommand
   
   
4. Create a class data node. Set its value to the fully-qualified name of the Java class that contains the command's business logic such as info.magnolia.module.mail.commands.MailCommand. The Java class should reside inside the module JAR.

See actual examples of commands in /modules/admininterface/commands.

Catalogs

Commands are organized into catalogs. A catalog is an optional intermediate folder in the configuration hierarchy. It resides under the commands folder and contains commands. For example, the adminInterface module has two command catalogs: default and website.

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 documents. 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 website-activate and the other with default-activate.

Catalog names have to be unique across the system. Magnolia CMS will not merge commands with same name from various catalogs. It will load commands only from one of them. Since the 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.

Querying for existing catalogs and commands

To query for existing commands:

1. In AdminCentral, 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.

119 nodes returned in 65ms
/modules/adminInterface/commands/MetaData  
/modules/adminInterface/commands/default
/modules/adminInterface/commands/default/MetaData
/modules/adminInterface/commands/default/activate
/modules/adminInterface/commands/default/activate/MetaData
/modules/adminInterface/commands/default/deactivate
/modules/adminInterface/commands/default/deactivate/MetaData
/modules/adminInterface/commands/default/sendMail
/modules/adminInterface/commands/default/sendMail/MetaData
/modules/adminInterface/commands/website
/modules/adminInterface/commands/website/MetaData
/modules/adminInterface/commands/website/activate
/modules/adminInterface/commands/website/activate/MetaData

Note that catalog is an optional level. Commands can reside directly under the commands folder too.

Command business logic (Java)

A command is typically implemented as a Java class. The class needs to extend the MgnlCommand class.

public class MyCommand extends MgnlCommand {
  public execute(Context ctx) {
    // Your business logic goes here.
  }
}

Examples of existing commands (SVN):

• info.magnolia.module.admininterface.commands.ActivationCommand
• info.magnolia.module.admininterface.commands.VersionCommand
• info.magnolia.module.workflow.commands.ActivationFlowCommand
• info.magnolia.module.data.commands.ImportCommand

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 website catalog is an example of this. It is a group of three commands that are executed when a user activates a content node such as web page:

1. version creates a new version of the page.
2. startFlow starts an activation workflow.
3. alert sends a workflow notification to the recipient's inbox.

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 syncronize a taxonomy of terms with an external source.

1. In AdminCentral, go to Configuration > Scheduler.
2. Copy the demo content node and paste it as a new node. This is the scheduled job that will launch your command.
3. Rename the job node so that its name indicates what command it launches.
4. Create the following data nodes under the job node. These are the job properties.
• 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.
• 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.

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. Install the Groovy Interactive Shell & Scripting Support module from Magnolia Store.
2. In AdminCentral, go to Tools > Groovy Console.
3. Issue the following commands in the console:

cm = info.magnolia.commands.CommandsManager.getInstance()
command = cm.getCommand('activate') 
command.setRepository('website') 
command.setPath('/demo-project/about/history') 
command.setClone(true) 
command.setRecursive(true)
command.execute(ctx) 

This example activates the page /demo-project/about/history. You can test it by making a small change on the history 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

1. Go to Tools > Scripts in AdminCentral.
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.