Alfresco integration

ARender integrates with Alfresco Content Services (ACS) through the alfresco-provider microservice. The provider is a standalone Spring Boot application that connects to Alfresco via the CMIS AtomPub protocol and exposes the ARender provider REST contract to the Document Service Broker.

1. Overview

The alfresco-provider runs as a Docker container alongside the ARender rendition backend. The Document Service Broker routes document requests to it based on the X-Provider-ID header injected by the BFF or reverse proxy layer. The provider fetches document content from Alfresco and returns it to the broker for rendering.

Figure: Request flow from ARender Horizon to Alfresco through the provider.

2. Prerequisites

ARender rendition backend running (broker, converter, renderer, text handler)
A BFF or reverse proxy that injects the X-Provider-ID: alfresco header or set the configuration registry.default-provider=filenet
Alfresco Content Services 5.x or later with CMIS 1.1 AtomPub endpoint enabled
Network connectivity from the alfresco-provider container to the Alfresco CMIS endpoint
Java 17 or later (if building from source)
Docker (for container deployment)

3. Provider installation

The provider ships as a Docker image. Add it to your Docker Compose stack alongside the rendition services.

docker-compose.yml
services:
  alfresco-provider:
    image: artifactory.arondor.cloud:5001/arender-alfresco-provider:2026.2.0
    environment:
      - "ARENDER_SERVER_ALFRESCO_ATOM_PUB_URL=http://alfresco:8080/alfresco/api/-default-/cmis/versions/1.1/atom"
    ports:
      - "8788:8788"

  service-broker:
    image: artifactory.arondor.cloud:5001/arender-document-service-broker:2026.2.0
    environment:
      - "DSB_KUBEPROVIDER_KUBE.HOSTS_DOCUMENT-CONVERTER=19999"
      - "DSB_KUBEPROVIDER_KUBE.HOSTS_DOCUMENT-RENDERER=9091"
      - "DSB_KUBEPROVIDER_KUBE.HOSTS_DOCUMENT-TEXT-HANDLER=8899"
      - "REGISTRY_PROVIDERS_ALFRESCO_BASE_URL=http://alfresco-provider:8788"
      - "REGISTRY_PROVIDERS_ALFRESCO_WHITELISTED_PARAMS=nodeRef,versionLabel,docs,folder"
      - "REGISTRY_DEFAULT_PROVIDER=alfresco"
    # ... rendition services omitted for brevity

4. Configuration

The provider is configured through Spring Boot externalized configuration. All properties under arender.server.alfresco.* can be set as environment variables.

Application properties

application.properties
# HTTP port (default: 8788)
server.port=8788

# CMIS AtomPub endpoint for the Alfresco server
arender.server.alfresco.atom.pub.url=http://localhost:8080/alfresco/api/-default-/cmis/versions/1.1/atom

Configuration reference

Property	Default	Description
`server.port`	`8788`	HTTP port the provider listens on
`arender.server.alfresco.atom.pub.url`	`http://localhost:8080/alfresco/.../atom`	CMIS 1.1 AtomPub endpoint URL for the Alfresco server

Request parameters

The following query parameters are used by the provider. The broker forwards all incoming request parameters to the provider regardless of whether they appear in REGISTRY_PROVIDERS_ALFRESCO_WHITELISTED_PARAMS.

Parameter	Required	Description
`nodeRef`	Yes (single document or folder)	Alfresco nodeRef (e.g. `workspace://SpacesStore/...`). The `workspace://SpacesStore/` prefix is stripped internally.
`alf_ticket`	Yes	Alfresco authentication ticket for the current user
`user`	Yes	Alfresco username
`versionLabel`	No	Document version label
`docs`	Yes (multi-document)	Comma-separated list of `nodeRef;versionLabel` pairs
`folder`	No	When set with `nodeRef`, opens the nodeRef as a folder and returns its children

The host application passes these parameters to the viewer as a single query string, which reaches the provider untouched:

window.ARender.openDocument('nodeRef=4aa144a5-a0b1-4c2d-8e3f-1234567890ab&user=admin&alf_ticket=TICKET_xxx&versionLabel=1.0');

See Web Component → Parameter contract for the encoding rules, and note that uuid is reserved by the viewer — never use it as an Alfresco parameter name.

note

whitelistedParams controls which parameters form the internal DocumentId used for caching. Parameters outside the list are still forwarded to the provider. Do not add alf_ticket to whitelistedParams: it is a short-lived per-user token, and including it in the cache key causes every request with a new ticket to miss the cache, forcing unnecessary re-rendition of the same document.

Authentication

The provider authenticates to Alfresco using the alf_ticket passed as a query parameter. This is the Alfresco ticket obtained during the user's session (user-delegated authentication). No service account is configured in the provider itself. Ticket validity is managed on the Alfresco side.

The provider maintains a cache of CMIS connections keyed by ticket. Each connection entry expires after 2 hours of inactivity.

Annotation access

The provider exposes annotation CRUD endpoints alongside the document endpoint. Annotations are read and written through the Alfresco CMIS API. The endpoints follow the ARender provider REST contract:

Endpoint	Method	Description
`/documents`	GET	Retrieve document content
`/annotations`	GET	Retrieve all annotations for a document
`/annotations/ids`	GET	Retrieve annotation identifiers
`/annotations/{annotationId}`	GET	Retrieve a single annotation
`/annotations`	POST	Create an annotation
`/annotations/{annotationId}`	PUT	Update an annotation
`/annotations/{annotationId}`	DELETE	Delete an annotation

5. Verification

After starting the provider, verify the integration:

Check the provider is reachable from the broker container:

curl http://alfresco-provider:8788/documents?nodeRef=<nodeRef>&alf_ticket=<ticket>&user=<user>

Expected response: document binary stream with Content-Disposition and Content-Type headers.

Open ARender Horizon and load a document from Alfresco:

window.ARender.openDocument('nodeRef=<nodeRef>&user=<user>&alf_ticket=<ticket>');

Check that the document renders without error.

6. Sample use case

A legal department uses Alfresco to manage contract documents. ARender Horizon is embedded in an Angular application through the <arender-element> Web Component. When a user opens a contract from the Alfresco document library:

The Angular application retrieves the user's Alfresco ticket from the session.
The application calls window.ARender.openDocument('nodeRef=…&user=admin&alf_ticket=…').
The <arender-element> component sends the request to the BFF.
The BFF injects X-Provider-ID: alfresco and forwards to the broker.
The broker calls alfresco-provider:8788/documents?nodeRef=...&alf_ticket=...&user=....
The provider returns the contract PDF via CMIS. The broker renders it and streams pages to the viewer.

7. Common issues

Error	Cause	Solution
`Cannot view document, missing info in query parameters`	`nodeRef`, `alf_ticket`, or `user` is absent from the request	Check the query string passed to `openDocument()` first, then that the BFF forwards it unchanged. The broker forwards all incoming parameters to the provider, so a missing parameter comes from the client or the BFF
Opaque `500` with a null `alf_ticket` in the provider logs	A parameter the provider cannot interpret reached it — typically a value whose separators were not encoded, so `alf_ticket` was parsed as part of the previous value	URL-encode every value before concatenating it into the query string. See Web Component → Parameter contract
`Connection refused` on CMIS call	The `arender.server.alfresco.atom.pub.url` is unreachable from the provider container	Check network connectivity: `curl <atom-pub-url>` from inside the provider container
`IllegalStateException: NOT IMPLEMENTED`	The request mode (DOCUMENT, FOLDER, MULTIDOCUMENT) could not be determined	Ensure `nodeRef` is present for single document mode, or `docs` for multi-document mode

1. Overview​

2. Prerequisites​

3. Provider installation​

4. Configuration​

Application properties​

Configuration reference​

Request parameters​

Authentication​

Annotation access​

5. Verification​

6. Sample use case​

7. Common issues​