Commands
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:
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
.
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 publishing-core
module has
two command catalogs: default
and versioned
. This configuration is
in the Configuration app > /modules/publishing-core/commands
.
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 publish commands by calling one with
workflow-publish
and the other with default-publish
.
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 publish
command in the versioned
catalog is an example of this. This configuration is in the Configuration app > /modules/publishing-core/commands/versioned
.
It is a group of two commands that are executed one after the other:
-
version
creates a new version of the node. -
publish
delegates to thepublish
command configured in thedefault
catalog.
Note the use of the commandName property in the <catalog>-<command name> format.
|
Executing commands with actions
In the UI, commands are executed by actions. Here is 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
Action definition for
the properties and their values.
Scheduling
You can use the Scheduler
module to execute commands at a given time. You could for example
publish 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, theactivate
command expects to receive arepository
name and a contentpath
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 example0 0 1 5 11 ? 2010
meansrun on November 5 at 01:00 am
. Cronmaker is a useful tool for building expressions. -
active
: Set value totrue
to activate the job.
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:
-
Open the JCR Tools app.
-
In the Query tab, select
config
workspace,sql
query language andnt:base
result item type. -
Paste the following query into the Statement box:
select * from nt:base where jcr:path like '%/commands/%'
. -
Click Execute.
The result looks like this. Path notation:
/modules/moduleName/commands/catalog/command
.
101 nodes returned in 24ms
/modules/publishing-core/commands/default
/modules/publishing-core/commands/default/publish
/modules/publishing-core/commands/default/unpublish
/modules/publishing-core/commands/default/activate
/modules/publishing-core/commands/default/deactivate
/modules/publishing-core/commands/versioned
/modules/publishing-core/commands/versioned/publish
/modules/publishing-core/commands/versioned/publish/version
/modules/publishing-core/commands/versioned/publish/publish
/modules/publishing-core/commands/versioned/unpublish
/modules/publishing-core/commands/versioned/unpublish/version
/modules/publishing-core/commands/versioned/unpublish/unpublish
/modules/publishing-core/commands/versioned/activate
/modules/publishing-core/commands/versioned/deactivate
/modules/rest-services/rest-endpoints/commands/enabledCommands
/modules/rest-services/rest-endpoints/commands/enabledCommands/activate
/modules/rest-services/rest-endpoints/commands/enabledCommands/activate/access
/modules/rest-services/rest-endpoints/commands/enabledCommands/activate/access/roles
/modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted
/modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted/access
/modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted/access/roles
/modules/rest-services/rest-endpoints/commands/enabledCommands/backup
/modules/rest-services/rest-endpoints/commands/enabledCommands/backup/access
/modules/rest-services/rest-endpoints/commands/enabledCommands/backup/access/roles
/modules/ui-framework/commands/default
/modules/ui-framework/commands/default/importZip
....
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. Both of the two options below publish 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.
-
Open the Groovy app.
-
Issue the following commands in the console:
-
Option A - Calling the
info.magnolia.commands.CommandsManager.executeCommand()
:map = new java.util.LinkedHashMap<String, String>() map.put("path", "/travel/about/careers") map.put("repository", "website") cm = info.magnolia.commands.CommandsManager.getInstance() cm.executeCommand('default','publish',map)
-
Option B - Passing a
SimpleContextobject
to theexecute()
method:cm = info.magnolia.commands.CommandsManager.getInstance() commandChain = cm.getCommand('activate'); command= commandChain.getCommands().get(0); command.setRepository('website') command.setPath('/travel/about/careers') command.setRecursive(true) command.execute(new info.magnolia.context.SimpleContext())
Using an earlier version than 6.2.22 of Magnolia?
-
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.
-
Open the Groovy app.
-
Click New Script.
-
Double-click the script name to change it.
-
Double-click the script icon to edit it.
-
Paste the example activation commands from above into the Source box.
-
Check the Is a script? box.
-
Check the Enabled box.
-
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 published. This way you can send an
email notification to a user who needs to review the page.
Definition
To create a command definition:
-
Create a
commands
folder in the configuration hierarchy of your module. -
Create a
catalog
subfolder under thecommands
folder. Choose a catalog name that characterizes its commands, such asmessaging
for commands that send emails and notifications. -
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.
-
Create a
class
property. Set its value to the fully-qualified name of the Java class that contains the command logic such asinfo.magnolia.module.mail.commands.MailCommand
. The Java class should reside inside the module JAR.
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 info.magnolia.commands.impl.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.