Skip to Content
Version 12.3 by Alex Cotiuga on 2026/05/26 10:51
Hide last authors
Alex Cotiuga 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">
Alex Cotiuga 3.1 8 <div class="hero-kicker">
Alex Cotiuga 1.1 9 <i class="fa fa-code" aria-hidden="true"></i>
10 XWiki custom development guidance
11 </div>
12 </div>
13
Alex Cotiuga 4.1 14 <h1 id="hero-title">Why XWiki custom development needs structure, documentation and upgrade awareness</h1>
Alex Cotiuga 1.1 15
16 <p class="resource-summary">
Alex Cotiuga 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.
Alex Cotiuga 1.1 19 </p>
20 </div>
21 </section>
22
23 <section class="resource-page">
24 <div class="container">
25 <div class="resource-layout">
Alex Cotiuga 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>
Alex Cotiuga 12.1 35 <li><a href="#custom-development-faq">FAQ</a></li>
Alex Cotiuga 3.2 36 </ul>
37 </aside>
Alex Cotiuga 1.1 38
39 <article class="resource-content">
40
41 <p>
Alex Cotiuga 2.1 42 Many organizations choose XWiki because it can grow beyond a simple documentation space. A platform may start
43 with pages, attachments and permissions, then evolve into structured applications, approval workflows, custom
44 dashboards, branded PDF exports, integrations or internal tools built around the company’s real processes.
Alex Cotiuga 1.1 45 </p>
46
47 <p>
Alex Cotiuga 2.1 48 This flexibility is valuable, but it also raises a legitimate concern: will custom development make upgrades
49 harder? The answer depends less on the existence of custom code and more on the way it is organized. A controlled
50 customization can remain stable for years. An undocumented change applied directly in production can become a
51 maintenance problem after the next upgrade.
Alex Cotiuga 1.1 52 </p>
53
54 <div class="resource-note">
55 <p>
Alex Cotiuga 12.1 56 <strong>In practice:</strong> XWiki custom development should be separated from standard platform pages,
57 documented, kept under source control, tested on staging and reviewed during upgrades. This makes custom
58 features easier to maintain instead of turning them into hidden dependencies.
59 </p>
60 </div>
61
62 <p>
63 XWiki custom development is the process of adapting the platform with custom pages, classes, objects, sheets,
64 templates, scripts, macros, UI extensions, Java components or integrations. The goal is to support real
65 business processes while keeping the instance understandable, maintainable and upgrade-aware.
66 </p>
67
68 <div class="resource-note">
69 <p>
Alex Cotiuga 2.1 70 <strong>The main point:</strong> custom code is not the problem. Uncontrolled custom code is. XWiki can be
71 customized safely when changes are separated from standard pages, tracked, documented and tested.
Alex Cotiuga 1.1 72 </p>
73 </div>
74
Alex Cotiuga 2.1 75 <h2 id="why-customize">Why XWiki custom development exists</h2>
Alex Cotiuga 1.1 76
77 <p>
Alex Cotiuga 2.1 78 Avoiding all customization may look safer at first, but it can create other costs. Users may start maintaining
79 side spreadsheets, sending approvals by email, duplicating data in external tools or bypassing the wiki because
80 it does not match their daily work. In these cases, a well-designed XWiki customization can simplify the process
81 and improve adoption.
Alex Cotiuga 1.1 82 </p>
83
84 <p>
Alex Cotiuga 2.1 85 Typical examples include custom metadata for documents, templates for recurring content, dashboards for teams,
86 approval flows, notifications, PDF layouts, page actions, UI extensions, macros and integrations with systems
87 such as authentication providers, ticketing tools, storage services, CRM platforms or AI assistants. These
88 features can be implemented at different levels, from wiki pages and scripts to packaged Java extensions.
Alex Cotiuga 1.1 89 </p>
90
Alex Cotiuga 2.1 91 <h2 id="where-risk-appears">Where customization becomes risky</h2>
Alex Cotiuga 1.1 92
93 <p>
Alex Cotiuga 2.1 94 Problems usually appear when nobody can quickly explain where a customization is implemented, why it exists or
95 how it should be tested. Business logic mixed into regular content pages, standard pages changed without notes,
96 scripts that exist only in production, hardcoded group names or missing upgrade checks are common signs that the
97 customization process needs more structure.
Alex Cotiuga 1.1 98 </p>
99
100 <p>
Alex Cotiuga 2.1 101 This is especially important in XWiki because custom logic can live in several places: classes, objects, sheets,
102 templates, Velocity or Groovy scripts, panels, UI extensions, macros, scheduled jobs and Java components. The
103 flexibility is useful, but each important customization should have a clear location and a clear maintenance
104 path.
Alex Cotiuga 1.1 105 </p>
106
Alex Cotiuga 12.1 107 <p>
108 Customizations should also be reviewed as part of the wider platform risk model. See
109 <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
110 for related checks around permissions, authentication, extensions, infrastructure and operational practices.
111 </p>
112
Alex Cotiuga 2.1 113 <h2 id="safe-model">A safer model for XWiki custom work</h2>
114
115 <h3>1. Keep custom code separate from standard XWiki pages</h3>
Alex Cotiuga 1.1 116 <p>
Alex Cotiuga 2.1 117 Custom classes, scripts, templates and configuration should usually live in dedicated technical spaces, for
118 example a company-specific <code>Code</code>, <code>Applications</code>, <code>Templates</code> or
119 <code>Config</code> area. This makes it easier to see what belongs to the standard distribution and what belongs
120 to the organization.
Alex Cotiuga 1.1 121 </p>
122
Alex Cotiuga 2.1 123 <h3>2. Document the purpose, not only the implementation</h3>
Alex Cotiuga 1.1 124 <p>
Alex Cotiuga 2.1 125 A short technical note is often enough: what the customization does, who uses it, where it is implemented, what
126 assumptions it makes and what should be checked after an upgrade. This turns custom work from a hidden script
127 into a maintainable part of the platform.
Alex Cotiuga 1.1 128 </p>
129
Alex Cotiuga 12.1 130 <h3>3. Keep custom code under source control</h3>
Alex Cotiuga 1.1 131 <p>
Alex Cotiuga 12.1 132 Custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
133 deployment files and templates should be stored in a source control system, such as Git. This gives the team a
134 history of what changed, when it changed and why.
Alex Cotiuga 1.1 135 </p>
136
Alex Cotiuga 2.1 137 <h3>4. Choose the right implementation level</h3>
Alex Cotiuga 1.1 138 <p>
Alex Cotiuga 2.1 139 Many useful features can start as wiki-based customizations using XWiki classes, sheets, templates, Velocity or
140 UI extensions. When a feature becomes complex, reusable or business-critical, packaging it as an extension is
141 often a better long-term option. Event listeners, custom services, scheduled jobs, integrations and advanced
142 workflow logic usually benefit from this approach.
Alex Cotiuga 1.1 143 </p>
144
Alex Cotiuga 2.1 145 <h3>5. Keep configuration outside the code</h3>
Alex Cotiuga 1.1 146 <p>
147 Group names, target spaces, template references, email recipients, external URLs and workflow settings should
Alex Cotiuga 2.1 148 not be hardcoded when they are likely to change. Configuration pages or preference objects make the feature
149 easier to adapt without rewriting the implementation.
Alex Cotiuga 1.1 150 </p>
151
Alex Cotiuga 2.1 152 <h2 id="upgrade-validation">Validate custom features during upgrades</h2>
153
Alex Cotiuga 1.1 154 <p>
Alex Cotiuga 2.1 155 A successful upgrade is not only one where XWiki starts and standard pages load. The upgrade plan should also
156 include the features that make the instance specific to the organization: custom dashboards, templates, macros,
157 workflows, permissions, notifications, PDF exports, scheduled jobs and integrations.
Alex Cotiuga 1.1 158 </p>
159
160 <p>
Alex Cotiuga 2.1 161 For each important customization, the team should know what to test and what a successful result looks like. A
162 staging environment or temporary clone is usually the safest place to run this validation before production is
163 touched.
Alex Cotiuga 1.1 164 </p>
165
Alex Cotiuga 12.1 166 <p>
167 For a broader upgrade preparation model, see
168 <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>.
169 </p>
170
Alex Cotiuga 2.1 171 <div class="resource-note">
172 <p>
173 <strong>A practical rule:</strong> production can receive urgent fixes when necessary, but it should not become
174 the only place where the real version of a customization exists. After the emergency, the change should be
175 reviewed, documented and added to the normal maintenance process.
176 </p>
177 </div>
Alex Cotiuga 1.1 178
Alex Cotiuga 12.2 179 <div class="resource-inline-cta">
180 <p>
181 <strong>Not sure how risky your current XWiki version is?</strong>
182 A short technical review can clarify the upgrade path, extension compatibility,
183 custom code risks and validation needs before production is touched.
184 </p>
185 <a class="btn btn-secondary" href="$xwiki.getURL('contact.WebHome')">Request a quick review</a>
186 </div>
187
Alex Cotiuga 12.1 188 <h2 id="practical-checklist">XWiki custom development checklist</h2>
Alex Cotiuga 1.1 189
Alex Cotiuga 12.1 190 <p>
191 A maintainable XWiki customization should be easy to locate, explain, test and update. The following checklist
192 can be used as a starting point when reviewing existing custom work or planning a new feature.
193 </p>
194
Alex Cotiuga 2.1 195 <ul class="resource-checklist">
196 <li>Separate custom pages, scripts and configuration from standard XWiki content.</li>
197 <li>Document the business purpose, technical location and validation steps.</li>
Alex Cotiuga 12.1 198 <li>Keep custom code and important assets under source control, for example in Git.</li>
Alex Cotiuga 2.1 199 <li>Test custom features on staging before production upgrades.</li>
200 <li>Review old customizations and remove what is no longer used.</li>
Alex Cotiuga 1.1 201 </ul>
202
203 <h2 id="strategic-advantage">Custom code can become a strategic advantage</h2>
204
205 <p>
Alex Cotiuga 2.1 206 Many useful platform features start as custom development for one concrete need. A workflow, dashboard,
207 integration or structured application may first solve a private business problem, then become a reusable
208 internal component or even a public extension. This is how practical solutions often mature.
Alex Cotiuga 1.1 209 </p>
210
211 <p>
Alex Cotiuga 2.1 212 The goal is not to customize everything. The goal is to customize the right parts, in a way that can be
213 understood and maintained later. When custom work is separated, documented, versioned and tested, XWiki can stay
214 flexible without becoming fragile.
Alex Cotiuga 1.1 215 </p>
216
Alex Cotiuga 12.1 217 <h2 id="custom-development-faq">XWiki custom development FAQ</h2>
218
Alex Cotiuga 12.3 219 <details class="resource-faq-item" open>
220 <summary>Does custom development make XWiki harder to upgrade?</summary>
221 <p>
222 Not automatically. Custom development becomes harder to upgrade when it is undocumented, mixed with regular
223 content, applied directly in production or missing from the upgrade validation plan. Well-organized custom work
224 can remain maintainable across upgrades.
225 </p>
226 </details>
Alex Cotiuga 12.1 227
Alex Cotiuga 12.3 228 <details class="resource-faq-item">
229 <summary>Where should XWiki custom code be stored?</summary>
230 <p>
231 Custom wiki pages, scripts, templates and configuration should usually be kept in dedicated technical spaces.
232 Code and important assets should also be tracked in a source control system, such as Git, so changes are not
233 stored only in the production wiki.
234 </p>
235 </details>
Alex Cotiuga 12.1 236
Alex Cotiuga 12.3 237 <details class="resource-faq-item">
238 <summary>When should an XWiki customization become an extension?</summary>
239 <p>
240 Packaging a customization as an extension is useful when the feature becomes complex, reusable, business-critical
241 or shared across multiple instances. Java components, event listeners, scheduled jobs and integrations often
242 benefit from an extension-based approach.
243 </p>
244 </details>
Alex Cotiuga 12.1 245
Alex Cotiuga 12.3 246 <details class="resource-faq-item">
247 <summary>What should be tested after an XWiki upgrade?</summary>
248 <p>
249 Besides standard pages, the validation should include custom dashboards, templates, macros, workflows,
250 permissions, notifications, PDF exports, scheduled jobs, integrations and any custom applications used by the
251 organization.
252 </p>
253 </details>
Alex Cotiuga 12.1 254
Alex Cotiuga 12.3 255 <details class="resource-faq-item">
256 <summary>Why should configuration be kept outside custom code?</summary>
257 <p>
258 Values such as group names, target spaces, external URLs, email recipients and workflow settings can change over
259 time. Keeping them in configuration pages or preference objects makes custom features easier to adapt without
260 changing the implementation.
261 </p>
262 </details>
Alex Cotiuga 12.1 263
Alex Cotiuga 11.2 264 <div class="resource-note">
265 <p>
266 Related resources:
Alex Cotiuga 11.4 267 <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
Alex Cotiuga 11.2 268 and
Alex Cotiuga 11.3 269 <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>
Alex Cotiuga 11.2 270 </p>
271 </div>
272
Alex Cotiuga 1.1 273 <div class="resource-cta">
274 <h3>Need help reviewing XWiki customizations?</h3>
275 <p>
276 If your XWiki instance includes custom scripts, dashboards, workflows, templates, integrations or Java
Alex Cotiuga 2.1 277 extensions, a customization review can help identify what is safe, what needs documentation and what should be
278 tested before the next upgrade.
Alex Cotiuga 1.1 279 </p>
280 <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
281 </div>
282
283 </article>
284 </div>
285 </div>
286 </section>
Alex Cotiuga 2.1 287
Alex Cotiuga 12.1 288 <script type="application/ld+json">
289 {
290 "@context": "https://schema.org",
291 "@type": "FAQPage",
292 "mainEntity": [
293 {
294 "@type": "Question",
295 "name": "Does custom development make XWiki harder to upgrade?",
296 "acceptedAnswer": {
297 "@type": "Answer",
298 "text": "Not automatically. Custom development becomes harder to upgrade when it is undocumented, mixed with regular content, applied directly in production or missing from the upgrade validation plan. Well-organized custom work can remain maintainable across upgrades."
299 }
300 },
301 {
302 "@type": "Question",
303 "name": "Where should XWiki custom code be stored?",
304 "acceptedAnswer": {
305 "@type": "Answer",
306 "text": "Custom wiki pages, scripts, templates and configuration should usually be kept in dedicated technical spaces. Code and important assets should also be tracked in a source control system, such as Git, so changes are not stored only in the production wiki."
307 }
308 },
309 {
310 "@type": "Question",
311 "name": "When should an XWiki customization become an extension?",
312 "acceptedAnswer": {
313 "@type": "Answer",
314 "text": "Packaging a customization as an extension is useful when the feature becomes complex, reusable, business-critical or shared across multiple instances. Java components, event listeners, scheduled jobs and integrations often benefit from an extension-based approach."
315 }
316 },
317 {
318 "@type": "Question",
319 "name": "What should be tested after an XWiki upgrade?",
320 "acceptedAnswer": {
321 "@type": "Answer",
322 "text": "Besides standard pages, the validation should include custom dashboards, templates, macros, workflows, permissions, notifications, PDF exports, scheduled jobs, integrations and any custom applications used by the organization."
323 }
324 },
325 {
326 "@type": "Question",
327 "name": "Why should configuration be kept outside custom code?",
328 "acceptedAnswer": {
329 "@type": "Answer",
330 "text": "Values such as group names, target spaces, external URLs, email recipients and workflow settings can change over time. Keeping them in configuration pages or preference objects makes custom features easier to adapt without changing the implementation."
331 }
332 }
333 ]
334 }
335 </script>
336
Alex Cotiuga 1.1 337 {{/html}}
338 {{/velocity}}