What XWiki customization involves
XWiki customization covers a wide range of work, from configuring existing applications and macros to building XClasses, scripts, skins and packaged extensions. The right depth depends on what the business needs the wiki to do. A knowledge base often needs a structured content type so articles carry consistent fields such as product, owner and review date. A department may need a workflow or approval page before content is published. Branding or navigation may need to match the company intranet. Each trigger points to a different layer of the platform, and naming the layer early keeps the scope honest.
The short answer: small configuration is often done in-house by an administrator who knows the wiki's spaces, rights and templates. Custom extensions that must survive upgrades are commonly scoped with a partner for the first build, then handed over to your team with documentation, tests and a support plan. Ask any partner to separate the two in writing, so you can see which work you will own afterward.
Release line matters more for extensions than for content. XWiki publishes a stable line, a long term support (LTS) line and an intermediate LTS line. At the time of research the official Docker image tags were 18.8.0 for stable, 17.10.14 for LTS and 18.4.7 for the intermediate LTS. An extension that works on one line may need changes, or may not be compatible at all, on another. Confirm which line you will run before any build starts, and ask whether each extension has been tested against that exact version.
What the work includes
Customization work for XWiki moves through the same sequence on every engagement: confirm whether an existing extension already covers the need, then design, build, package and document what remains. Each package below produces artifacts your team can review and maintain.
Requirements and extension inventory
Before any code is written, each requirement is checked against existing extensions, including XWiki Pro applications such as Forum, Diagram, Calendar and Pro Macros, and the xwiki-contrib catalog. The output is a decision record per requirement: adopt, configure, build or drop. Confirm licensing and support terms for any paid Pro application before it enters the design.
Data model design with XClasses
Structured data such as project records, contract fields or asset attributes is modeled as XClasses attached to pages through sheets. Field types, validation, default values and page template layouts are decided here, because changing a class after content exists means migrating stored objects. Review how the model will be queried and reported before building forms on top of it.
Scripting and macro development
Custom macros and server-side scripts add behavior to pages, usually in Groovy or Velocity. Each script is reviewed for the rights it needs, because scripting rights are a security boundary in XWiki. Macros are documented with their parameters and tested on the XWiki versions in use, since script APIs can change between lines.
Skins and templates
Branding, navigation and page layouts are delivered as a skin extension or as customized templates and style sheets layered on an existing skin. Keeping changes in a separate skin, rather than editing core resources, limits what must be re-applied after an upgrade. Check accessibility and rendering on the browsers your users run.
Packaging and test and deployment pipeline
Each extension is built as a packaged XAR or JAR artifact from a versioned source repository, then tested and promoted through a pipeline to staging and production. Automated tests cover macros, classes and page rendering where feasible, and each release is installed and removed in a staging wiki first. Confirm which Maven or build tooling your team already runs before choosing the pipeline design.
Documentation and handover
Each extension gets user-facing documentation, an administrator guide and developer notes covering data model, scripts and dependencies. Install and rollback steps are written so an administrator can apply or reverse a release without the original developers. The maintenance guide names the XWiki versions each extension was tested against, so upgrade planning starts from known compatibility.
What drives cost and duration
The table lists the factors that change customization effort in XWiki, why each one matters and how to keep it under control.
| Driver | Why it matters | How to reduce it |
|---|---|---|
| Custom objects and forms | Each class, form and sheet adds schema design, validation, data migration and regression tests. | Reuse existing classes and apps, and limit fields to those that reports and rights rules need. |
| Server-side scripting versus front-end work | Server-side Groovy and Velocity scripts run inside the wiki and need rights review and upgrade testing. Skins and JavaScript need browser testing. | Prefer standard macros and existing apps, keep scripts in small reviewed modules, and limit UI changes to one skin. |
| Integrations with external systems | Each identity, document store or ticketing link adds configuration, credentials, error handling and monitoring. | Confirm which integrations go live first, phase the rest, and check whether the OpenID Connect extension fits before writing custom login code. |
| Edition and licensed Pro apps | Standard is free, but Pro apps such as the Active Directory SSO, Office365 and OnlyOffice connectors are licensed and add setup and support scope. | Settle the app list first, confirm license coverage for each app, and state in the quote which Pro apps are included. |
| Support plan and consulting rate | XWiki SAS lists consulting at 1200 EUR per day, but this rate requires a Business or Enterprise support plan. | Ask whether that support condition applies to your quote before comparing day rates across proposals. |
| Environments and test coverage | Each environment needs its own wiki data, extension versions and regression runs for custom code. | Limit environments to development, test and production, and automate smoke tests for each custom app and script. |
| Compliance evidence | Access reviews, change records and test results for custom code add documentation and sign-off effort. | Agree the evidence list with your assessor early, and generate records from version control and test runs where possible. |
| XWiki versions supported at once | Stable, LTS and intermediate LTS lines differ in extension compatibility, so supporting several lines multiplies test effort. | Standardize production on one line, and confirm extension compatibility with the target version before each upgrade. |
Project phases and outputs
The sequence moves an XWiki customization from an agreed inventory of extensions and requirements to a tested, documented package running on the XWiki line your organization supports.
Inventory extensions and requirements
The team lists every existing or requested extension, application, skin and macro, records its owner, purpose and XWiki line compatibility, and confirms the target stable or LTS line. The output is a decision log that records which items are kept, replaced, or dropped, and why.
Design the data model and rights impact
Structured data is designed as XClasses, object properties and page hierarchy, and each new class or script is mapped to the rights it needs. The output is a data model document and a rights matrix that the security owner reviews before any build starts.
Build a working prototype
A prototype of the highest-risk customization is built on a non-production instance using the same servlet container and database type as production. It is done when the core user flow works, and the team has recorded which behaviors were confirmed and which remain open.
Build and test the package
The approved design is implemented as a versioned package, with unit or integration tests where practical, and scripts reviewed for scripting rights. The output is a tested package with a changelog and a list of test cases, including those that could not be automated.
Test on the target XWiki line
The package is installed on a staging instance that matches the target XWiki stable or LTS line, production data shape and extension set. The check is complete when functional, permission and upgrade-path tests pass and the results are written up for sign-off.
Deploy and hand over
The package is deployed to production under a documented change process, and a runbook covers installation, rollback, upgrade testing and extension review. Handover is complete when the operating team has run the runbook once and accepted the documentation.
What to keep in-house and what to outsource
This table compares each part of XWiki customization by the skill it needs and whether a team usually keeps it internal, shares it or outsources the first build, so you can decide where to staff your own people.
| Work part | Skill it needs | Keep in-house or outsource, and why |
|---|---|---|
| Business requirements and content ownership | Knowledge of processes, content owners and approval rules | Keep in-house. Only your team knows which spaces, workflows and records matter and who signs off on them. |
| XClass and template design | Data modeling, form and template design, familiarity with the wiki's content structure | Often shared. Your team defines the fields and meaning, while a partner can speed up the first structure and template set. |
| Groovy or Velocity scripting | Server-side XWiki scripting, script rights handling, secure coding for wiki content | Often outsourced for the first build. Keep a skilled internal reviewer who can read and maintain the scripts afterward. |
| Java extension development | Java, XWiki component model, build tooling and knowledge of extension APIs | Often outsourced for the first build. Internal ownership of the source, build and release process should be agreed from the start. |
| Skin and CSS work | Front-end skills, CSS, XWiki skin structure and accessibility checks | Shared or outsourced. Brand decisions stay internal, while technical skin work can be contracted and handed over with documentation. |
| Test automation | Test design, browser automation and regression testing of wiki pages and macros | Shared. Internal staff should own the acceptance tests, and a partner can build the initial automated suite. |
| Container and servlet tuning | Linux, container runtime, Tomcat and JVM tuning, database connection management | Often shared. Platform engineers keep operational control, while tuning help can be scoped as a defined task. |
| Upgrade testing of custom code | Release notes review, extension compatibility checks, regression testing on a staging copy | Keep ownership in-house. Your team must decide to adopt or drop each extension after testing against each target XWiki line. |
What usually goes wrong
Most XWiki customization problems appear months after go-live, during an upgrade, an audit or a staff change. The patterns below are the ones we see most often, each with the check that prevents it.
Extensions broken by a later upgrade
Extensions and custom applications are often built and tested against one XWiki line, then fail when the platform moves to a later release. Pin the XWiki version each extension was tested against, and record that pairing in your change log. Before any upgrade, run the extension set on a staging copy and confirm each one loads and renders its macros.
Custom code that bypasses rights
Scripts that read or write pages through low-level API calls can skip the access checks that the wiki's rights model applies to normal users. The result is content visible to people who should not see it. Review each custom script for the API calls it makes, and test it with a user who lacks the relevant rights.
Scripts with excessive rights
Some scripts run with programming rights that are granted to a broader group than the script needs, so any editor who can reach that code can act with those powers. Inventory every page that holds script or programming rights, limit grants to named administrators, and remove rights that a script no longer uses.
Unmaintained third-party extensions
Extensions installed from the public catalog may have no recent release, no owner responding to issues, or unresolved security reports. Keeping them in production creates a dependency that nobody can fix. Before adoption, check the last release date, the open issue history and the license. Plan a replacement or an internal fork for any extension you cannot support.
Customizations that exist only in the live instance
Some teams edit pages, templates and application code directly in the running wiki, with no copy in version control. A failed edit, a lost instance or a departing developer can leave no way to rebuild the change. Export custom applications and skins into a repository, require review for changes, and restore the repository state on a test instance regularly.
Hard-coded URLs and database assumptions
Templates and scripts that embed host names, ports or database-specific SQL break when the domain changes, a reverse proxy is added or the database engine differs between environments. Use configuration and relative references, keep SQL out of custom code where possible, and test the same build against each database variant you plan to run.
How the work changes by starting point
A new install is the cleanest starting point because extension choices can be made before any content depends on them. Most of the effort goes into decisions made before the first build.
- Pick the release line first. Choose between stable, LTS and intermediate LTS, since the extension compatibility you test depends on that choice. Confirm current tags on the official image pages before pinning.
- Choose the database image variant. The official images come in MySQL, PostgreSQL and MariaDB variants, each running on Tomcat. Standardize on the database your team already operates.
- Keep an extension register. Record every extension, its version and its owner from day one so later upgrades start from a known list.
- Decide on skins and applications early. Custom skins and applications are among the costlier items to change after content is built, so settle them during design.
An instance that has grown through scripts and macros usually needs an inventory before any rebuild. The work is mostly sorting: what still runs, what duplicates a maintained extension and what nobody owns.
- Inventory every script and macro. Identify Groovy, Velocity and wiki macros, and note which pages or other macros call them.
- Review scripting rights. Code that runs with script rights can read or change data broadly, so review who can edit it before moving anything.
- Replace duplicates with extensions. Where a maintained extension covers the same need, plan the swap and compare the output with the original.
- Retire and document. Remove dead code deliberately, then document what remains with an owner and a test to run before each upgrade.
Users arriving from a commercial wiki expect familiar features on day one. Some features will map to XWiki Standard, some to extensions and some to XWiki Pro applications, so the feature list drives the design.
- Build a feature map. List each feature users rely on and mark whether XWiki Standard covers it, an extension covers it or it needs custom work.
- Check paid application scope. XWiki Pro lists applications such as File Manager, Forum, Polls and Calendar. Confirm current licensing with XWiki SAS before assuming any of them fit the plan.
- Test with representative content. Migrated pages may depend on macros from the source tool, so sample representative pages early.
- Confirm identity expectations. Single sign-on and group mapping need the same decisions in every move, so agree them before the pilot.
When extensions are baked into images, every extension change becomes an image build, test and rollout. The work shifts from the wiki administration console to the build pipeline.
- Pin the base image tag. Use a specific tag from the release line you chose, not a floating one, so rebuilds are reproducible.
- Match the database variant to operations. The MySQL, PostgreSQL and MariaDB images run on Tomcat. Confirm the amd64 or arm64v8 architecture your nodes use before building.
- Version extensions in the build. Record the checksum and version of each extension included in the image, and rebuild on every security release.
- Externalize configuration. Keep database credentials and settings in Kubernetes secrets and config maps so one image runs in several environments.
- Confirm persistent storage. Attachments and search data must survive pod restarts, so agree the volume design with your platform team.
Where the network blocks outbound access, every image, extension and dependency must be transferred in, verified and recorded before installation. Extension dependencies are the most common source of delay.
- Mirror images and packages. Transfer the chosen image tags and extension packages through your approved media process, and record their digests.
- Resolve dependencies offline. Extensions can pull in other libraries, so build a complete offline set and test that the instance starts without external calls.
- Verify provenance. Check signatures or checksums against the source before import, and keep the evidence with your change records.
- Plan updates as controlled imports. Each security release becomes another transfer, so agree the cadence and approval path up front.
The official images are licensed under LGPL 2.1, so include the images and extensions in your license review.
What you need to provide
Before any extension work starts, the client must supply a staging instance on the same XWiki line as production. If staging runs a different stable, LTS or intermediate LTS release, every custom application and skin test will prove little about production. Confirm the exact release tag with your DeployOpen lead and keep staging's servlet container and database variant matched to production as well.
Provide a copy of representative content and user data, with written handling rules covering who may access it, where it may be stored, how long it is kept and how personal data is masked. Custom applications often depend on real page structures, object classes and attachment patterns, so a sample that omits them will hide defects. Name the business owners who can approve data models and screen layouts, and make sure they are available for review during build, not only at sign-off.
Supply a source repository the team can use for extension code, templates, XAR packages and configuration, with branch rules and access for DeployOpen engineers. Also grant access to the identity and integration endpoints the extension will call, such as the directory, the identity provider or external APIs, including test credentials and an agreed network path from staging.
Decide which edition the extensions will run on: XWiki Standard, or XWiki Pro for the business applications and connectors it includes. Confirm this against the Pro application list before design starts, because a dependency on a Pro application changes licensing and support scope. Finally, name who approves rights changes made by extensions and who will own each extension after handover, including upgrade testing and the person accountable for retiring it.
Frequently asked questions
Can our own developers build XWiki extensions without a partner?
Yes, if your developers already know XWiki's extension model, its scripting and Java code, and your release process, they can build extensions in-house. A partner adds the most value when the team is new to XWiki, when the extension touches authentication or permissions, or when the work must finish by a fixed date. Most of the effort sits in requirements, testing against each target XWiki line and maintaining the code after go-live. Check that your team can own those tasks for the life of the extension. DeployOpen can take on any part of this work under a written, fixed scope.
How is the cost of an XWiki extension project set?
Cost follows the written scope, and DeployOpen does not publish a price list, so the quote is the only reliable figure. The main drivers are the number of extensions, the number of integrations they need, the depth of testing across your target XWiki version, and whether documentation and handover are included. Ask the quote to state each deliverable, the environments it covers, which work is one-time, such as design and build, and which work recurs, such as patching for later XWiki releases or retainer support. Also ask how changes to requirements during the work will be priced.
How long does a typical XWiki extension project take?
The duration depends on scope, and it cannot be estimated responsibly without written requirements. A small macro or skin change is a very different job from an application with its own data model, permissions and connectors. Timing also depends on how quickly your team reviews designs, how many environments must be tested, and whether an upgrade falls in the same window. Prepare a list of the extensions, data flows, approval steps and the people who can sign off, along with access to a non-production instance that matches production. The written scope will then state the timeline.
How do we stop custom XWiki code breaking at upgrade time?
Custom code can break at upgrade because it depends on internal APIs, templates and the behavior of other extensions, and these can change between releases. The risk is controlled by keeping customizations small, using documented extension points where they exist, and testing each extension against the target XWiki line in a staging copy. Keep a regression checklist for key spaces and pages, and choose between the stable line and an LTS line deliberately, since that choice sets how often you must retest. Record every custom component in a register so upgrade work is planned rather than discovered.
Should we use an existing Pro application or contrib extension before building?
Check existing options first, because a maintained application or extension often covers common needs. XWiki Pro lists applications such as File Manager, Forum, Polls, Calendar and Ideas, and the xwiki-contrib OpenID Connect extension can authenticate XWiki users against an external provider. Pro applications come under XWiki Pro terms, and contrib extensions are community code, so review license terms, recent maintenance activity and compatibility with your target XWiki line. Build custom code only where the gap is specific to your processes.
What happens to our extension code after handover?
You own the delivered code under the terms in your written agreement, and it should live in a repository you control with documentation, build steps and test cases. Handover should include a design record, a dependency list, deployment instructions and a walkthrough with the team that will maintain it. After that, your team handles patches, upgrades and bug fixes, or a support retainer covers them. Ask the quote to state who holds the repository, what documentation is delivered and what support is included after go-live.
How DeployOpen delivers this
DeployOpen scopes, builds, tests, documents and supports XWiki customizations inside infrastructure you control, so extensions, applications, skins and structured data are designed to survive the version upgrades that follow go-live. Work is agreed as a fixed scope in writing before any build starts.
How we scope
- Inventory the extensions, applications, skins, macros and structured data classes the wiki needs, and separate what exists in XWiki Standard from what must be built.
- Record each customization in the written scope with its owner, target XWiki line (stable or LTS), and the spaces or users it affects.
- Confirm the extension sources you accept, including whether an extension is an official XWiki Pro app or a community contribution, and who approves its use.
How we build
- Model structured data with XWiki classes and sheets so content stays queryable, and keep presentation logic in skins and templates rather than in page content.
- Build custom code as versioned extensions in source control, with documented build steps and rights set on scripts so no page author gains server-side access by accident.
- Test each extension on a staging instance running the same XWiki line, database and servlet container as production before anything is promoted.
How we hand over
- Deliver source repositories, build and packaging instructions, and a record of every extension with its version, dependencies and configuration.
- Document the data model, scripting rights, and any places where custom code overrides default XWiki behavior, so upgrade reviews know where to look.
- Walk your administrators through the upgrade test procedure so your team can rerun extension checks against each new XWiki release.
How we support
- Retest custom extensions against each planned XWiki upgrade in staging before the production change window, and report incompatibilities with a remediation plan.
- Support is available as a retainer for fixes, upgrades and extension maintenance after handover, agreed in writing with its own scope.
- Confirm with your XWiki support plan which vendor-side assistance applies to your installed extensions, since XWiki SAS sets those terms directly.
