Scripting OpenCms

OpenCms ships with a shell script for accessing the virtual file system from the command line. This is useful for a lot of administrative tasks like importing modules or exporting content. You can supply scripts that issue commands or use the shell interactively. As the syntax for the scripts is quite limited some tasks can’t be achieved that easily. This blogpost describes a way to circumvent these problems by generating the script files.

I will present a simple extension of this mechanism that makes it possible to access the VFS using the groovy scripting language that also runs on the Java Virtual Machine. It can be useful to import users or content from different systems, create content for test runs or any other task you can think of.

The original script file for accessing the cms shell is located in WEB-INF/cmsshell.sh ( See here on how to make it work on Ubuntu systems). The following file is a modification of the original file that doesn’t call the underlying Java class but another groovy script and should be placed next to the original:

#!/bin/sh
# Script for evaluating groovy scripts with access to opencms.
#
# Please make sure that "servlet-api.jar" and "jsp-api.jar" are found.
#
# get path to opencms base directory
OPENCMS_BASE=`pwd`
# get path to tomcat home
if [ -z "$TOMCAT_HOME" ]; then
        [ -n "$CATALINA_HOME" ] && TOMCAT_HOME="$CATALINA_HOME"
        [ -z "$TOMCAT_HOME" ] && TOMCAT_HOME="$OPENCMS_BASE"/../../..
fi
TOMCAT_CLASSPATH=""
# Support for tomcat 5
for JAR in ${TOMCAT_HOME}/common/lib/*.jar; do
   TOMCAT_CLASSPATH="${TOMCAT_CLASSPATH}:${JAR}"
done
for JAR in ${TOMCAT_HOME}/shared/lib/*.jar; do
   TOMCAT_CLASSPATH="${TOMCAT_CLASSPATH}:${JAR}"
done
# Support for tomcat 6
for JAR in ${TOMCAT_HOME}/lib/*.jar; do
   TOMCAT_CLASSPATH="${TOMCAT_CLASSPATH}:${JAR}"
done
OPENCMS_CLASSPATH=""
for JAR in ${OPENCMS_BASE}/lib/*.jar; do
   OPENCMS_CLASSPATH="${OPENCMS_CLASSPATH}:${JAR}"
done
groovy -classpath "${OPENCMS_CLASSPATH}:${TOMCAT_CLASSPATH}:classes" evalscripts.groovy -base="${OPENCMS_BASE}" "$@"

As you can see, a groovy script named “evalscripts.groovy” is called and all options are passed to it. The script:

import org.opencms.main.CmsShell;
import org.opencms.file.CmsObject;
base = args[0].substring(CmsShell.SHELL_PARAM_BASE.length());
shell = new CmsShell(base, null, null, ">", null) {
    CmsObject getCmsObject() {
        return m_cms;
    }
}
user = "Admin";
pass = "admin";
cms = shell.getCmsObject();
cms.loginUser(user, pass);
binding1 = new Binding();
binding1.setProperty('cmsObject' , cms);
groovyShell = new GroovyShell(binding1);
for (int i = 1; i < args.length; i++) {
    groovyShell.evaluate(new File(args[i]))
}
shell.exit();

We start by creating an instance of the CmsShell class and make the underlying CmsObject accessible. We login using the Admin user and bind the instance so we can use it in the scripts that are doing the real work. This is where you come into play: You can write any groovy script that uses this CmsObject and do whatever you want. Some ideas? Why not create some users:

10.times {
  cmsObject.createUser("User$it", "Pass$it", "", new HashMap());
}

Or list all users:

cmsObject.getUsers().each {
        println it.name
}

How do you use it? You pass the path to the scripts that contain your logic to the shell script and it will execute them automatically. Suppose the shell script is named groovyshell.sh and the groovy files are named createUsers.groovy and listUsers.groovy. Execute them like this:

./groovyshell.sh createUsers.groovy listUsers.groovy

You will see the familiar OpenCms startup sequence followed by the output of the second script:

...
Welcome to the OpenCms shell!
This is OpenCms 7.5.x.
Copyright (c) 2010 Alkacon Software GmbH
OpenCms comes with ABSOLUTELY NO WARRANTY
This is free software, and you are welcome to
redistribute it under certain conditions.
Please see the GNU Lesser General Public Licence for
further details.
help              Shows this text.
help *            Shows the signatures of all available methods.
help {string}     Shows the signatures of all methods containing this string.
exit or quit      Leaves this OpenCms Shell.
Admin
Export
Guest
User0
User1
User2
User3
User4
User5
User6
User7
User8
User9
Goodbye!
...

I think this will be useful for us in the future, maybe also for you?