Last updated Sep 27, 2023

Rate this page:

Confluence objects accessible from Velocity

Confluence has a few distinct Velocity contexts for different purposes in the application (user macros, email templates, and exports), but the most commonly used context is called the "default context".

Velocity usage guidelines for plugins

To detect deprecation and code change breakages during compilation time, it is recommended that, where possible, you add functionality that calls Confluence code in your plugin Java code (that is, actions or components) rather than in a Velocity template. You can call any method on your plugin action from Velocity with $action.getComplicatedCustomObject() instead of putting complicated logic in your Velocity template that is not checked by the compiler.

For example, if your plugin needs a calculated list of particular pages to display in the Velocity template, you should do the following:

  1. Inject a PageManager into your action class by using constructor injection (more information on dependency injection).
  2. In your action's execute() method, retrieve the desired pages using the pageManager object and store them in a field in your class called calculatedPages.
  3. Add a getCalculatedPages() method to your action, which returns the list of pages.
  4. To get the calculated pages from the action and display them, use $action.calculatedPages.

Although it is currently supported, you should not perform data updates directly from Velocity code, and future versions of Confluence may prevent you doing this in your plugin.

Default Velocity context

The following list highlights the most important entries in the default Velocity context. You can get a full list by calling MacroUtils.defaultVelocityContext(). The default Velocity context is used for templates rendered by:




The current Struts action

Class Reference:

Your action class, normally a subclass of ConfluenceActionSupport


$i18n.getText() should be used for plugin internationalization.

Class Reference: I18NBean


Provides a date and time formatter suitable for the exporting user's locale and environment.

Class Reference: DateFormatter


The current servlet request object (if available)

Class Reference: >HttpServletRequest


The current context path. Used for creating relative URLs:


Class Reference: String


The current servlet response object (should not be accessed in Velocity)

Class Reference: HttpServletResponse


Can retrieve the current global settings with $settingsManager.getGlobalSettings()

Class Reference: SettingsManager

$settingsManager .getGlobalSettings() .getBaseUrl()

The base URL of the Confluence installation. Used for creating absolute URLs in email and RSS:

  Back to Confluence

Class Reference: String


A GeneralUtil object, with useful utility methods for URL encoding etc

Several methods are deprecated. Use htmlUtil.

Class Reference: GeneralUtil


Provides methods for URL encoding

Class Reference: htmlUtil


The currently authenticated user, or null if anonymous user.

Class Reference: ConfluenceActionSupport


For retrieving users, groups and checking membership

Class Reference: UserAccessor


Can be used to check permissions, but it is recommended that you check permission in your action

Class Reference: PermissionHelper


Retrieving attachments

Class Reference: AttachmentManager


Space operations

Class Reference: SpaceManager


Page operations

Class Reference: PageManager

User macro Velocity context

User macros have a Velocity context, which may include any of the above and some additional entries specific to the user macros. See Guide to user macro templates for a list of the latter.

Email notifications using Velocity context

Starting from Confluence 5.2, Soy templates are used instead of Velocity for email notifications.

When you customise the Velocity templates for Confluence email notifications, you can use the following items in addition to the default context.



Class Reference


Default stylesheet CSS contents



Same as $req.contextPath in the default context



The email notification subject



Wiki rendering support



Notification render context for use with $wikiStyleRenderer



Daily report (only for digest notifications)



Whether this notification should include diffs



Whether this notification should include full page content



Diff rendering support



Diff for the notification, if enabled


Export Velocity context

The export context does not include any of the values from the default context. See Available Velocity contexts in exporters for a complete list.

Rate this page: