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. Additionally, this makes your application more secure by not exposing complex objects on the Velocity context which can be leveraged by attackers in the event of an SSTI vulnerability.

You can call any method on your plugin action from Velocity with $action.getComplicatedCustomObject() instead of putting complicated logic in your Velocity template.

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

Inject a PageManager into your action class by using constructor injection (more information on dependency injection).
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.
Add a getCalculatedPages() method to your action, which returns the list of pages.
To get the calculated pages from the action and display them, use $action.calculatedPages.

You should NOT perform data updates or any mutations directly from Velocity templates and it will often be blocked; they should be used purely as a view layer.

Default Velocity context

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

Struts Actions
Macros
Email notifications (with additions - see below)
User macro (with additions - see below)

Variable	Description
`$action`	The current Struts Action Class Reference: Struts Action class, usually a subclass of ConfluenceActionSupport
`$i18n`	`$i18n.getText()` should be used for plugin internationalization. Class Reference: I18NBean
`$dateFormatter`	Provides a date and time formatter suitable for the exporting user's locale and environment. Class Reference: DateFormatter
`$request`	The current servlet request object (if available) Class Reference: HttpServletRequest
`$request.contextPath`	The current context path. Used for creating relative URLs: 1 2 `<a href="$request.contextPath/dashboard.action">Dashboard</a>` Class Reference: String
`$response`	The current servlet response object (avoid accessing in Velocity) Class Reference: HttpServletResponse
`$globalSettings`	Current global settings configuration Class Reference: Settings
`$generalUtil`	A general utility object containing miscellaneous helpful methods Class Reference: VelocityUtil
`$htmlUtil`	Provides methods for HTML and URL encoding Class Reference: HtmlUtil
`$authenticatedUser`	The currently authenticated user, or `null` if unauthenticated Class Reference: ConfluenceUser
`$userAccessor`	For retrieving users, groups and checking membership Class Reference: UserAccessor
`$permissionHelper`	Can be used to check permissions, but it is recommended that you check permission in your action Class Reference: PermissionHelper

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.

In Confluence 7.13.15 LTS, 7.19.7 LTS, 8.2.0 and later versions, the user macro Velocity context is set to include only the generalUtil and htmlUtil variables. To change or add more variables, you will need to configure the system property macro.required.velocity.context.keys. See configuring system properties to learn how.

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.

Variable	Description	Class Reference
`$stylesheet`	Default stylesheet CSS contents	String
`$contextPath`	Same as `$request.contextPath` in the default context	String
`$subject`	The email notification subject	String
`$renderContext`	Notification render context	RenderContext
`$report`	Daily report (only for digest notifications)	ChangeDigestReport
`$showDiffs`	Whether this notification should include diffs	boolean
`$showFullContent`	Whether this notification should include full page content	boolean
`$diff`	Diff for the notification, if enabled	ConfluenceDiff

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.