Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Document Conversion (DOCX → PDF)
Convert the right source, preserve its identity
The ordinary conversion API creates a new PDF document in the source’s folder and leaves the Word source unchanged. It accepts a document ID, not a source-version selector. The service resolves that document’s current version when it executes and reports the actual sourceVersionNumber in the result. A task’s pinned attachment version does not force this API to convert that older version.
Before conversion, establish source read access, destination folder upload rights, a supported source type/size and an admitted available engine. An ordinary health/status response does not qualify arbitrary font fidelity, source-renderer custody or a private diagnostic build. Existing private/native/PR3228 holds remain separate.
| Concern | Actual contract |
|---|---|
| HTTP call | POST /api/documents/{documentId}/convert/pdf, no body/source-version parameter |
| Availability | GET /api/documents/conversion/status returns available,engineId |
| Source identity | Actual sourceDocumentId,sourceVersionNumber returned after resolution |
| New output | pdfDocumentId,pdfVersionId,pdfVersionNumber,pdfName |
| Supporting metrics | engineId,sourceBytes,pdfBytes,durationMillis; not a business acceptance signature |
| Engine policy | Canonical dms.conversion.engine; retired engine environment alias does not override it |
| Connection | Supported URL/binary/timeout/size settings retain their documented sources |
| BPMN binding | Governed documentId uses leading = expressions, with runtime requester/run-as reauthorization |
For a workflow, choose the actual service.dms.convert.docx-to-pdf implementation and its permitted result binding. For a user, the HTTP path still requires current secured source and upload admission. Do not interpret a worker thread, parseable expression or a viewable title as a document grant. Examples below are source-checked procedures/projections; no conversion runtime or private renderer proof was executed for this documentation.
Worked examples
Example FLOW-DC-01 — Convert the current approved letter into a sibling PDF
Scenario and inputs. Sara has actual view access to a synthetic approval-letter document in people-ops and editor/upload rights in its folder. The ordinary engine is admitted and available. She records the document’s current metadata before requesting conversion, while acknowledging that another authorized version update could race the request.
Procedure. Read GET /api/documents/conversion/status. POST /api/documents/{documentId}/convert/pdf without an invented JSON body or version query. Inspect the returned sourceDocumentId/sourceVersionNumber together with the new PDF’s document/version identity and name. Download the actual new PDF through its admitted version read and retain both source and output references. Compare the returned source version with the intended evidence before using the PDF in a consequential business step.
Expected result. A new sibling PDF is created while the Word source remains unchanged. The result’s sourceVersionNumber states what the service actually converted; it is not assumed equal to an older task attachment pin.
Failure and recovery. If the wrong current source version was resolved, do not relabel the PDF as proof of an older version. Use the supported owner workflow to reconcile the intended source. A lost reply is not automatically a failed conversion; check for the actual output before another request could create a duplicate.
Sources. DocumentController.java:751; DocumentController.java:992; SecuredDocumentConversionService.java:49.
Example FLOW-DC-02 — Resolve a governed case-file document at execution
Scenario and inputs. Nadia authors conversion after leave approval. The case file contains a permitted document ID value, and the selected service task is the actual DMS conversion implementation. The following is a configuration fragment, not a complete BPMN process or a general permission grant.
{
"documentId": "=approvalDocumentId",
"resultVariable": "pdfDocument"
}
Procedure. Configure the activity’s documentId through the supported governed expression field and choose a declared, nonreserved result variable. Publish through the lifecycle’s current validation, compatibility and requester/run-as gates. At execution, the wired executor resolves the expression and reauthorizes DOCUMENT_VIEW on the resulting source before secured conversion. Inspect the nested result under the actual authored binding and preserve source/PDF version identities.
Expected result. The dynamic source is checked when it is known; publication-time parseability alone does not authorize a later document. The PDF still uses secured destination upload and the service’s current-source-version behavior.
Failure and recovery. ${approvalDocumentId} is screen interpolation syntax and is not accepted for this governed field. A missing/invalid expression, unavailable engine or denied resolved resource remains a specific failure. Do not treat an actorless worker as a bypass, choose an engine-owned result name or replace a denied document with another source silently.
Sources. DmsConvertDocxToPdfServiceTaskExecutor.java:28; DmsConvertDocxToPdfServiceTaskExecutor.java:75.
Example FLOW-DC-03 — Configure engine policy and connection independently
Scenario and inputs. An operator prepares an owned local or deployment lane where ordinary DMS conversion is authorized. The operator has the actual configuration/restart authority and protected trust prerequisites. This is a configuration recipe, not permission to restart a shared renderer or import private font/source material.
Procedure. Select the supported canonical feature setting, for example:
dms.conversion.engine=gotenberg
Configure the admitted sidecar URL through the supported connection setting, such as DMS_CONVERSION_GOTENBERG_URL, separately from the engine policy. Review timeout/source-size bounds and required renderer trust/credential-file references without printing their secrets. Apply only the owner-approved deployment/restart procedure and inspect the ordinary status/readiness plus the task’s separately required qualification evidence.
Expected result. Engine selection comes from the canonical configuration snapshot; URL/binary/timeout/size settings retain their own documented precedence. An available endpoint is one prerequisite, not blanket source/PDF fidelity or production certification.
Failure and recovery. Do not revive DMS_CONVERSION_ENGINE as an override, disable trust checks, loosen a protected source directory or claim a font-image rebuild qualified a held renderer path. A private/native/PR3228 proof remains deferred until explicitly resumed by its owner.
Sources. DocumentConversionProperties.java:1; feature-flags.md:1.
Example FLOW-DC-04 — Diagnose an actual refusal before deciding whether to retry
Scenario and inputs. A conversion request returns an error, or the client loses its reply. The source document/version, actor scope and safe request/support evidence are retained. The service distinguishes disabled/unavailable engine, unsupported Word source and oversized input; those are different from a potentially accepted request whose response was lost.
Procedure. For a definite refusal, inspect the actual code and current dependency/source metadata. Unsupported input uses UNSUPPORTED_SOURCE_TYPE; a declared or streamed excessive source can produce SOURCE_TOO_LARGE; disabled/unavailable engine uses its own code. Correct the real permitted source or owner-controlled dependency, then plan the supported operation again. For an uncertain transport result, inspect the actual document list/version and allowed logs/evidence to reconcile whether a sibling PDF was created before another consequential request.
Expected result. Diagnosis leads to a concrete supported recovery, not a fabricated successful PDF or a destructive replacement of the Word source. Metrics, filenames and engine availability do not by themselves authenticate business acceptance or private output qualification.
Failure and recovery. Do not retry indefinitely, infer rollback from an HTTP/network failure, or launch a private/native alternative to bypass a refusal. Preserve the original failure and any uncertain output, keep credentials out of diagnostics and ask the actual dependency owner for the specific authorized correction.
Sources. DocumentConversionException.java:1; DefaultDocumentConversionServiceTest.java:84.
Detailed reference
Date: 2026-07-23
Status: Production-oriented DMS conversion slice
Base path: /api/documents
Why LibreOffice (not POI alone)
Complex Word documents — multi-section layout, headers/footers, tables, embedded objects, and mixed Arabic (RTL) + English (LTR) — need a real document layout engine. Apache POI can read/write OOXML but does not faithfully render print layout to PDF.
This platform converts with LibreOffice Writer’s PDF export, reached in one of two ways:
| Engine id | How | When to use |
|---|---|---|
gotenberg (default) |
HTTP to Gotenberg POST /forms/libreoffice/convert |
Docker Compose / k8s sidecar (recommended) |
libreoffice-cli |
Local soffice --headless --convert-to pdf |
Bare-metal nodes with LO installed |
disabled |
No engine | Feature off; API returns ENGINE_* errors |
Both engines use the same LibreOffice renderer class, so Arabic shaping, bidi, and complex layout quality match LibreOffice’s own export.
Contract (stable for API + workflow)
- Input: a live DMS
documentIdwhose current version is Word-family:.docx,.doc,.odt, or.rtf(by filename extension and/or MIME). - Output: a new document in the same folder, named
{base}.pdf, with one PDF version. The source document is never modified or replaced. - Authorization (HTTP): global
DOCUMENT_VIEWceiling + document VIEWER on the source; creating the PDF reuses secured upload (folder EDITOR). - Authorization (BPMN): a literal
documentIdis authorized at publication. Governed expression bindings use a leading=(for example=caseDocumentId); the publication gate parses them and defers resource authorization until resolution.${...}is not accepted for this governed field. The binding resolves when the step executes. The wired executor reauthorizesDOCUMENT_VIEWon the resolved document using the step's requester and authored run-as contract before calling conversion. Service-account run-as retains its published binding proof; a worker thread is not a general permission bypass. Source download and PDF creation still use the secured document services in the instance workspace. - Audit:
DOCUMENT_CONVERTED_TO_PDFon the new PDF document id (metadata includes source/pdf ids, engine, byte counts, duration — no content).
Architecture
API POST /api/documents/{id}/convert/pdf
BPMN service.dms.convert.docx-to-pdf
│
▼
SecuredDocumentConversionService ← DOCUMENT_VIEW + VIEWER (if actor present)
│
▼
DefaultDocumentConversionService ← load bytes → engine → upload PDF sibling
│
▼
DocumentConversionEngine (SPI)
├── GotenbergDocumentConversionEngine
└── LocalLibreOfficeDocumentConversionEngine
Java types:
| Type | Role |
|---|---|
DocumentConversionService |
High-level DMS API (convert + availability) |
DocumentConversionEngine |
Byte-level SPI (no ACL/storage) |
DocumentConversionProperties |
Engine selection + limits (conf + env) |
DocumentConversionResult |
Stable result DTO / process-variable map |
DocumentConversionException |
Stable code for HTTP ProblemDetail / process errors |
HTTP API
Convert
POST /api/documents/{documentId}/convert/pdf
X-Actor-Id: root
X-Workspace-Id: {workspace}
200 response:
{
"sourceDocumentId": "doc-src",
"sourceVersionNumber": 1,
"pdfDocumentId": "doc-pdf",
"pdfVersionId": "ver-pdf",
"pdfVersionNumber": 1,
"pdfName": "Contract.pdf",
"engineId": "gotenberg",
"sourceBytes": 48210,
"pdfBytes": 91200,
"durationMillis": 1840
}
Status
GET /api/documents/conversion/status
{ "available": true, "engineId": "gotenberg" }
Use this for ops/UI gating before offering convert.
Error codes (ProblemDetail.code)
| Code | HTTP | Meaning |
|---|---|---|
DOCUMENT_NOT_FOUND / DOCUMENT_VERSION_NOT_FOUND |
404 | Missing or not visible in workspace |
UNSUPPORTED_SOURCE_TYPE |
400 | Not Word/ODT/RTF |
EMPTY_SOURCE / SOURCE_TOO_LARGE / INVALID_ARGUMENT |
400 | Input validation (size capped while streaming from storage) |
ENGINE_DISABLED / ENGINE_UNAVAILABLE / CONVERSION_TIMEOUT |
503 | Engine off, down, or timed out |
ENGINE_HTTP_* / ENGINE_EXIT_* / INVALID_PDF / PDF_NOT_PRODUCED |
502 | Engine returned a non-success / non-PDF |
ACCESS_DENIED |
403 | Identity path (via secured document/upload) |
Workflow service task
| Field | Value |
|---|---|
| Type | service.dms.convert.docx-to-pdf |
| Implementation | dms-convert-docx-to-pdf |
| Executor | DmsConvertDocxToPdfServiceTaskExecutor |
| Gate | process.module.enabled=true |
| Mode | SYNC_AUTOMATED |
Configuration
| Key | Required | Default | Description |
|---|---|---|---|
documentId |
yes | — | Source DMS document id |
resultVariable |
no | pdfDocument |
Nested result object name (must not be serviceTaskType / serviceTaskStatus) |
Success output envelope
{
"serviceTaskType": "service.dms.convert.docx-to-pdf",
"serviceTaskStatus": "SUCCEEDED",
"pdfDocument": {
"kind": "document-conversion",
"sourceDocumentId": "…",
"sourceVersionNumber": 1,
"pdfDocumentId": "…",
"pdfVersionId": "…",
"pdfVersionNumber": 1,
"pdfName": "….pdf",
"engineId": "gotenberg",
"sourceBytes": 0,
"pdfBytes": 0,
"durationMillis": 0
}
}
Failure messages use [CODE] short message (bounded; no stack traces).
Examples: [PROCESS_MODULE_DISABLED]…, [ENGINE_UNAVAILABLE]…,
[UNSUPPORTED_SOURCE_TYPE]….
Catalog: conf/service-tasks/platform-service-tasks.xml
Implementation: conf/service-task-implementations/platform-service-task-implementations.xml
BPMN sketch
<serviceTask id="toPdf"
name="Convert DOCX To PDF"
inflow:activityType="service.dms.convert.docx-to-pdf"
inflow:documentId="=caseDocumentId"
inflow:resultVariable="pdfDocument" />
Later process steps can read ${pdfDocument.pdfDocumentId} for download,
attach, or e-sign handoff.
Configuration
Loaded by DocumentConversionProperties. Select the engine through the canonical
feature configuration (dms.conversion.engine); the retired
DMS_CONVERSION_ENGINE environment variable does not override it. Connection,
binary, timeout and size settings below still accept their listed environment
overrides before conf/custom_config.properties.
| Property | Env | Default | Notes |
|---|---|---|---|
dms.conversion.engine |
none (canonical feature configuration) | gotenberg |
gotenberg | libreoffice-cli | disabled |
dms.conversion.gotenberg.url |
DMS_CONVERSION_GOTENBERG_URL |
http://gotenberg-dev:3000 |
No trailing slash required |
dms.conversion.libreoffice.path |
DMS_CONVERSION_LIBREOFFICE_PATH |
soffice |
Path to binary |
dms.conversion.timeout-seconds |
DMS_CONVERSION_TIMEOUT_SECONDS |
120 |
Min 10 |
dms.conversion.max-source-mb |
DMS_CONVERSION_MAX_SOURCE_MB |
50 |
Enforced in engines |
Docker Compose (local)
Service gotenberg-dev runs Gotenberg 8. Set canonical
dms.conversion.engine=gotenberg; api-dev receives the URL:
DMS_CONVERSION_GOTENBERG_URL=http://gotenberg-dev:3000
and depends on gotenberg-dev healthy.
docker compose up -d gotenberg-dev
# or with API
docker compose up -d api-dev
Smoke (after upload of a DOCX as {documentId}):
curl.exe -X POST "http://localhost:8080/api/documents/{documentId}/convert/pdf" `
-H "X-Actor-Id: root"
curl.exe "http://localhost:8080/api/documents/conversion/status" -H "X-Actor-Id: root"
Arabic + English expectations
LibreOffice handles:
- Arabic script shaping and presentation forms
- Bidirectional runs (Arabic + Latin in one paragraph)
- RTL page/paragraph direction when set in the Word document
- Common complex layouts (tables, multi-column, headers)
Fonts (baked into the conversion image)
Local Compose builds inflow-gotenberg:local from docker/gotenberg/
instead of bare stock Gotenberg. That image installs common open fonts and
fontconfig aliases so Office family names map to good substitutes:
| Document asks for | Container prefers |
|---|---|
| Arial / Helvetica | Liberation Sans, Noto Sans |
| Calibri | Carlito |
| Cambria | Caladea |
| Times New Roman | Liberation Serif, Noto Serif |
| Courier New | Liberation Mono |
| Tahoma / Verdana / Segoe UI | DejaVu Sans / Noto Sans |
| Traditional Arabic / Sakkal Majalla / Andalus | Amiri |
| Simplified Arabic / Arabic Typesetting | Noto Naskh Arabic |
| Dubai | Noto Sans Arabic |
Also installed: Noto (core/UI/extra), Scheherazade, Lateef, Amiri, Arabeyes, Open Sans, Roboto, FreeFont, DejaVu, Liberation 1+2, Carlito, Caladea.
Rebuild after Dockerfile or docker/gotenberg/fonts/ changes:
docker compose build gotenberg-dev
docker compose up -d gotenberg-dev
docker compose exec gotenberg-dev fc-list :lang=ar family
Drop org-specific licensed TTFs into docker/gotenberg/fonts/ and rebuild
when a tenant standard face is not covered. Do not rely on Windows host fonts
— conversion always runs inside the container.
Real Arial / Office faces (Body CS)
Word often shows Arial (Body CS) for Arabic body text — that is the Arial family used for complex scripts, not a separate downloadable face. For closest match to Word:
# On Windows with licensed Office/Windows fonts (once per machine):
.\scripts\sync-gotenberg-ms-fonts.ps1
docker compose build gotenberg-dev
docker compose up -d gotenberg-dev
That embeds Arial (regular/bold/italic/narrow), Times New Roman, Courier New, Verdana, Tahoma, Calibri, Cambria, Segoe UI, and common Arabic region faces into the private conversion image. Font binaries are gitignored — bake them into your private registry image for production; do not commit proprietary TTFs.
Pixel-perfect match to Microsoft Word is not guaranteed, but with Arial embedded, Body CS Arabic + Latin documents should no longer look like a wrong fallback face.
Fonts and deployment packaging (do not forget)
Fonts are not shipped as loose files next to the Java API. Conversion quality depends entirely on the Gotenberg container image you build and deploy.
Studio / API → POST convert/pdf → Gotenberg container (LibreOffice + fonts)
| What | In git (inflow.ai source)? |
In the Gotenberg image when built? | In a deployment package? |
|---|---|---|---|
| Open fonts (Liberation, Carlito, Noto, Amiri, Scheherazade, …) | Installed by docker/gotenberg/Dockerfile via apt — yes as build recipe |
Yes — always, if you build this Dockerfile | Yes — only if you ship that built Gotenberg image |
| Microsoft Arial / Calibri / Times / … | No — gitignored under docker/gotenberg/fonts/ |
Only if you run .\scripts\sync-gotenberg-ms-fonts.ps1 (or equivalent) before docker build |
Only if CI baked them into a private image |
| API / Studio artifacts | Normal repo packaging | N/A for fonts | Does not include Word fonts |
Word “Arial (Body CS)” is the Arial family for complex scripts (Arabic), not a separate font file. Closest match requires real Arial TTFs in the conversion image.
What every environment must do
- Deploy the custom Gotenberg image from
docker/gotenberg/(not bare stockgotenberg/gotenbergwithout fonts), alongside the API. - Set canonical
dms.conversion.engine=gotenbergand pointDMS_CONVERSION_GOTENBERG_URLat that sidecar. - Do not rely on Windows host fonts at runtime — LO only sees fonts inside the container.
Optional: real Arial for production fidelity
On a licensed build agent (Windows or a font-provisioned Linux builder):
.\scripts\sync-gotenberg-ms-fonts.ps1
docker compose build gotenberg-dev
# tag + push to your private registry, e.g. inflow-gotenberg:prod
- Never commit proprietary
.ttf/.otfto git. - Bake MS fonts only into a private registry image if legal allows embedding for document rendering.
- Open-font-only images remain valid for default Arabic + English quality.
Local operator checklist
# Open fonts only (always from Dockerfile)
docker compose build gotenberg-dev
docker compose up -d gotenberg-dev
# Optional closer Word match (Arial Body CS)
.\scripts\sync-gotenberg-ms-fonts.ps1
docker compose build gotenberg-dev
docker compose up -d gotenberg-dev
docker compose exec gotenberg-dev fc-list | findstr /i arial
Related paths:
docker/gotenberg/Dockerfile— open font packages + aliasesdocker/gotenberg/conf/99-inflow-font-aliases.conf— Office / Body CS name mapsdocker/gotenberg/fonts/— drop-in (gitignored binaries); seefonts/README.mdscripts/sync-gotenberg-ms-fonts.ps1— copy licensed Windows fonts for image builddocker/gotenberg/README.md— short operator notes
Security notes
- Conversion never logs file content or secrets — only ids, sizes, engine, ms.
- Source bytes are read through the same secured download path as human downloads (audit attribution uses the acting principal).
- PDF upload is a normal DMS create in the source folder (encryption, grants, extraction pipeline apply as for any upload).
- Gotenberg is an internal sidecar; do not expose port
3000on public networks in production.
Extending later (same SPI)
Future formats (e.g. XLSX→PDF, PPTX→PDF, HTML→PDF) should:
- Add methods or a typed request on
DocumentConversionService/ engine SPI. - Reuse Gotenberg LibreOffice or Chromium routes as appropriate.
- Keep “new sibling document” semantics unless a product decision says otherwise.
- Register additional catalog types (e.g.
service.dms.convert.sheet-to-pdf) that call the same service layer.
Do not reintroduce pure-POI PDF writers for Word layout fidelity.
Related
- DMS API surface:
docs/manuals/document-management.md - Text extraction (Tika): same manual, extraction section
- Service task catalog:
docs/manuals/service-task-catalog.md - Plan notes:
docs/document-management-plan.md,docs/dms-embed-options.md