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:
- Docker Compose — Recommended for most deployments. See Docker installation.
- Java service — For environments without Docker. See Java installation.
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
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
| Check | Expected |
|---|---|
GET /actuator/health on gateway | {"status":"UP"} |
curl RENDITION_BASE_URL from inside uxopian-ai container | HTTP 200 |
| OpenSearch reachable from uxopian-ai | No 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.
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
| Check | Expected |
|---|---|
GET /uxopian-ai/api/v1/prompts with identity headers | HTTP 200 |
GET /uxopian-ai/api/v1/prompts without headers | HTTP 401 |
| Gateway logs | No 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
| Check | Expected |
|---|---|
POST /uxopian-ai/api/v1/requests with text message | LLM response |
| Admin UI provider status | Provider 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 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
- Open ARender and load a document.
- Click the AI button in the top panel.
- Click Summarize in text format.
- 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.jsnot 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.
uxopian-ai_arender_scripts.zip — arender-config.js, arender-core.js, arender-buttons.js
| Script | Content |
|---|---|
arender-config | Constants only: where Uxopian AI is, which startup script to chain, which scripts to load, the accent colour. |
arender-core | The 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-buttons | The 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.
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' })
]
});
| Helper | Description |
|---|---|
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-aiis 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 (
FDabove) 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 inhost. 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-coreinjects 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-coreloads the other scripts with a timestamp, so a published change shows at the next opening;arender-coreitself 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
| Key | Description |
|---|---|
style.sheet | Comma-separated CSS files loaded in the ARender UI |
arenderjs.startupScript | JavaScript bundle loaded at startup. Must include web-components.js |
topPanel.section.middle.buttons.beanNames | Bean names for top-panel buttons; add aiMenu to include the AI menu |
uxopian.ai.host | Gateway URL used by button JavaScript to call createChat() |
toppanel-arender-ai-configuration.xml — shipped buttons
| Button | Prompt used | Description |
|---|---|---|
| Summarize in text format | summarizeDocumentText | Plain text summary |
| Summarize in Markdown | summarizeDocumentMarkdown | Markdown-formatted summary |
| Detailed comparison | detailedComparison | Point-by-point document comparison |
| Generic comparison | genericComparison | High-level document comparison |
| Translate to French | translate | Translation with language=french payload |
| Translate to English | translate | Translation 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
| Error | Cause | Solution |
|---|---|---|
| AI menu not visible | aiMenu missing from beanNames | Add aiMenu to topPanel.section.middle.buttons.beanNames |
createChat is not defined | web-components.js not loaded | Verify file exists and is in arenderjs.startupScript |
| No document content in response | RENDITION_BASE_URL unreachable | Run docker exec … curl RENDITION_BASE_URL — if NXDOMAIN, join the ARender Docker network |
RENDITION_BASE_URL=http://localhost:8761 fails | localhost = the container, not the host | Use the DSB Docker service name (e.g. dsb-service) |
UXOPIAN_AI_HOST uses a Docker service name | Browsers cannot resolve Docker DNS | Use the public host IP/domain for UXOPIAN_AI_HOST |
| LLM returns "provider not found" | llm.default.provider names a non-existent provider | Align default.provider with an entry in llm.provider.globals (Phase 3.2) |
| 401 on all requests | Provider not configured or path mismatch | Check gateway route path and provider configuration |
| CORS errors in browser | Browser blocked cross-origin requests | Serve ARender and gateway on the same origin, or configure CORS |
Could not fetch startup script '…/arender-core', Status=401 | The viewer cannot authenticate on that route | FlowerDocs viewer: use the GUI-plugin route /gui/plugins/<scope>/gateway/uxopian-ai (see FlowerDocs viewer) |
Integration menus gone after setting arenderjs.startupScript | arender-core not published on the user's tenant, so ARender runs no startup script | Publish the three scripts on that tenant, or remove the property |
AI menu absent, [uxoai] warning in the console | A script of arender-config is not published, or host is wrong | Check the script ids and host in arender-config |
Related pages
- Configure gateway routes —
path,prefix,rewritePath, debug logging - Authentication and gateway
- Web components
- Prompts and templating
- Quickstart with ARender
- Environment variables reference