com.dotcms.ruleengine.velocityscriptingactionlet

com.dotcms.ruleengine.velocityscriptingactionlet

Purpose

This plugin adds a Rules Engine actionlet that executes Velocity script during rule evaluation.

What This Plugin Does

• Registers VelocityScriptingActionlet as a custom rule actionlet.
• Accepts a Velocity script parameter and evaluates it in web context.
• Supports quote placeholders and logs errors if script evaluation fails.

When a Customer Might Use This

• Rule behavior needs dynamic logic that changes without rebuilding Java code.
• You need to inspect or manipulate request-context data inside rules.
• You want a reference for custom Rule Actionlet registration and parameter handling.

How to build this example

To build the JAR, run the following Maven command:

mvn clean install

This will generate the plugin JAR in the target directory.

How to install this bundle

• To install this bundle:

  Copy the bundle JAR file inside the Felix OSGI container (dotCMS/felix/load).

  OR

  Upload the bundle JAR file using the dotCMS UI (CMS Admin -> Plugins -> Upload Plugin).

• To uninstall this bundle:

  Remove the bundle JAR file from the Felix OSGI container (dotCMS/felix/load).

  OR

  Undeploy the bundle JAR using the dotCMS UI (CMS Admin -> Plugins -> Undeploy).

How to create a bundle plugin for Annotation Framework based on AOP

In order to create this OSGI plugin, Maven is configured to generate the META-INF/MANIFEST.MF file automatically. If needed, you can customize the configuration in the pom.xml.

Below is a description of the required fields in the MANIFEST.MF and how they are configured in a pom.xml:

Bundle-Name: The name of your bundle
Bundle-SymbolicName: A short and unique name for the bundle
Bundle-Vendor: The vendor of the bundle (example: dotCMS)
Bundle-Description: A brief description of the bundle
Bundle-DocURL: URL for the bundle documentation
Bundle-Activator: Package and name of your Activator class (example: com.dotmarketing.osgi.actionlet.Activator)
Export-Package: Declares the packages that are visible outside the plugin. Any package not declared here has visibility only within the bundle.
Import-Package: This is a comma-separated list of the names of packages to import. This list must include the packages that you are using inside your OSGI bundle plugin and are exported and exposed by the dotCMS runtime.

These fields are configured in the pom.xml as follows:

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <version>5.1.9</version>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <Bundle-Name>Your Bundle Name</Bundle-Name>
            <Bundle-SymbolicName>com.example.yourbundle</Bundle-SymbolicName>
            <Bundle-Vendor>dotCMS</Bundle-Vendor>
            <Bundle-Description>dotCMS - OSGI Actionlet example</Bundle-Description>
            <Bundle-DocURL>https://dotcms.com/</Bundle-DocURL>
            <Bundle-Activator>com.dotmarketing.osgi.actionlet.Activator</Bundle-Activator>
            <Export-Package>com.example.yourbundle.package</Export-Package>
            <Import-Package>*</Import-Package>
        </instructions>
    </configuration>
</plugin>

Beware (!)

In order to work inside the Apache Felix OSGI runtime, the import and export directives must be bidirectional:

• Exported Packages

  The dotCMS must declare the set of packages that will be available to the OSGI plugins by updating the file: dotCMS/WEB-INF/felix/osgi-extra.conf. This can also be configured using the dotCMS UI (CMS Admin -> Plugins -> Exported Packages).

  Only after the exported packages are defined in this list, can a plugin import the packages to use them inside the OSGI bundle.

• Fragment (Deprecated)

  Previously, a bundle fragment was used to make its contents available to other bundles by exporting 3rd party libraries from dotCMS. Fragments do not participate in the lifecycle of the bundle and therefore cannot have a Bundle-Activator. As this is no longer required, this section is deprecated.

How to Use

Once the plugin is installed, then :

1. Go to the Rule Engine portlet
2. Add or modify a rule
3. Add this VelocityScriptingActionlet actionlet and type the velocity code as the parameter

Note: If The velocity script uses quotes or single quotes, those should be escaped to avoid a validation error on the rule engine. The quotes can be replaced with this values:

1. For single quotes (‘) replace with ${singleQuote}
2. For double quotes (“) replace with ${quote}

for example if you velocity code is:

<ul> #foreach($con in $dotcontent.pull(“+contentType:News”, 2, “random”)) <li>$con.title</li> #end </ul>

then should pass this code:

<ul> #foreach($con in $dotcontent.pull(${quote}+contentType:News${quote}, 2, ${quote}random${quote})) <li>$con.title</li> #end </ul>