Skip to main content
Version: v2026.0.0

Integrate with ARender

This guide walks through the complete integration of Uxopian AI into an ARender deployment. Follow the phases in order. Each phase ends with a validation checkpoint. Do not move to the next phase until the current one passes — this avoids context-switching between infrastructure work and UI configuration.

Phase 5 adds the AI menu with ARender XML beans and a JavaScript file deployed next to ARender. With the GWT viewer (arender-ui-springboot, or the flower-docs-arender-hmi viewer FlowerDocs publishes), the menu can instead be written as Uxopian AI scripts that ARender loads at startup, so that changing it needs no image rebuild and no XML: see Define the AI menu as Uxopian AI scripts.

Architecture​

Figure: ARender integration data flow from AI menu click to LLM response.

Integration roadmap​


Phase 1 — Deploy the Uxopian AI stack​

Install and start uxopian-ai and uxopian-gateway. Choose one of the two installation methods:

At minimum, the stack must include uxopian-ai, uxopian-gateway, and opensearch. The ARender services (ui, dsb, renderer, etc.) can be started in parallel but are not required to validate the Uxopian AI stack itself.

Checkpoint 1 — Stack is up​

curl http://<gateway-host>:<port>/actuator/health

Expected response: {"status":"UP"}


Phase 2 — Verify service connectivity​

Docker deployments — read this first

Container-to-container URLs must use Docker service names as hostnames, not localhost. localhost inside a container refers to the container itself, not the host machine. See Docker networking and URL configuration for the full two-URL rule, external network setup, and DNS debugging commands.

2.1 Configure RENDITION_BASE_URL​

Set RENDITION_BASE_URL to the ARender DSB URL as seen by uxopian-ai (container-to-container):

# Same Docker Compose stack — use the DSB service name
RENDITION_BASE_URL=http://dsb-service:8761

# ARender in a separate Docker stack — join its network first, then use its service name
RENDITION_BASE_URL=http://dsb-service:8761

# Java service on the same host (no Docker isolation)
RENDITION_BASE_URL=http://localhost:8761

If ARender runs in a separate Compose stack, uxopian-ai must join its Docker network:

services:
uxopian-ai:
networks:
- uxopian-ai-net
- arender-net # Join the ARender network

networks:
uxopian-ai-net:
arender-net:
external: true
name: <exact-network-name> # From: docker network ls

Note that UXOPIAN_AI_HOST is a browser-side URL — it must point to the gateway using the public host address or IP, not a Docker service name:

UXOPIAN_AI_HOST=http://my-server:8085/uxopian-ai   # ✓ browser-accessible
UXOPIAN_AI_HOST=http://gateway-service:8085/uxopian-ai # ✗ not reachable from browsers

2.2 Confirm the DSB is reachable from uxopian-ai​

docker exec -it <uxopian-ai-container> sh
curl http://dsb-service:8761/ActionsAPI

If nslookup dsb-service returns NXDOMAIN, the containers are not on the same Docker network. Document content will be silently absent in LLM responses if RENDITION_BASE_URL is unreachable.

Checkpoint 2 — Connectivity verified​

CheckExpected
GET /actuator/health on gateway{"status":"UP"}
curl RENDITION_BASE_URL from inside uxopian-ai containerHTTP 200
OpenSearch reachable from uxopian-aiNo connection errors in logs

Phase 3 — Configure and validate authentication​

3.1 Configure the gateway route​

In gateway-application.yaml, configure the route to uxopian-ai with the appropriate auth provider. For development, use DevProvider. For production, replace with your identity provider.

app:
routes:
- id: uxopian-ai
uri: http://uxopian-ai:8080
path: /uxopian-ai/**
provider: DevProvider # Replace with production provider
security:
- path: /.well-known/**
public: true
- path: /assets/**
public: true
- path: /actuator/health
public: true
- path: /v3/**
public: true
- path: /swagger-ui/**
public: true

If requests arrive at the gateway with a different path prefix than the backend expects (e.g., after being proxied by ARender or nginx), you may need rewritePath. See Configure gateway routes for a step-by-step derivation.

3.2 Verify the LLM default provider exists​

In config/llm-clients-config.yml, confirm that llm.default.provider names an entry that actually exists in llm.provider.globals:

llm:
default:
provider: openai # ← must match a provider below
provider:
globals:
- provider: openai # ← must exist
globalConf:
apiSecret: ${OPENAI_API_KEY:}

If the default.provider names a provider not in globals, every chat request will fail at the LLM stage with no visible error in the UI.

3.3 Test authentication​

With DevProvider, inject identity headers directly:

curl -H "X-User-Id: test-user" \
-H "X-User-TenantId: test-tenant" \
-H "X-User-Roles: USER" \
http://<gateway-host>:<port>/uxopian-ai/api/v1/prompts

Expected: HTTP 200 with a list of prompts.

Test interface — Swagger UI

The gateway exposes a Swagger UI at /uxopian-ai/swagger-ui/index.html. Use the Authorize button to pass credentials and test endpoints interactively.

Checkpoint 3 — Authentication works​

CheckExpected
GET /uxopian-ai/api/v1/prompts with identity headersHTTP 200
GET /uxopian-ai/api/v1/prompts without headersHTTP 401
Gateway logsNo provider errors at startup

Phase 4 — Send your first prompt​

Validate the full chain — gateway → uxopian-ai → LLM → response — before touching ARender configuration.

4.1 Open the admin UI​

The admin UI is available at http://<gateway-host>:<port>/uxopian-ai/admin. From here, verify that the LLM provider is listed as active and that the expected prompts are loaded.

4.2 Send a test request​

curl -X POST http://<gateway-host>:<port>/uxopian-ai/api/v1/requests \
-H "X-User-Id: test-user" \
-H "X-User-TenantId: test-tenant" \
-H "X-User-Roles: USER" \
-H "Content-Type: application/json" \
-d '{
"inputs": [{
"role": "USER",
"content": [{ "type": "text", "value": "Hello, confirm you are working." }]
}]
}'

A successful response includes a response field with the LLM reply and a non-null conversationId.

4.3 Test a document extraction call​

To confirm that the ARender plugin is wired correctly, ask the LLM to summarize a document that it can reach via the DSB. If the DSB has a test document available, reference its ID:

-d '{"inputs": [{"role": "USER", "content": [
{"type": "text", "value": "Summarize document <dsb-doc-id>"}
]}]}'

The LLM should call the ARender extraction tool and return content. If the tool fails, verify RENDITION_BASE_URL is correct (Phase 2).

Checkpoint 4 — LLM chain is validated​

CheckExpected
POST /uxopian-ai/api/v1/requests with text messageLLM response
Admin UI provider statusProvider listed as active

The backend stack is validated. You can now configure ARender.


Phase 5 — Embed the AI menu in ARender​

5.1 Download the ARender example package​

The archive contains ARender configuration files to integrate:

arender/
configurations/
arender-plugins.xml # Imports the AI top-panel plugin
arender-custom-client.properties # Sets AI host URL and top-panel buttons
toppanel-arender-ai-configuration.xml # AI menu buttons and JavaScript handlers
public/
web-components.js # JS loaded by ARender in the browser

5.2 Configure the gateway URL​

Set UXOPIAN_AI_HOST to the gateway URL as reachable from user browsers:

UXOPIAN_AI_HOST=http://your-gateway:8085/uxopian-ai

This value propagates into the ARender XML configuration at startup. If it points to the wrong URL, the createChat() call will fail in the browser.

The web-components.js file in arender/public/ also contains a hardcoded UXOPIAN_AI_HOST constant used by comparison buttons. Update it to match your deployment before starting ARender.

5.3 arender-custom-client.properties​

Key properties to verify:

# JS bundle loaded at startup — registers createChat() in the browser
arenderjs.startupScript=web-components.js

# Add aiMenu to the top panel
topPanel.section.middle.buttons.beanNames=...,aiMenu

# Gateway URL used by button JavaScript
uxopian.ai.host=${UXOPIAN_AI_HOST:}
web-components.js is required

web-components.js is loaded by ARender in the browser and registers the createChat() function. Without it, clicking any AI button produces a silent error. Verify the file is present in arender/public/ and referenced in arenderjs.startupScript.

5.4 Restart ARender​

After updating ARender configuration, restart the ARender UI service. The top panel should display the AI button.

Checkpoint 5 — AI menu works in ARender​

  1. Open ARender and load a document.
  2. Click the AI button in the top panel.
  3. Click Summarize in text format.
  4. The chat panel should appear and stream a summary.

If the panel does not appear, open browser developer tools:

  • Network tab: does /uxopian-ai/assets/... return HTTP 200?
  • Console: is createChat is not defined? → web-components.js not loaded.
  • Console: network errors to UXOPIAN_AI_HOST? → URL is wrong or gateway is unreachable.

Define the AI menu as Uxopian AI scripts​

Instead of declaring the AI menu in ARender's XML and deploying a JavaScript file next to ARender, the GWT viewer can take its whole menu from three scripts kept in Uxopian AI. ARender is pointed at them by one JVM system property; after that, an administrator adds, removes or renames an entry from the admin console, publishes, and the next document opening shows it. No image is rebuilt and no ARender XML is touched.

Figure: ARender loads arender-core as its startup script; arender-core loads the configuration and the menu from Uxopian AI and injects the menu in the top panel.

Download

uxopian-ai_arender_scripts.zip — arender-config.js, arender-core.js, arender-buttons.js

ScriptContent
arender-configConstants only: where Uxopian AI is, which startup script to chain, which scripts to load, the accent colour.
arender-coreThe machinery. Loads arender-config from the URL ARender fetched it from, runs the startup script ARender had before, loads the chat web component and the scripts listed in the configuration, injects menus and buttons in the top panel and puts them back whenever ARender redraws it. Offers the helpers below.
arender-buttonsThe menu itself: one uxoai.addMenu call, one line per entry.

1. Publish the three scripts​

In the admin panel, open Scripts and create arender-config, arender-core and arender-buttons with the content of the archive, then publish them (scan, or force-publish). Do it on every tenant whose users open the viewer.

Edit arender-config first:

window.uxoaiConfig = {
// uxopian-ai as seen by the browser: absolute, or relative to ARender when both share an origin.
host: 'https://your-gateway-host/uxopian-ai',
// Startup script ARender had before arender-core, relative to ARender ('' when there is none).
chainedStartupScript: '',
// Scripts loaded once ARender is ready, in this order.
scripts: ['arender-buttons'],
// true: load the drafts instead of the published versions, to try a change before publishing.
useDrafts: false,
accentColor: '#6d28d9'
};

2. Point ARender at arender-core​

Set the arenderjs.startupScript system property on the viewer's JVM:

# ARender Helm chart
viewer:
jvmOpts: "-Xms512m -Xmx512m -Darenderjs.startupScript=https://your-gateway-host/uxopian-ai/api/v1/scripts/arender-core"
# Docker Compose
ui:
image: artifactory.arondor.cloud:5001/arender-ui-springboot:<version>
environment:
JAVA_OPTS: -Xms512m -Xmx1024m -Darenderjs.startupScript=https://your-gateway-host/uxopian-ai/api/v1/scripts/arender-core

A system property outranks every ARender properties file, the arender.properties an integration image embeds included, so it works whatever the image already sets. The URL must end with /api/v1/scripts/arender-core: arender-core derives from it where to load the other scripts.

Publish before you deploy

Once the property is set, ARender runs arender-core and nothing else. If arender-core cannot be fetched (not published on the user's tenant, or a 401), ARender runs no startup script at all — the integration's own script, such as FlowerDocs' menus, included.

When ARender and the gateway are on different origins, list ARender's origin in the gateway's app.cors.allowed-origins; otherwise the chat opens but every request fails with a network error.

3. Write the menu​

arender-buttons declares the menu with the helpers of arender-core:

uxoai.addMenu({
title: 'Uxopian AI',
items: [
uxoai.promptItem('Summarize in text format', 'summarizeDocumentText', function (doc) {
return { documentId: doc.documentId };
}),
uxoai.promptItem('Generic comparison', 'genericComparison', function (doc) {
return { language: 'french', leftDocumentId: doc.documentIds[0], rightDocumentId: doc.documentIds[1] };
}, { icon: 'icon-compare', multiDocument: true }),
uxoai.chatItem('Open chat with AI', 'arenderContext', function (doc) {
return { documentId: doc.documentId };
}, { icon: 'icon-send' })
]
});
HelperDescription
uxoai.addMenu({ title, icon, items })Adds a dropdown to the top panel. Without icon, a robot is drawn in the accent colour.
uxoai.addButton({ title, icon, run })Adds a single button to the top panel.
uxoai.promptItem(label, promptId, payload, options)Menu entry that sends the prompt to the chat as the user's message.
uxoai.chatItem(label, promptId, payload, options)Menu entry that opens the chat with the prompt as system context, for a free conversation.
uxoai.createChat(request)Opens the chat with any request, on the configured host.
uxoai.addStyle(id, css)Adds or replaces a <style> element.
uxoai.onReady(callback)Runs callback(arenderjs) once ARender's JavaScript API is available.

payload receives { documentId, documentIds }: the current document and the documents of the layout (only the current one when a single document is open). options takes icon, an ARender icon class (icon-compare, icon-text, icon-send, icon-list-check, …), and multiDocument: true to grey the entry out unless several documents are open.

To change the menu, edit arender-buttons, publish, and reopen the document.

FlowerDocs viewer​

The flower-docs-arender-hmi viewer already has a startup script, scripts/menus.js, that wires ARender into FlowerDocs. Keep it running by naming it in arender-config, and go through the FlowerDocs GUI-plugin route of the gateway, which is on the viewer's own origin and where the FlowerDocs GUI adds the user's token:

window.uxoaiConfig = {
host: '/gui/plugins/FD/gateway/uxopian-ai',
chainedStartupScript: 'scripts/menus.js',
scripts: ['arender-buttons'],
useDrafts: false,
accentColor: '#6d28d9'
};
viewer:
jvmOpts: "-Xms512m -Xmx512m -Darenderjs.startupScript=/gui/plugins/FD/gateway/uxopian-ai/api/v1/scripts/arender-core"
  • The direct route /gui/gateway/uxopian-ai is not an option from the viewer: the gateway finds no FlowerDocs token for the viewer's session cookie and answers 401. The GUI-plugin route buffers responses, so a chat answer arrives in one block instead of streaming.
  • The scope (FD above) is part of the route, and the tenant of a request is the user's scope: publish the scripts on each scope's tenant, with that scope in host. A viewer shared by several scopes needs the scripts on all of them.

Limitations​

  • ARender's JavaScript API cannot create a top panel button. arender-core injects the menu in the DOM of the GWT top panel, with the panel's own CSS classes (toppanelSection, toppanelButton, dropDownMenuItem): check the menu after each ARender upgrade.
  • Injected menus and buttons are not part of ARender's overflow menu on a narrow screen.
  • GET /api/v1/scripts/{id} is cached for five minutes (max-age=300). arender-core loads the other scripts with a timestamp, so a published change shows at the next opening; arender-core itself is loaded from the property's URL, so a new version of it takes up to five minutes to reach a browser that already loaded it.
  • ARender 2026.3 does not load Font Awesome: use ARender's icon-* classes.

ARender configuration reference​

arender-custom-client.properties​

KeyDescription
style.sheetComma-separated CSS files loaded in the ARender UI
arenderjs.startupScriptJavaScript bundle loaded at startup. Must include web-components.js
topPanel.section.middle.buttons.beanNamesBean names for top-panel buttons; add aiMenu to include the AI menu
uxopian.ai.hostGateway URL used by button JavaScript to call createChat()

toppanel-arender-ai-configuration.xml — shipped buttons​

ButtonPrompt usedDescription
Summarize in text formatsummarizeDocumentTextPlain text summary
Summarize in MarkdownsummarizeDocumentMarkdownMarkdown-formatted summary
Detailed comparisondetailedComparisonPoint-by-point document comparison
Generic comparisongenericComparisonHigh-level document comparison
Translate to FrenchtranslateTranslation with language=french payload
Translate to EnglishtranslateTranslation with language=english payload
Open chat(none)Opens a free-form chat window

To add a new button, add a DropdownMenuItemPresenter bean and reference its ID in the aiMenu bean's orderedNamedList.


Common issues​

ErrorCauseSolution
AI menu not visibleaiMenu missing from beanNamesAdd aiMenu to topPanel.section.middle.buttons.beanNames
createChat is not definedweb-components.js not loadedVerify file exists and is in arenderjs.startupScript
No document content in responseRENDITION_BASE_URL unreachableRun docker exec … curl RENDITION_BASE_URL — if NXDOMAIN, join the ARender Docker network
RENDITION_BASE_URL=http://localhost:8761 failslocalhost = the container, not the hostUse the DSB Docker service name (e.g. dsb-service)
UXOPIAN_AI_HOST uses a Docker service nameBrowsers cannot resolve Docker DNSUse the public host IP/domain for UXOPIAN_AI_HOST
LLM returns "provider not found"llm.default.provider names a non-existent providerAlign default.provider with an entry in llm.provider.globals (Phase 3.2)
401 on all requestsProvider not configured or path mismatchCheck gateway route path and provider configuration
CORS errors in browserBrowser blocked cross-origin requestsServe ARender and gateway on the same origin, or configure CORS
Could not fetch startup script '…/arender-core', Status=401The viewer cannot authenticate on that routeFlowerDocs viewer: use the GUI-plugin route /gui/plugins/<scope>/gateway/uxopian-ai (see FlowerDocs viewer)
Integration menus gone after setting arenderjs.startupScriptarender-core not published on the user's tenant, so ARender runs no startup scriptPublish the three scripts on that tenant, or remove the property
AI menu absent, [uxoai] warning in the consoleA script of arender-config is not published, or host is wrongCheck the script ids and host in arender-config