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.2 to 1.3 From 12.1 to 12.2

From version 1.3

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

Change comment: There is no comment for this version

To version 12.1

edited by Agnease
on 2026/05/26 10:35

Change comment: There is no comment for this version

Raw
Rendered

Summary

Page properties (2 modified, 0 added, 0 removed)
Objects (0 modified, 1 added, 0 removed)
- Agnease.Code.SEODetailsClass[0]

Details

Page properties

Title

@@ -1,1 +1,1 @@
--xwiki-custom-development
++How to Customize XWiki Without Creating Upgrade Problems

Content

@@ -11,10 +11,11 @@
          </div>
        </div>
--      <h1 id="hero-title">How to customize XWiki safely without creating upgrade problems</h1>
++      <h1 id="hero-title">Why XWiki custom development needs structure, documentation and upgrade awareness</h1>
        <p class="resource-summary">
--        Custom code does not have to make XWiki fragile. The real risk is unmanaged customization, not customization itself.
++        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.
        </p>
      </div>
    </section>
@@ -22,207 +22,297 @@
    <section class="resource-page">
      <div class="container">
        <div class="resource-layout">
++        <aside class="resource-sidebar" aria-label="Page summary">
++          <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="#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="#strategic-advantage">Strategic advantage</a></li>
++            <li><a href="#custom-development-faq">FAQ</a></li>
++          </ul>
++        </aside>
          <article class="resource-content">
            <p>
--            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.
++            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.
            </p>
            <p>
--            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.
++            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.
            </p>
            <div class="resource-note">
              <p>
--              <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.
++              <strong>In practice:</strong> XWiki custom development should be separated from standard platform pages,
++              documented, kept under source control, tested on staging and reviewed during upgrades. This makes custom
++              features easier to maintain instead of turning them into hidden dependencies.
              </p>
            </div>
--          <h2 id="why-customize">Why organizations customize XWiki</h2>
--
            <p>
--            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.
++            XWiki custom development is the process of adapting the platform with custom pages, classes, objects, sheets,
++            templates, scripts, macros, UI extensions, Java components or integrations. The goal is to support real
++            business processes while keeping the instance understandable, maintainable and upgrade-aware.
            </p>
--          <p>Typical XWiki customizations include:</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.
++            </p>
++          </div>
--          <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>
++          <h2 id="why-customize">Why XWiki custom development exists</h2>
            <p>
--            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.
++            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.
            </p>
--          <h2 id="customization-risks">Where customization becomes risky</h2>
--
            <p>
--            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.
++            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.
            </p>
--          <p>Common warning signs include:</p>
++          <h2 id="where-risk-appears">Where customization becomes risky</h2>
--          <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>
++          <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.
++          </p>
--          <h2 id="safe-model">A safer model for XWiki custom development</h2>
++          <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.
++          </p>
--          <h3>1. Separate custom code from standard XWiki pages</h3>
            <p>
--            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.
++            Customizations should also be reviewed as part of the wider platform risk model. See
++            <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
++            for related checks around permissions, authentication, extensions, infrastructure and operational practices.
            </p>
--          <h3>2. Document each important customization</h3>
++          <h2 id="safe-model">A safer model for XWiki custom work</h2>
++
++          <h3>1. Keep custom code separate from standard XWiki pages</h3>
            <p>
--            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.
++            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.
            </p>
--          <h3>3. Track wiki-based customizations</h3>
++          <h3>2. Document the purpose, not only the implementation</h3>
            <p>
--            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.
++            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.
            </p>
--          <h3>4. Use Java extensions for larger or long-term features</h3>
++          <h3>3. Keep custom code under source control</h3>
            <p>
--            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.
++            Custom development should not exist only inside the production wiki. Java code, scripts, XAR packages,
++            deployment files and templates should be stored in a source control system, such as Git. This gives the team a
++            history of what changed, when it changed and why.
            </p>
--          <h3>5. Use Git for serious custom development</h3>
++          <h3>4. Choose the right implementation level</h3>
            <p>
--            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.
++            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.
            </p>
--          <h3>6. Keep configuration separate from code</h3>
++          <h3>5. Keep configuration outside the 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 solution
--            easier to adjust without editing the implementation.
++            not be hardcoded when they are likely to change. Configuration pages or preference objects make the feature
++            easier to adapt without rewriting the implementation.
            </p>
--          <h3>7. Test custom features during every upgrade</h3>
++          <h2 id="upgrade-validation">Validate custom features during upgrades</h2>
++
            <p>
--            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.
++            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.
            </p>
--          <h2 id="tracking-checklist">Practical tracking checklist</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.
++          </p>
++          <p>
++            For a broader upgrade preparation model, see
++            <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>.
++          </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>
++
++          <h2 id="practical-checklist">XWiki custom development checklist</h2>
++
++          <p>
++            A maintainable XWiki customization should be easy to locate, explain, test and update. The following checklist
++            can be used as a starting point when reviewing existing custom work or planning a new feature.
++          </p>
++
            <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>
++            <li>Separate custom pages, scripts and configuration from standard XWiki content.</li>
++            <li>Document the business purpose, technical location and validation steps.</li>
++            <li>Keep custom code and important assets under source control, for example in Git.</li>
++            <li>Test custom features on staging before production upgrades.</li>
++            <li>Review old customizations and remove what is no longer used.</li>
            </ul>
--          <h2 id="delivery-process">A controlled delivery process</h2>
++          <h2 id="strategic-advantage">Custom code can become a strategic advantage</h2>
            <p>
--            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.
++            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.
            </p>
--          <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>
++          <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.
++          </p>
--          <h2 id="common-mistakes">Common mistakes to avoid</h2>
++          <h2 id="custom-development-faq">XWiki custom development FAQ</h2>
--          <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>
++          <h3>Does custom development make XWiki harder to upgrade?</h3>
++          <p>
++            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.
++          </p>
--          <h2 id="strategic-advantage">Custom code can become a strategic advantage</h2>
++          <h3>Where should XWiki custom code be stored?</h3>
++          <p>
++            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.
++          </p>
++          <h3>When should an XWiki customization become an extension?</h3>
            <p>
--            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.
++            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.
            </p>
++          <h3>What should be tested after an XWiki upgrade?</h3>
            <p>
--            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.
++            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.
            </p>
++          <h3>Why should configuration be kept outside custom code?</h3>
++          <p>
++            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.
++          </p>
++
++          <div class="resource-note">
++            <p>
++              Related resources:
++              <a href="$xwiki.getURL('resources.xwiki-security-review')">what an XWiki security review should actually include</a>
++              and
++              <a href="$xwiki.getURL('resources.why-upgrade-xwiki')">why regular XWiki upgrades matter</a>
++            </p>
++          </div>
++
            <div class="resource-cta">
              <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>
          </article>
--
--        <aside class="resource-sidebar" aria-label="Page summary">
--          <h4>In this guide</h4>
--          <ul>
--            <li><a href="#why-customize">Why customize XWiki</a></li>
--            <li><a href="#customization-risks">Customization risks</a></li>
--            <li><a href="#safe-model">Safe model</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>
--
        </div>
      </div>
    </section>
++
++  <script type="application/ld+json">
++  {
++    "@context": "https://schema.org",
++    "@type": "FAQPage",
++    "mainEntity": [
++      {
++        "@type": "Question",
++        "name": "Does custom development make XWiki harder to upgrade?",
++        "acceptedAnswer": {
++          "@type": "Answer",
++          "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."
++        }
++      },
++      {
++        "@type": "Question",
++        "name": "Where should XWiki custom code be stored?",
++        "acceptedAnswer": {
++          "@type": "Answer",
++          "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."
++        }
++      },
++      {
++        "@type": "Question",
++        "name": "When should an XWiki customization become an extension?",
++        "acceptedAnswer": {
++          "@type": "Answer",
++          "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."
++        }
++      },
++      {
++        "@type": "Question",
++        "name": "What should be tested after an XWiki upgrade?",
++        "acceptedAnswer": {
++          "@type": "Answer",
++          "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."
++        }
++      },
++      {
++        "@type": "Question",
++        "name": "Why should configuration be kept outside custom code?",
++        "acceptedAnswer": {
++          "@type": "Answer",
++          "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."
++        }
++      }
++    ]
++  }
++  </script>
++
  {{/html}}
  {{/velocity}}

Agnease.Code.SEODetailsClass[0]

metaDescription

...	...	@@ -1,0 +1,1 @@
	1	+Learn how to organize XWiki custom development, scripts, extensions and templates so your platform stays easier to maintain, document and upgrade.

metaTitle

...	...	@@ -1,0 +1,1 @@
	1	+How to Customize XWiki Without Creating Upgrade Problems \| Agnease