Skip to Content

Wiki source code of xwiki-custom-development

Version 1.2 by Agnease on 2026/05/18 18:59
Show last authors
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">
8 <div class="resource-kicker">
9 <i class="fa fa-code" aria-hidden="true"></i>
10 XWiki custom development guidance
11 </div>
12 </div>
13
14 <h1 id="hero-title">How to customize XWiki safely without creating upgrade problems</h1>
15
16 <p class="resource-summary">
17 Custom code does not have to make XWiki fragile. The real risk is unmanaged customization, not customization itself.
18 </p>
19 </div>
20 </section>
21
22 <section class="resource-page">
23 <div class="container">
24 <div class="resource-layout">
25
26 <article class="resource-content">
27
28 <p>
29 XWiki is often selected because it can adapt to real business processes. Teams can start with standard wiki
30 features, then add structured pages, templates, dashboards, workflows, PDF exports, integrations, macros,
31 UI extensions or Java components when the organization needs more than generic content editing.
32 </p>
33
34 <p>
35 This flexibility is a major advantage, but it also creates a common concern: if the platform is customized too
36 much, will future upgrades become expensive or risky? The answer depends less on how much customization exists
37 and more on how that customization is designed, tracked, documented and tested.
38 </p>
39
40 <div class="resource-note">
41 <p>
42 <strong>The main point:</strong> custom development is not the problem. Uncontrolled custom development is.
43 When delivered in a controlled way, custom XWiki features can remain stable across multiple upgrades.
44 </p>
45 </div>
46
47 <h2 id="why-customize">Why organizations customize XWiki</h2>
48
49 <p>
50 Many organizations can use XWiki successfully with standard features. But production platforms often evolve
51 beyond generic pages and spaces. They need to reflect internal processes, compliance requirements, document
52 governance, reporting needs or integrations with other business systems.
53 </p>
54
55 <p>Typical XWiki customizations include:</p>
56
57 <ul>
58 <li>custom document metadata, classes, sheets and templates</li>
59 <li>structured applications for internal processes</li>
60 <li>approval workflows and controlled document lifecycles</li>
61 <li>custom dashboards, reports and LiveData views</li>
62 <li>branded PDF exports and document templates</li>
63 <li>UI extensions, panels, macros and page actions</li>
64 <li>integrations with authentication, storage, CRM, ticketing or AI systems</li>
65 <li>scheduled jobs, notifications and automation</li>
66 </ul>
67
68 <p>
69 Avoiding all customization can create hidden costs: manual workarounds, duplicated tools, weak adoption and
70 processes that remain outside the knowledge platform. The goal is not to customize everything. The goal is to
71 customize the right things in a maintainable way.
72 </p>
73
74 <h2 id="customization-risks">Where customization becomes risky</h2>
75
76 <p>
77 XWiki makes it easy to add logic in wiki pages, Velocity scripts, Groovy scripts, templates, panels, macros,
78 UI extensions and Java components. That power needs discipline. A customization becomes risky when nobody can
79 quickly explain where it is implemented, why it exists and how it should be validated after an upgrade.
80 </p>
81
82 <p>Common warning signs include:</p>
83
84 <ul>
85 <li>business logic mixed directly into regular content pages</li>
86 <li>standard XWiki pages modified without documentation</li>
87 <li>important scripts existing only in production</li>
88 <li>no source control or release history for custom code</li>
89 <li>hardcoded users, groups, page names, URLs or workflow states</li>
90 <li>custom features missing from upgrade validation plans</li>
91 <li>urgent fixes applied in production and never cleaned up later</li>
92 </ul>
93
94 <h2 id="safe-model">A safer model for XWiki custom development</h2>
95
96 <h3>1. Separate custom code from standard XWiki pages</h3>
97 <p>
98 Custom pages, classes, templates, scripts and configuration should usually live in dedicated technical spaces,
99 such as a company-specific <code>Code</code>, <code>Applications</code>, <code>Templates</code> or
100 <code>Config</code> area. This keeps the difference between standard distribution content and company-specific
101 logic clear during upgrades.
102 </p>
103
104 <h3>2. Document each important customization</h3>
105 <p>
106 Every significant customization should have a short technical note: what it does, where it is implemented, who
107 requested it, what pages or components are involved, what assumptions it makes and how it should be tested.
108 </p>
109
110 <h3>3. Track wiki-based customizations</h3>
111 <p>
112 Many practical features can be built directly in the wiki using XWiki classes, objects, sheets, templates,
113 Velocity, Groovy, UI extensions or dashboards. These should still be grouped, documented and exported or
114 versioned when they become important for the business.
115 </p>
116
117 <h3>4. Use Java extensions for larger or long-term features</h3>
118 <p>
119 When a customization becomes complex, reusable or business-critical, a Java extension is often a better
120 long-term solution. This is especially useful for event listeners, custom services, reusable macros, scheduled
121 jobs, integrations, workflow logic, APIs or advanced PDF export behavior.
122 </p>
123
124 <h3>5. Use Git for serious custom development</h3>
125 <p>
126 Important customizations should be stored in source control. Git makes it possible to understand what changed,
127 when it changed, why it changed and whether the change can be safely rolled back or adapted for a new XWiki
128 version.
129 </p>
130
131 <h3>6. Keep configuration separate from code</h3>
132 <p>
133 Group names, target spaces, template references, email recipients, external URLs and workflow settings should
134 not be hardcoded when they are likely to change. Configuration pages or preference objects make the solution
135 easier to adjust without editing the implementation.
136 </p>
137
138 <h3>7. Test custom features during every upgrade</h3>
139 <p>
140 A successful upgrade is not only one where the server starts. Custom dashboards, workflows, macros, PDF exports,
141 notifications, integrations, permissions and scheduled jobs should be part of the validation checklist.
142 </p>
143
144 <h2 id="tracking-checklist">Practical tracking checklist</h2>
145
146 <ul class="resource-checklist">
147 <li>List all important custom pages, templates, sheets, macros, scripts and Java extensions.</li>
148 <li>Identify which customizations are business-critical and which are historical or optional.</li>
149 <li>Move technical logic into dedicated spaces instead of regular content pages where possible.</li>
150 <li>Store Java code, scripts, XAR packages and deployment files in Git.</li>
151 <li>Document the purpose, owner, technical location and validation steps for each customization.</li>
152 <li>Use staging or a temporary clone to test custom features before production upgrades.</li>
153 <li>Review hardcoded references to users, groups, spaces, page names, URLs and external systems.</li>
154 <li>Remove obsolete customizations instead of carrying them through every upgrade cycle.</li>
155 <li>Package larger features as extensions when they become reusable or business-critical.</li>
156 </ul>
157
158 <h2 id="delivery-process">A controlled delivery process</h2>
159
160 <p>
161 Custom code should be treated as part of the platform architecture, not as a temporary patch. A practical
162 delivery process can be simple, but it should be repeatable.
163 </p>
164
165 <ol>
166 <li><strong>Clarify the need:</strong> define the business problem and the users affected.</li>
167 <li><strong>Choose the right implementation level:</strong> wiki pages, scripts, XAR package or Java extension.</li>
168 <li><strong>Develop outside production:</strong> use a development or staging environment for non-trivial work.</li>
169 <li><strong>Track the change:</strong> store code, scripts, configuration and documentation in a maintainable form.</li>
170 <li><strong>Validate the behavior:</strong> test permissions, rendering, workflows, exports, jobs and integrations.</li>
171 <li><strong>Deploy with notes:</strong> record what changed and what should be checked during future upgrades.</li>
172 </ol>
173
174 <h2 id="common-mistakes">Common mistakes to avoid</h2>
175
176 <ul>
177 <li><strong>Changing standard pages without a plan.</strong> Direct changes are harder to compare, explain and preserve.</li>
178 <li><strong>Using production as the development environment.</strong> Quick fixes may be necessary, but they should be reviewed and integrated properly afterwards.</li>
179 <li><strong>Leaving scripts undocumented.</strong> A script that nobody understands becomes a maintenance risk.</li>
180 <li><strong>Hardcoding business assumptions.</strong> Roles, groups, spaces and external systems change over time.</li>
181 <li><strong>Testing only standard XWiki features during upgrades.</strong> Custom behavior is often where the real upgrade risk is found.</li>
182 </ul>
183
184 <h2 id="strategic-advantage">Custom code can become a strategic advantage</h2>
185
186 <p>
187 Some of the most useful solutions in a platform environment start as custom code for a real project. A workflow,
188 dashboard, macro, integration or structured application may begin as a private need, then become a reusable
189 internal product or even a public extension.
190 </p>
191
192 <p>
193 This is why the question should not be whether XWiki custom development should be avoided. The better question
194 is how to make it maintainable. When customizations are separated, documented, versioned and tested, they can
195 help the organization build a knowledge platform that matches its real work instead of forcing users into
196 disconnected tools and manual workarounds.
197 </p>
198
199 <div class="resource-cta">
200 <h3>Need help reviewing XWiki customizations?</h3>
201 <p>
202 If your XWiki instance includes custom scripts, dashboards, workflows, templates, integrations or Java
203 extensions, a customization review can help identify what is safe, what needs documentation and what should
204 be tested before the next upgrade.
205 </p>
206 <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
207 </div>
208
209 </article>
210
211 <aside class="resource-sidebar" aria-label="Page summary">
212 <h4>In this guide</h4>
213 <ul>
214 <li><a href="#why-customize">Why customize XWiki</a></li>
215 <li><a href="#customization-risks">Customization risks</a></li>
216 <li><a href="#safe-model">Safe model</a></li>
217 <li><a href="#tracking-checklist">Tracking checklist</a></li>
218 <li><a href="#delivery-process">Delivery process</a></li>
219 <li><a href="#common-mistakes">Common mistakes</a></li>
220 <li><a href="#strategic-advantage">Strategic advantage</a></li>
221 </ul>
222 </aside>
223
224 </div>
225 </div>
226 </section>
227 {{/html}}
228 {{/velocity}}