xWiki as DMS for external integration

Development
1

What is the best integration scenario for use of xWiki as DMS.

ATM we

  1. define “document template” in xWiki space (as standard document with “placeholder macro“)
  2. in external system the template is processed
    1. downloaded from xWiki
    2. replaced “placeholder macro“ with expected values with Thymeleaf.org
    3. new content published on xWiki to other space
  3. other manual modifications in xWiki

after modifications are made other flow is initiated

  1. external system initiate publishing (as PDF)
  2. external system use PDF export (old way Customizations for PDF Export Using URL Parameters (XWiki.org))
  3. external system publish the PDF in own database

All xWiki calls use REST API (XWiki.org).

We would like to validate the possibility to implement “xWiki extension” for the first phase. PDF export is crucial and the “new way“ we find not acceptable for this sort of “backend” integration.

What other options to integrate xWiki we have?

2

You can use this if you don’t want to use the PDF UI: https://extensions.xwiki.org/xwiki/bin/view/Extension/PDF%20Export%20Application/#HScriptService

3

I don’t know if it helps but Gemini 3 gave the following (that I haven’t reviewed but maybe it can give you ideas).

"
Your current architecture uses XWiki primarily as a storage and rendering engine, but by performing the “template processing” (Thymeleaf) externally, you are incurring significant overhead and missing out on XWiki’s core strengths as a structured DMS.

To optimize this for a backend-heavy integration while keeping the PDF export reliable, here are the best integration scenarios.

1. The “XWiki-Native” Scenario (Recommended)

Instead of treating XWiki as a flat file storage, use its Data Model (XClasses and XObjects).

  • Phase 1 (Data Injection): * Define an XClass in XWiki with fields matching your placeholders.

  • The external system does not download a template. Instead, it sends a POST or PUT request to the REST API /objects containing the raw data (JSON/XML).

  • The Template: You define a “Sheet” in XWiki (using Velocity or Groovy). This sheet acts as your “Thymeleaf.” When the page is viewed (or exported to PDF), the sheet dynamically injects the Object data into the layout.

  • Benefits: * No round-trip (Download → Process → Upload).

  • Data remains structured and searchable in XWiki.

  • Manual modifications are easier because users edit form fields or specific sections rather than raw HTML/Wiki syntax.

2. The “Custom REST Resource” Extension

If you want to keep the logic in an XWiki Extension (as you suggested), the best approach is to implement a Custom REST Resource.

  • How it works: You write a Java component (using JAX-RS) that runs inside XWiki.
  • Workflow:
  1. External system calls POST /xwiki/rest/my-custom-dms/generate?template=MyTemplate&target=NewPage.
  2. The body contains the JSON data.
  3. Your Java extension handles the page creation, placeholder replacement (using XWiki’s internal ModelContext and ContentConfiguration), and saving.
  • Benefits: This reduces your external system’s logic to a single API call. It is highly performant and keeps your DMS logic encapsulated within XWiki.

3. Strategy for PDF Export

You mentioned that the “new way” (the PDF Export Application based on LaTeX or Client-side) is unacceptable. For backend/DMS integration, your instinct to stay with the Server-Side (FOP) Export is correct for two reasons: Performance and Predictability.

  • The “Old Way” via REST: You can still trigger the old export via the URL:
    GET /xwiki/bin/export/Space/Page?format=pdf&[parameters]
  • The Improvement: Create a Custom Skin or a PDF Template within XWiki specifically for these DMS documents. By passing the skin or pdfpage parameter in the REST call, you ensure the external system gets a clean, professional document without sidebars, headers, or UI elements.
  • Stability: Since the “old way” is currently being maintained for backward compatibility and server-side stability, it remains the most robust choice for automated “headless” PDF generation.

4. Integration via “XWiki Task Manager” (Asynchronous)

If Phase 1 or the PDF export takes too long (risking REST timeouts), use a Queue approach:

  1. External system pushes a “Job” to XWiki (via a custom XObject).
  2. An XWiki Scheduler (Groovy script) picks up the job.
  3. XWiki generates the document and the PDF.
  4. XWiki sends a Webhook (HTTP POST) back to your external system with the PDF attached or a link to download.

Comparison of Options

Feature Your Current Way XClass/Object Way Custom REST Extension
Logic Location External (Thymeleaf) Internal (Velocity/Groovy) Internal (Java)
Network Overhead High (2-3 calls) Low (1 call) Lowest (1 call)
Reliability Medium (Sync issues) High Highest
Ease of Change Easy (External dev) Easy (Wiki-based) Hard (Requires Java deploy)

Final Recommendation

  1. Stop the Download-Process-Upload cycle. It is the primary bottleneck.
  2. Implement an XClass-based model. Let the external system simply “push data” into XObjects via the standard REST API.
  3. Use XWiki “Sheets” to handle the visual replacement of placeholders. This replaces your Thymeleaf logic.
  4. Keep the “Old” PDF Export. Use URL parameters to force a specific PDF template for your backend-generated documents to ensure layout consistency.

If you specifically want to build an XWiki Extension, focus on creating a Custom REST Endpoint that accepts your external system’s data and performs the page creation/PDF trigger internally.
"