Velocity Script Sub-Action

The Velocity Script Subaction executes Velocity code when a user takes the Workflow Action. The Velocity code executed in the Subaction may include any valid Velocity code (including include of another Velocity file via the #dotParse directive), and may read and change the values of the content item the Workflow Action is executed on.

Usage

Reading Content Field Values

The Velocity code in the Subaction can access the content item the Workflow Action will be executed on, in a Velocity variable named $content. You may access the fields of the content item using the Velocity variable names of the fields, as in the following example:

$content.title

Setting Content Field Values

You may set the values of the fields of the content item as well, as in the following example:

$content.setProperty( "title", "New Title" )

Saving Changes to the Content Item

The Velocity Script Subaction does not save the changes you make to the content item. To save the changes you've made, the Velocity Script Subaction must be followed by a Save content or Save Draft Subaction.

If the Velocity Script Subaction is not followed by a Subaction which saves the content, any changes to the content made by the Velocity Subaction will be lost.

Including a Velocity File Asset

You may include the Velocity script using the #dotParse() Velocity method, enabling you to edit and maintain your code separately from the Workflow Action.

#dotParse('/application/vtl/subaction.vtl')

Displaying a Message to the User

In addition to directly setting the values of fields in the content item, you may also output any text you wish in the Script Code property of the Subaction, and then access that text from other Workflow Subactions that display messages to the user executing the Action (such as the Large Message, Notification, and Notify Assignee Subactions).

By default, any text produced by the Velocity code in the Script Code property will be assigned to a property of the $content object named result. This output can then be accessed from any other Workflow Subaction which can access the content object as $content.result.

You can change the name of the property where the output of the Velocity code are stored by entering a name in the Contentlet Result Property Name property of the Velocity Script Subaction. For example, if you enter codeOutput in the Contentlet Result Property Name field, then you would access the text produced by your Velocity code as $content.codeOutput.

Velocity Script Subaction vs. the Code Property

You may also execute Velocity code using the Code property of the Workflow Action itself. However the Code property is more limited than the Velocity Script Subaction, and its main purpose is to provide backward compatibility with older dotCMS versions; it is recommended that all new Workflow Action code be performed using the Velocity Script Subaction instead.

The following table summarizes differences between using the Code property and the Velocity Script Subaction:

1. Reads the $content object before any Workflow Subactions are executed.
2. Using another Subaction which follows the Velocity Script Subaction.

Examples

Example: Copy Value of One Field to Another

This demonstrates how to create a Workflow Action which copies the value of one field in the content to another field in the content.

The Workflow Action is configured to perform the Velocity Script sub-action, and then Save the content:

The Velocity Script subaction contains just one line, which copies the value from the field with the Velocity variable name sourceValue to the field with the Velocity variable name destinationValue.

So, to make this example work for your Content Type, replace sourceValue and destinationValue with the appropriate Velocity variable names of the fields in your Content Type:

The Velocity Script Subaction just contains the following line of code:

$content.setProperty('destinationValue', $content.sourceValue )

Example: Update Field Value and Display Results

The following Velocity code updates a Content Type field named title in the content item, when the Workflow Action containing the Velocity Script Subaction is executed on it:

## Get the current value of the title field
#set( $oldTitle = $content.title )
## Append a string to the title
#set( $newTitle = "${oldTitle} [Updated]" )
## Update the value of the title in the content item
$content.setProperty( "title", $newTitle )
<p>Title changed from ${esc.q}${oldTitle}${esc.q} to ${esc.q}${newTitle}${esc.q}</p>

Note: For this to work:

• The Velocity Script Subaction must be followed by a Save content or Save Draft Subaction.
• The Content Type must have a Text field with the Velocity variable name title.
• The text displayed by this code (in the last lines) will not be displayed to the user when the Velocity Script Subaction is executed.
  • This text will only be displayed to the user if the Velocity Script Subaction is followed by another Subaction which displays this text.

Displaying the Results

You can display a popup window to the user executing the action, which contains the text (the last line of code) from the above example. To do this, add a Large Message Subaction after the Velocity Script Subaction, which contains the following values (you can leave any properties not listed below at their default values):