xWiki Scripting Engine: Velocity, Groovy, and Python Guide

Three Scripting Languages, One Powerful Platform

xWiki's extensibility is one of its defining characteristics, and at the heart of that extensibility lies a multi-language scripting engine that gives administrators and developers the power to customize, automate, and extend the platform far beyond its out-of-the-box capabilities. With more than twenty years of development behind it and the trust of over 800 teams worldwide, xWiki has refined its scripting architecture to support three complementary languages: Velocity for template rendering, Groovy for server-side logic, and Python for advanced automation. Each language serves a distinct purpose, and together they provide a comprehensive toolkit for building sophisticated wiki-based applications.

The decision to support multiple scripting languages rather than mandating a single one reflects xWiki's pragmatic engineering philosophy. Different tasks have different requirements. Rendering a dynamic page layout demands a lightweight templating language with minimal overhead. Implementing complex business logic requires a full-featured programming language with access to the Java ecosystem. Automating data processing and external integrations benefits from a language with rich libraries for those specific domains. By providing Velocity, Groovy, and Python, xWiki allows practitioners to choose the right tool for each task rather than forcing compromises.

When you run xWiki on MassiveGRID's managed hosting infrastructure, your scripting workloads execute on enterprise-grade compute resources backed by our 100% uptime SLA, ISO 9001-certified operations, and 24/7 expert support. Our data centers in Frankfurt, London, New York, and Singapore ensure that script execution performance is consistent and reliable regardless of your team's geographic distribution.

Velocity for Template Rendering

Velocity is xWiki's primary templating language, and it is the first scripting language that most xWiki administrators encounter. Originally developed by the Apache Software Foundation, Velocity is a lightweight template engine designed for generating dynamic text output from structured data. In xWiki, Velocity is used extensively for rendering page content, building navigation elements, generating email templates, and creating reusable layout components.

The appeal of Velocity lies in its simplicity and its intentional constraints. Velocity's syntax consists of variable references prefixed with a dollar sign, directives prefixed with a hash, and a small set of control structures for conditionals and iteration. This minimal syntax means that wiki content creators who are not software developers can learn to write effective Velocity templates within hours rather than weeks. The language deliberately omits features like complex object instantiation and direct database access, which keeps templates focused on presentation concerns and prevents them from becoming repositories of business logic.

Dynamic page layouts represent one of the most common applications of Velocity in xWiki. Consider a documentation portal where different sections should display different navigation menus, or a project space where the page header should dynamically show the project's status and owner. With Velocity, these requirements are addressed through templates that query the page's metadata and render the appropriate content.

#set($projectStatus = $doc.getObject('ProjectClass').getProperty('status').value)
#if($projectStatus == 'active')
  <div class="status-badge active">Active Project</div>
#elseif($projectStatus == 'archived')
  <div class="status-badge archived">Archived</div>
#end

Conditional content rendering extends the dynamic layout concept to the content itself. Velocity templates can evaluate user permissions, page properties, or environmental variables to determine which content blocks to display. A single wiki page can present different information to administrators, regular users, and anonymous visitors by wrapping content sections in Velocity conditionals that check the current user's group membership.

Loops enable Velocity templates to generate repetitive content from structured data. A template that lists all child pages of the current page, a navigation macro that renders a hierarchical menu tree, or a summary panel that aggregates statistics from multiple pages all rely on Velocity's iteration directives. The foreach loop iterates over collections returned by xWiki's API, rendering a template fragment for each element.

Reusable templates are perhaps Velocity's most valuable contribution to xWiki productivity. By defining common layout patterns as Velocity macros stored in dedicated template pages, organizations can ensure visual and structural consistency across hundreds or thousands of wiki pages. A change to the template propagates automatically to every page that includes it, eliminating the maintenance burden of manually updating each page.

Groovy for Server-Side Logic

Where Velocity is intentionally simple, Groovy is intentionally powerful. Groovy is a dynamic language that runs on the Java Virtual Machine and provides seamless interoperability with Java libraries. In xWiki, Groovy scripts have access to the full xWiki API, the underlying Java platform, and any Java library that has been added to the xWiki classpath. This makes Groovy the language of choice for implementing complex business logic, data transformations, event handling, custom workflows, and external system integrations.

Complex automation scenarios that would be awkward or impossible in Velocity become straightforward in Groovy. Consider an onboarding workflow where a new employee's wiki account must be created, added to the appropriate groups based on their department, provisioned with a personalized dashboard page populated with relevant links and resources, and notified via email with their access credentials. Each of these steps involves multiple API calls, conditional logic, and error handling that Groovy handles with the expressiveness and robustness of a full programming language.

import com.xpn.xwiki.api.*

def xwiki = xcontext.getWiki()
def userDoc = xwiki.getDocument("XWiki.${username}", xcontext.getContext())
def userObj = userDoc.newObject("XWiki.XWikiUsers", xcontext.getContext())
userObj.set("first_name", firstName)
userObj.set("last_name", lastName)
userObj.set("email", email)
xwiki.saveDocument(userDoc, "Created user account", xcontext.getContext())

Data transformations represent another domain where Groovy excels. Organizations frequently need to restructure, aggregate, or validate data stored across multiple wiki pages. A Groovy script can query the xWiki database using HQL or XWQ, process the results through arbitrary transformation logic, and write the results back to wiki pages or export them to external formats. This capability transforms xWiki from a passive content repository into an active data processing platform.

Event handling allows Groovy scripts to react to changes in the wiki automatically. xWiki's event system fires notifications when pages are created, modified, deleted, or accessed. Groovy event listeners can intercept these events and execute custom logic in response. A listener might enforce naming conventions by validating page titles against a regex pattern, synchronize content changes to an external search index, or trigger approval workflows when documents in regulated spaces are modified.

External API integration is where Groovy's access to the Java ecosystem becomes particularly valuable. Using standard Java HTTP libraries or dedicated client libraries, Groovy scripts can communicate with REST APIs, SOAP services, message queues, and databases. A Groovy script might pull customer data from a CRM, fetch deployment status from a CI/CD pipeline, query a monitoring system for infrastructure metrics, or push wiki content to a content delivery network. These integrations position xWiki as a hub that connects and orchestrates information flows across the organization's technology landscape.

Python for Advanced Automation

xWiki's support for Python scripting through the Jython engine adds another dimension to the platform's extensibility. Python brings its distinctive strengths in readability, rapid prototyping, and an extensive standard library to the xWiki scripting ecosystem. While Python in xWiki runs on the JVM through Jython rather than as native CPython, it retains the language's syntax and most of its standard library, making it immediately accessible to the large community of developers who are already proficient in Python.

Data science workflows benefit from Python's natural expressiveness for data manipulation. Scripts that aggregate wiki content into statistical summaries, generate visualizations from structured data, or perform text analysis on document collections can be written in Python's clean, readable syntax. While Jython does not have access to native Python libraries like NumPy or Pandas, it can interact with external Python services through HTTP APIs, enabling sophisticated data processing pipelines that combine xWiki's content management capabilities with the Python data science ecosystem.

Batch operations are another area where Python's strengths align well with common xWiki administration tasks. Migrating content from legacy systems, bulk-updating metadata across thousands of pages, generating standardized pages from templates, or cleaning up orphaned attachments are all tasks that benefit from Python's concise iteration patterns and string manipulation capabilities. A Python script that would take an experienced developer thirty minutes to write might save hours of manual work and eliminate the human errors that inevitably accompany repetitive tasks.

Integration with external Python tools extends xWiki's reach into ecosystems that are predominantly Python-oriented. Machine learning services, natural language processing APIs, document conversion utilities, and scientific computing frameworks often provide Python SDKs as their primary interface. By supporting Python scripting, xWiki can serve as a front-end and orchestration layer for these services, presenting their capabilities through the wiki's familiar interface while the heavy computational work happens externally.

Deploying and Managing Scripts

The power of xWiki's scripting engine comes with a corresponding responsibility to manage scripts securely and efficiently. xWiki provides a comprehensive framework for controlling who can write scripts, what those scripts can access, and how they perform under load.

Permissions form the first line of defense. xWiki distinguishes between regular page editing and script authoring through its rights management system. Only users with the Programming right can save pages containing Groovy or Python scripts, while Velocity scripting can be restricted to users with the Script right. This tiered permission model ensures that the most powerful scripting capabilities are available only to trusted administrators and developers, while preventing accidental or malicious script injection by regular users.

Sandboxing provides an additional layer of security by restricting what scripts can access at the system level. xWiki's script security framework can prevent scripts from accessing the file system, making network connections to unauthorized hosts, or invoking dangerous Java APIs. These restrictions can be configured per-script or globally, allowing administrators to enforce security policies without eliminating scripting capabilities entirely. The sandboxing configuration should be reviewed and adjusted as part of any security audit, particularly in multi-tenant environments where scripts from one tenant should never be able to access another tenant's data.

Performance optimization for scripts requires attention to both algorithmic efficiency and platform-specific considerations. Velocity templates should avoid complex computations and database queries within loops, as the template rendering phase of page display is latency-sensitive. Groovy scripts that perform heavy processing should be designed to run asynchronously rather than blocking the page rendering pipeline. Python scripts should be mindful of Jython's startup overhead and consider caching results for expensive computations that do not change frequently.

Security best practices for xWiki scripting extend beyond permissions and sandboxing. Scripts should validate all input, particularly when processing data from user-submitted forms or external APIs. Database queries should use parameterized queries rather than string concatenation to prevent injection attacks. Scripts that interact with external services should handle errors gracefully, implement timeouts, and avoid exposing credentials in page source. Organizations should maintain a registry of all active scripts, review them periodically for security vulnerabilities, and establish a code review process for new script submissions.

Deploying xWiki on MassiveGRID's infrastructure provides the compute resources and monitoring capabilities necessary to support intensive scripting workloads. Our managed hosting includes performance monitoring that can identify resource-intensive scripts before they impact user experience, and our 24/7 support team can assist with script optimization and troubleshooting. With data centers in Frankfurt, London, New York, and Singapore, your scripts execute close to your users for minimal latency, and our GDPR-compliant infrastructure ensures that data processed by scripts meets regulatory requirements.

For organizations evaluating xWiki's scripting capabilities alongside other platforms, our comprehensive xWiki versus Confluence enterprise comparison examines how these platforms differ in their approach to extensibility, including the breadth and depth of scripting support. With over 900 extensions available in its ecosystem and support for more than 40 languages, xWiki's scripting engine is a core part of a platform that has been designed from the ground up for customization.

Frequently Asked Questions

Can I run Python directly in xWiki macros?

Yes, xWiki supports Python scripting through the Jython engine, which runs Python code on the Java Virtual Machine. You can write Python scripts directly within xWiki pages using the Python script macro, and they will execute server-side with access to the xWiki API. It is important to note that Jython implements Python 2.7 syntax and includes most of the Python standard library, but it does not support native C extensions such as NumPy or Pandas. For workflows that require those libraries, the recommended approach is to call an external Python service via HTTP from within your xWiki script. Users must have the Programming right to save pages containing Python scripts.

How do I debug Groovy scripts in xWiki?

Debugging Groovy scripts in xWiki involves several complementary techniques. The most immediate approach is to use xWiki's logging framework by calling services.logging.getLogger() to write diagnostic messages to the server log, which you can then review in the xWiki administration panel or directly in the log files. For iterative development, many administrators use a dedicated script testing page where they can modify and execute Groovy code quickly, examining the output rendered on the page. The xWiki REPL extension provides an interactive console for testing Groovy expressions against the live wiki. For more complex debugging, you can configure remote debugging on the xWiki JVM and attach an IDE like IntelliJ IDEA, which provides breakpoints, variable inspection, and step-through execution for Groovy scripts.

What are the security risks of enabling scripting in xWiki?

Enabling scripting in xWiki introduces the same categories of risk that any server-side code execution presents. Scripts with the Programming right can access the full Java API, which means a malicious or poorly written script could read or modify any data in the wiki, access the server's file system, make network connections to external hosts, or consume excessive CPU and memory resources. xWiki mitigates these risks through its tiered permission model, which restricts script authoring to trusted users, and its sandboxing framework, which limits what system resources scripts can access. Best practices include granting the Programming right only to administrators, enabling sandboxing for all non-administrative scripts, reviewing all scripts through a code review process, validating all user input within scripts, and monitoring script execution for resource consumption anomalies. On MassiveGRID's managed infrastructure, our monitoring systems can detect and alert on unusual script behavior, adding an additional layer of protection.