Changes for page How to Customize XWiki Without Creating Upgrade Problems

Last modified by Agnease on 2026/05/26 11:00

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

From 1.4 to 1.3 From 3.1 to 2.1

From version 2.1

edited by Agnease
on 2026/05/18 19:22

Change comment: Imported from XAR

To version 1.4

edited by Agnease
on 2026/05/18 19:01

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Title

@@ -1,1 +1,1 @@
--XWiki custom development
++xwiki-custom-development

Content

@@ -5,17 +5,16 @@
    <section class="resource-header" aria-labelledby="hero-title">
      <div class="container">
        <div class="text-center">
--        <div class="resource-kicker">
++        <div class="hero-kicker">
            <i class="fa fa-code" aria-hidden="true"></i>
            XWiki custom development guidance
          </div>
        </div>
--      <h1 id="hero-title">How to customize XWiki without creating upgrade problems</h1>
++      <h1 id="hero-title">How to customize XWiki safely without creating upgrade problems</h1>
        <p class="resource-summary">
--        XWiki can be adapted to complex business needs. The important part is to keep custom work documented,
--        versioned and easy to validate during future upgrades.
++        Custom code does not have to make XWiki fragile. The real risk is unmanaged customization, not customization itself.
        </p>
      </div>
    </section>
@@ -27,140 +27,174 @@
          <article class="resource-content">
            <p>
--            Many organizations choose XWiki because it can grow beyond a simple documentation space. A platform may start
--            with pages, attachments and permissions, then evolve into structured applications, approval workflows, custom
--            dashboards, branded PDF exports, integrations or internal tools built around the company’s real processes.
++            XWiki is often selected because it can adapt to real business processes. Teams can start with standard wiki
++            features, then add structured pages, templates, dashboards, workflows, PDF exports, integrations, macros,
++            UI extensions or Java components when the organization needs more than generic content editing.
            </p>
            <p>
--            This flexibility is valuable, but it also raises a legitimate concern: will custom development make upgrades
--            harder? The answer depends less on the existence of custom code and more on the way it is organized. A controlled
--            customization can remain stable for years. An undocumented change applied directly in production can become a
--            maintenance problem after the next upgrade.
++            This flexibility is a major advantage, but it also creates a common concern: if the platform is customized too
++            much, will future upgrades become expensive or risky? The answer depends less on how much customization exists
++            and more on how that customization is designed, tracked, documented and tested.
            </p>
            <div class="resource-note">
              <p>
--              <strong>The main point:</strong> custom code is not the problem. Uncontrolled custom code is. XWiki can be
--              customized safely when changes are separated from standard pages, tracked, documented and tested.
++              <strong>The main point:</strong> custom development is not the problem. Uncontrolled custom development is.
++              When delivered in a controlled way, custom XWiki features can remain stable across multiple upgrades.
              </p>
            </div>
--          <h2 id="why-customize">Why XWiki custom development exists</h2>
++          <h2 id="why-customize">Why organizations customize XWiki</h2>
            <p>
--            Avoiding all customization may look safer at first, but it can create other costs. Users may start maintaining
--            side spreadsheets, sending approvals by email, duplicating data in external tools or bypassing the wiki because
--            it does not match their daily work. In these cases, a well-designed XWiki customization can simplify the process
--            and improve adoption.
++            Many organizations can use XWiki successfully with standard features. But production platforms often evolve
++            beyond generic pages and spaces. They need to reflect internal processes, compliance requirements, document
++            governance, reporting needs or integrations with other business systems.
            </p>
++          <p>Typical XWiki customizations include:</p>
++
++          <ul>
++            <li>custom document metadata, classes, sheets and templates</li>
++            <li>structured applications for internal processes</li>
++            <li>approval workflows and controlled document lifecycles</li>
++            <li>custom dashboards, reports and LiveData views</li>
++            <li>branded PDF exports and document templates</li>
++            <li>UI extensions, panels, macros and page actions</li>
++            <li>integrations with authentication, storage, CRM, ticketing or AI systems</li>
++            <li>scheduled jobs, notifications and automation</li>
++          </ul>
++
            <p>
--            Typical examples include custom metadata for documents, templates for recurring content, dashboards for teams,
--            approval flows, notifications, PDF layouts, page actions, UI extensions, macros and integrations with systems
--            such as authentication providers, ticketing tools, storage services, CRM platforms or AI assistants. These
--            features can be implemented at different levels, from wiki pages and scripts to packaged Java extensions.
++            Avoiding all customization can create hidden costs: manual workarounds, duplicated tools, weak adoption and
++            processes that remain outside the knowledge platform. The goal is not to customize everything. The goal is to
++            customize the right things in a maintainable way.
            </p>
--          <h2 id="where-risk-appears">Where customization becomes risky</h2>
++          <h2 id="customization-risks">Where customization becomes risky</h2>
            <p>
--            Problems usually appear when nobody can quickly explain where a customization is implemented, why it exists or
--            how it should be tested. Business logic mixed into regular content pages, standard pages changed without notes,
--            scripts that exist only in production, hardcoded group names or missing upgrade checks are common signs that the
--            customization process needs more structure.
++            XWiki makes it easy to add logic in wiki pages, Velocity scripts, Groovy scripts, templates, panels, macros,
++            UI extensions and Java components. That power needs discipline. A customization becomes risky when nobody can
++            quickly explain where it is implemented, why it exists and how it should be validated after an upgrade.
            </p>
++          <p>Common warning signs include:</p>
++
++          <ul>
++            <li>business logic mixed directly into regular content pages</li>
++            <li>standard XWiki pages modified without documentation</li>
++            <li>important scripts existing only in production</li>
++            <li>no source control or release history for custom code</li>
++            <li>hardcoded users, groups, page names, URLs or workflow states</li>
++            <li>custom features missing from upgrade validation plans</li>
++            <li>urgent fixes applied in production and never cleaned up later</li>
++          </ul>
++
++          <h2 id="safe-model">A safer model for XWiki custom development</h2>
++
++          <h3>1. Separate custom code from standard XWiki pages</h3>
            <p>
--            This is especially important in XWiki because custom logic can live in several places: classes, objects, sheets,
--            templates, Velocity or Groovy scripts, panels, UI extensions, macros, scheduled jobs and Java components. The
--            flexibility is useful, but each important customization should have a clear location and a clear maintenance
--            path.
++            Custom pages, classes, templates, scripts and configuration should usually live in dedicated technical spaces,
++            such as a company-specific <code>Code</code>, <code>Applications</code>, <code>Templates</code> or
++            <code>Config</code> area. This keeps the difference between standard distribution content and company-specific
++            logic clear during upgrades.
            </p>
--          <h2 id="safe-model">A safer model for XWiki custom work</h2>
--
--          <h3>1. Keep custom code separate from standard XWiki pages</h3>
++          <h3>2. Document each important customization</h3>
            <p>
--            Custom classes, scripts, templates and configuration should usually live in dedicated technical spaces, for
--            example a company-specific <code>Code</code>, <code>Applications</code>, <code>Templates</code> or
--            <code>Config</code> area. This makes it easier to see what belongs to the standard distribution and what belongs
--            to the organization.
++            Every significant customization should have a short technical note: what it does, where it is implemented, who
++            requested it, what pages or components are involved, what assumptions it makes and how it should be tested.
            </p>
--          <h3>2. Document the purpose, not only the implementation</h3>
++          <h3>3. Track wiki-based customizations</h3>
            <p>
--            A short technical note is often enough: what the customization does, who uses it, where it is implemented, what
--            assumptions it makes and what should be checked after an upgrade. This turns custom work from a hidden script
--            into a maintainable part of the platform.
++            Many practical features can be built directly in the wiki using XWiki classes, objects, sheets, templates,
++            Velocity, Groovy, UI extensions or dashboards. These should still be grouped, documented and exported or
++            versioned when they become important for the business.
            </p>
--          <h3>3. Track important changes in a version control system</h3>
++          <h3>4. Use Java extensions for larger or long-term features</h3>
            <p>
--            Serious custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
--            deployment files and important templates should be stored in a version control system, such as Git. This gives
--            the team a history of what changed, when it changed and why.
++            When a customization becomes complex, reusable or business-critical, a Java extension is often a better
++            long-term solution. This is especially useful for event listeners, custom services, reusable macros, scheduled
++            jobs, integrations, workflow logic, APIs or advanced PDF export behavior.
            </p>
--          <h3>4. Choose the right implementation level</h3>
++          <h3>5. Use Git for serious custom development</h3>
            <p>
--            Many useful features can start as wiki-based customizations using XWiki classes, sheets, templates, Velocity or
--            UI extensions. When a feature becomes complex, reusable or business-critical, packaging it as an extension is
--            often a better long-term option. Event listeners, custom services, scheduled jobs, integrations and advanced
--            workflow logic usually benefit from this approach.
++            Important customizations should be stored in source control. Git makes it possible to understand what changed,
++            when it changed, why it changed and whether the change can be safely rolled back or adapted for a new XWiki
++            version.
            </p>
--          <h3>5. Keep configuration outside the code</h3>
++          <h3>6. Keep configuration separate from code</h3>
            <p>
              Group names, target spaces, template references, email recipients, external URLs and workflow settings should
--            not be hardcoded when they are likely to change. Configuration pages or preference objects make the feature
--            easier to adapt without rewriting the implementation.
++            not be hardcoded when they are likely to change. Configuration pages or preference objects make the solution
++            easier to adjust without editing the implementation.
            </p>
--          <h2 id="upgrade-validation">Validate custom features during upgrades</h2>
--
++          <h3>7. Test custom features during every upgrade</h3>
            <p>
--            A successful upgrade is not only one where XWiki starts and standard pages load. The upgrade plan should also
--            include the features that make the instance specific to the organization: custom dashboards, templates, macros,
--            workflows, permissions, notifications, PDF exports, scheduled jobs and integrations.
++            A successful upgrade is not only one where the server starts. Custom dashboards, workflows, macros, PDF exports,
++            notifications, integrations, permissions and scheduled jobs should be part of the validation checklist.
            </p>
++          <h2 id="tracking-checklist">Practical tracking checklist</h2>
++
++          <ul class="resource-checklist">
++            <li>List all important custom pages, templates, sheets, macros, scripts and Java extensions.</li>
++            <li>Identify which customizations are business-critical and which are historical or optional.</li>
++            <li>Move technical logic into dedicated spaces instead of regular content pages where possible.</li>
++            <li>Store Java code, scripts, XAR packages and deployment files in Git.</li>
++            <li>Document the purpose, owner, technical location and validation steps for each customization.</li>
++            <li>Use staging or a temporary clone to test custom features before production upgrades.</li>
++            <li>Review hardcoded references to users, groups, spaces, page names, URLs and external systems.</li>
++            <li>Remove obsolete customizations instead of carrying them through every upgrade cycle.</li>
++            <li>Package larger features as extensions when they become reusable or business-critical.</li>
++          </ul>
++
++          <h2 id="delivery-process">A controlled delivery process</h2>
++
            <p>
--            For each important customization, the team should know what to test and what a successful result looks like. A
--            staging environment or temporary clone is usually the safest place to run this validation before production is
--            touched.
++            Custom code should be treated as part of the platform architecture, not as a temporary patch. A practical
++            delivery process can be simple, but it should be repeatable.
            </p>
--          <div class="resource-note">
--            <p>
--              <strong>A practical rule:</strong> production can receive urgent fixes when necessary, but it should not become
--              the only place where the real version of a customization exists. After the emergency, the change should be
--              reviewed, documented and added to the normal maintenance process.
--            </p>
--          </div>
++          <ol>
++            <li><strong>Clarify the need:</strong> define the business problem and the users affected.</li>
++            <li><strong>Choose the right implementation level:</strong> wiki pages, scripts, XAR package or Java extension.</li>
++            <li><strong>Develop outside production:</strong> use a development or staging environment for non-trivial work.</li>
++            <li><strong>Track the change:</strong> store code, scripts, configuration and documentation in a maintainable form.</li>
++            <li><strong>Validate the behavior:</strong> test permissions, rendering, workflows, exports, jobs and integrations.</li>
++            <li><strong>Deploy with notes:</strong> record what changed and what should be checked during future upgrades.</li>
++          </ol>
--          <h2 id="practical-checklist">A compact checklist</h2>
++          <h2 id="common-mistakes">Common mistakes to avoid</h2>
--          <ul class="resource-checklist">
--            <li>Separate custom pages, scripts and configuration from standard XWiki content.</li>
--            <li>Document the business purpose, technical location and validation steps.</li>
--            <li>Use a version control system, such as Git, for code and important assets.</li>
--            <li>Test custom features on staging before production upgrades.</li>
--            <li>Review old customizations and remove what is no longer used.</li>
++          <ul>
++            <li><strong>Changing standard pages without a plan.</strong> Direct changes are harder to compare, explain and preserve.</li>
++            <li><strong>Using production as the development environment.</strong> Quick fixes may be necessary, but they should be reviewed and integrated properly afterwards.</li>
++            <li><strong>Leaving scripts undocumented.</strong> A script that nobody understands becomes a maintenance risk.</li>
++            <li><strong>Hardcoding business assumptions.</strong> Roles, groups, spaces and external systems change over time.</li>
++            <li><strong>Testing only standard XWiki features during upgrades.</strong> Custom behavior is often where the real upgrade risk is found.</li>
            </ul>
            <h2 id="strategic-advantage">Custom code can become a strategic advantage</h2>
            <p>
--            Many useful platform features start as custom development for one concrete need. A workflow, dashboard,
--            integration or structured application may first solve a private business problem, then become a reusable
--            internal component or even a public extension. This is how practical solutions often mature.
++            Some of the most useful solutions in a platform environment start as custom code for a real project. A workflow,
++            dashboard, macro, integration or structured application may begin as a private need, then become a reusable
++            internal product or even a public extension.
            </p>
            <p>
--            The goal is not to customize everything. The goal is to customize the right parts, in a way that can be
--            understood and maintained later. When custom work is separated, documented, versioned and tested, XWiki can stay
--            flexible without becoming fragile.
++            This is why the question should not be whether XWiki custom development should be avoided. The better question
++            is how to make it maintainable. When customizations are separated, documented, versioned and tested, they can
++            help the organization build a knowledge platform that matches its real work instead of forcing users into
++            disconnected tools and manual workarounds.
            </p>
            <div class="resource-cta">
@@ -167,8 +167,8 @@
              <h3>Need help reviewing XWiki customizations?</h3>
              <p>
                If your XWiki instance includes custom scripts, dashboards, workflows, templates, integrations or Java
--              extensions, a customization review can help identify what is safe, what needs documentation and what should be
--              tested before the next upgrade.
++              extensions, a customization review can help identify what is safe, what needs documentation and what should
++              be tested before the next upgrade.
              </p>
              <a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Request a customization review</a>
            </div>
@@ -179,10 +179,11 @@
            <h4>In this guide</h4>
            <ul>
              <li><a href="#why-customize">Why customize XWiki</a></li>
--            <li><a href="#where-risk-appears">Where risk appears</a></li>
++            <li><a href="#customization-risks">Customization risks</a></li>
              <li><a href="#safe-model">Safe model</a></li>
--            <li><a href="#upgrade-validation">Upgrade validation</a></li>
--            <li><a href="#practical-checklist">Checklist</a></li>
++            <li><a href="#tracking-checklist">Tracking checklist</a></li>
++            <li><a href="#delivery-process">Delivery process</a></li>
++            <li><a href="#common-mistakes">Common mistakes</a></li>
              <li><a href="#strategic-advantage">Strategic advantage</a></li>
            </ul>
          </aside>
@@ -190,6 +190,5 @@
        </div>
      </div>
    </section>
--
  {{/html}}
  {{/velocity}}