Wiki source code of How to Customize XWiki Without Creating Upgrade Problems

Version 11.4 by Alex Cotiuga on 2026/05/26 09:14

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Siblings
- Content
- Comments
- Attachments
- History
- Information
- Likes

version	line-number	content
1.1	1	{{velocity}}
	2	#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
	3	{{html clean="false"}}
	4
	5	<section class="resource-header" aria-labelledby="hero-title">
	6	<div class="container">
	7	<div class="text-center">
3.1	8	<div class="hero-kicker">
1.1	9	<i class="fa fa-code" aria-hidden="true"></i>
	10	XWiki custom development guidance
	11	</div>
	12	</div>
	13
4.1	14	<h1 id="hero-title">Why XWiki custom development needs structure, documentation and upgrade awareness</h1>
1.1	15
	16	<p class="resource-summary">
2.1	17	XWiki can be adapted to complex business needs. The important part is to keep custom work documented,
	18	versioned and easy to validate during future upgrades.
1.1	19	</p>
	20	</div>
	21	</section>
	22
	23	<section class="resource-page">
	24	<div class="container">
	25	<div class="resource-layout">
3.2	26	<aside class="resource-sidebar" aria-label="Page summary">
	27	<h4>In this guide</h4>
	28	<ul>
	29	<li><a href="#why-customize">Why customize XWiki</a></li>
	30	<li><a href="#where-risk-appears">Where risk appears</a></li>
	31	<li><a href="#safe-model">Safe model</a></li>
	32	<li><a href="#upgrade-validation">Upgrade validation</a></li>
	33	<li><a href="#practical-checklist">Checklist</a></li>
	34	<li><a href="#strategic-advantage">Strategic advantage</a></li>
	35	</ul>
	36	</aside>
1.1	37
	38	<article class="resource-content">
	39
	40	<p>
2.1	41	Many organizations choose XWiki because it can grow beyond a simple documentation space. A platform may start
	42	with pages, attachments and permissions, then evolve into structured applications, approval workflows, custom
	43	dashboards, branded PDF exports, integrations or internal tools built around the company’s real processes.
1.1	44	</p>
	45
	46	<p>
2.1	47	This flexibility is valuable, but it also raises a legitimate concern: will custom development make upgrades
	48	harder? The answer depends less on the existence of custom code and more on the way it is organized. A controlled
	49	customization can remain stable for years. An undocumented change applied directly in production can become a
	50	maintenance problem after the next upgrade.
1.1	51	</p>
	52
	53	<div class="resource-note">
	54	<p>
2.1	55	<strong>The main point:</strong> custom code is not the problem. Uncontrolled custom code is. XWiki can be
	56	customized safely when changes are separated from standard pages, tracked, documented and tested.
1.1	57	</p>
	58	</div>
	59
2.1	60	<h2 id="why-customize">Why XWiki custom development exists</h2>
1.1	61
	62	<p>
2.1	63	Avoiding all customization may look safer at first, but it can create other costs. Users may start maintaining
	64	side spreadsheets, sending approvals by email, duplicating data in external tools or bypassing the wiki because
	65	it does not match their daily work. In these cases, a well-designed XWiki customization can simplify the process
	66	and improve adoption.
1.1	67	</p>
	68
	69	<p>
2.1	70	Typical examples include custom metadata for documents, templates for recurring content, dashboards for teams,
	71	approval flows, notifications, PDF layouts, page actions, UI extensions, macros and integrations with systems
	72	such as authentication providers, ticketing tools, storage services, CRM platforms or AI assistants. These
	73	features can be implemented at different levels, from wiki pages and scripts to packaged Java extensions.
1.1	74	</p>
	75
2.1	76	<h2 id="where-risk-appears">Where customization becomes risky</h2>
1.1	77
	78	<p>
2.1	79	Problems usually appear when nobody can quickly explain where a customization is implemented, why it exists or
	80	how it should be tested. Business logic mixed into regular content pages, standard pages changed without notes,
	81	scripts that exist only in production, hardcoded group names or missing upgrade checks are common signs that the
	82	customization process needs more structure.
1.1	83	</p>
	84
	85	<p>
2.1	86	This is especially important in XWiki because custom logic can live in several places: classes, objects, sheets,
	87	templates, Velocity or Groovy scripts, panels, UI extensions, macros, scheduled jobs and Java components. The
	88	flexibility is useful, but each important customization should have a clear location and a clear maintenance
	89	path.
1.1	90	</p>
	91
2.1	92	<h2 id="safe-model">A safer model for XWiki custom work</h2>
	93
	94	<h3>1. Keep custom code separate from standard XWiki pages</h3>
1.1	95	<p>
2.1	96	Custom classes, scripts, templates and configuration should usually live in dedicated technical spaces, for
	97	example a company-specific <code>Code</code>, <code>Applications</code>, <code>Templates</code> or
	98	<code>Config</code> area. This makes it easier to see what belongs to the standard distribution and what belongs
	99	to the organization.
1.1	100	</p>
	101
2.1	102	<h3>2. Document the purpose, not only the implementation</h3>
1.1	103	<p>
2.1	104	A short technical note is often enough: what the customization does, who uses it, where it is implemented, what
	105	assumptions it makes and what should be checked after an upgrade. This turns custom work from a hidden script
	106	into a maintainable part of the platform.
1.1	107	</p>
	108
2.1	109	<h3>3. Track important changes in a version control system</h3>
1.1	110	<p>
2.1	111	Serious custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
	112	deployment files and important templates should be stored in a version control system, such as Git. This gives
	113	the team a history of what changed, when it changed and why.
1.1	114	</p>
	115
2.1	116	<h3>4. Choose the right implementation level</h3>
1.1	117	<p>
2.1	118	Many useful features can start as wiki-based customizations using XWiki classes, sheets, templates, Velocity or
	119	UI extensions. When a feature becomes complex, reusable or business-critical, packaging it as an extension is
	120	often a better long-term option. Event listeners, custom services, scheduled jobs, integrations and advanced
	121	workflow logic usually benefit from this approach.
1.1	122	</p>
	123
2.1	124	<h3>5. Keep configuration outside the code</h3>
1.1	125	<p>
	126	Group names, target spaces, template references, email recipients, external URLs and workflow settings should
2.1	127	not be hardcoded when they are likely to change. Configuration pages or preference objects make the feature
	128	easier to adapt without rewriting the implementation.
1.1	129	</p>
	130
2.1	131	<h2 id="upgrade-validation">Validate custom features during upgrades</h2>
	132
1.1	133	<p>
2.1	134	A successful upgrade is not only one where XWiki starts and standard pages load. The upgrade plan should also
	135	include the features that make the instance specific to the organization: custom dashboards, templates, macros,
	136	workflows, permissions, notifications, PDF exports, scheduled jobs and integrations.
1.1	137	</p>
	138
	139	<p>
2.1	140	For each important customization, the team should know what to test and what a successful result looks like. A
	141	staging environment or temporary clone is usually the safest place to run this validation before production is
	142	touched.
1.1	143	</p>
	144
2.1	145	<div class="resource-note">
	146	<p>
	147	<strong>A practical rule:</strong> production can receive urgent fixes when necessary, but it should not become
	148	the only place where the real version of a customization exists. After the emergency, the change should be
	149	reviewed, documented and added to the normal maintenance process.
	150	</p>
	151	</div>
1.1	152
2.1	153	<h2 id="practical-checklist">A compact checklist</h2>
1.1	154
2.1	155	<ul class="resource-checklist">
	156	<li>Separate custom pages, scripts and configuration from standard XWiki content.</li>
	157	<li>Document the business purpose, technical location and validation steps.</li>
	158	<li>Use a version control system, such as Git, for code and important assets.</li>
	159	<li>Test custom features on staging before production upgrades.</li>
	160	<li>Review old customizations and remove what is no longer used.</li>
1.1	161	</ul>
	162
	163	<h2 id="strategic-advantage">Custom code can become a strategic advantage</h2>
	164
	165	<p>
2.1	166	Many useful platform features start as custom development for one concrete need. A workflow, dashboard,
	167	integration or structured application may first solve a private business problem, then become a reusable
	168	internal component or even a public extension. This is how practical solutions often mature.
1.1	169	</p>
	170
	171	<p>
2.1	172	The goal is not to customize everything. The goal is to customize the right parts, in a way that can be
	173	understood and maintained later. When custom work is separated, documented, versioned and tested, XWiki can stay
	174	flexible without becoming fragile.
1.1	175	</p>
	176
11.2	177	<div class="resource-note">
	178	<p>
	179	Related resources:
11.4	180	<a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
11.2	181	and
11.3	182	<a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>
11.2	183	</p>
	184	</div>
	185
1.1	186	<div class="resource-cta">
	187	<h3>Need help reviewing XWiki customizations?</h3>
	188	<p>
	189	If your XWiki instance includes custom scripts, dashboards, workflows, templates, integrations or Java
2.1	190	extensions, a customization review can help identify what is safe, what needs documentation and what should be
	191	tested before the next upgrade.
1.1	192	</p>
	193	<a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
	194	</div>
	195
	196	</article>
	197	</div>
	198	</div>
	199	</section>
2.1	200
1.1	201	{{/html}}
	202	{{/velocity}}