Commands API
This page describes the commands endpoint, which can be used to
trigger commands defined in
catalogs.
Magnolia uses commands to publish and unpublish content, send email, flush cache, take backups, import and export data and for many other tasks.
The commands:
-
Can perform duties within the system or connect to external resources.
-
Are typically executed by actions or scheduled for execution by the Scheduler module.
| The REST resource must be called with HTTP POST. |
You can only call commands via REST which are whitelisted at
/modules/rest-services/rest-endpoints/commands/enabledCommands. For
further details see
REST
module configuring the commands endpoint and
REST security.
Request URLs
The endpoint recognizes URLs with or without a catalog parameter.
POST /commands/v2/{catalogName}/{commandName}
POST /commands/v2/{commandName}
Parameters
| Parameter | Description | Type | Data Type |
|---|---|---|---|
|
required The name of the command as defined in the Command definition. |
|
|
|
optional, default catalog name is `default` The name of the Command catalog. |
|
|
|
required Request body in JSON or XML format; it contains the parameters required to execute the command. |
|
|
Examples
Here are a couple of examples for publishing content using the commands endpoint.
Publish page
Publish the page /travel/hello.
curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/website/activate \
-H "Content-Type: application/json" \
-X POST --user superuser:superuser \
--data \
'{
"comment": "Published via REST",
"repository": "website",
"path": "/travel/hello",
"recursive": false
}'You cannot send the request as XML, you only can receive the response in
XML with the Accept header.
Schedule page
Publish (activate) the page /travel/hello on a future date.
curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/website/activate \
-H "Content-Type: application/json" \
-X POST --user superuser:superuser \
--data \
'{
"comment": "Published via REST (scheduled)",
"publicationDate": "2020-01-01T11:10:00.000+01:00",
"repository": "website",
"path": "/travel/hello",
"recursive": false
}'Call the markAsDeletedAction command
This example shows how to call the info.magnolia.ui.contentapp.action.MarkAsDeletedCommandActionDefinition command. The following parameters are required for the call context:
-
The name of a repository.
-
The name of the node to be marked.
-
The UUID of the parent node.
curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/markAsDeleted \
-H "Content-Type: application/json" \
-X POST --user superuser:superuser \
--data \
'{
"repository": "dam",
"deleteNode": "google-plus.png",
"uuid": "0234aab2-9a0a-456a-8f0b-fe0a6d4d83ec"
}'Call the flushCachesCommand command
This example shows how to call the info.magnolia.module.cache.commands.FlushCachesCommand command, which completely flushes all caches.
The call context, no parameters are required:
curl http://localhost:8080/magnoliaAuthor/.rest/commands/v2/cache/flushAll \
-H "Content-Type: application/json" \
-X POST --user superuser:superuserWhitelist return properties
This example shows how to configure which data should be sent back using a configuration for contextParameters.
The Groovy command in this example is configured in the ui-admincentral module, as shown below.
| Node name | Value |
|---|---|
⸬ groovy |
|
⬩ class |
samples.commands.RestCommand |
The Groovy command is added to the Groovy app and contains the following script.
package samples.commands;
import info.magnolia.commands.MgnlCommand;
import info.magnolia.context.MgnlContext;
/*
* This groovy class is an example that serves to show how it can be used as a replacement of a traditional Java class on the fly.
*/
public class RestCommand extends MgnlCommand {
@Override
public boolean execute(Context ctx) throws Exception {
MgnlContext.setInstance(ctx);
MgnlContext.setAttribute("foo", "bar");
}
}By specifying foo and request as contextParameters, you can get them sent back after the call below.
Using this configuration, you can block or allow data through depending on what should be returned.
curl https://localhost:8080/magnoliaAuthor/.rest/commands/v2/groovy \
-H "Content-Type: application/json" \
-X POST --user superuser:superuser \
--data \
'{
"request": "Groovy call"
}'{"request":"Groovy call","success":true,"foo":"bar"}