DEV Community: Stefan Kopf

Connect LlamaIndex to Alfresco with OpenDMA: Reader, Retriever, and Agent Tools

Stefan Kopf — Fri, 16 Oct 2026 19:28:29 +0000

Connecting LlamaIndex to Alfresco looks simple at first: read documents, extract text, build an index. In practice, the repository context becomes important very quickly.

At that point there are usually three different tasks that all look similar from a distance:

ingest Alfresco content into a LlamaIndex Index, for example a VectorStoreIndex
retrieve content live from Alfresco without building a separate vector store
give an agent tools to browse Alfresco, inspect metadata, search, and read selected documents

The OpenDMA LlamaIndex integration provides all three surfaces. You can use AlfrescoReader, AlfrescoRetriever, or AlfrescoToolSpec, depending on where the repository should stay in the application flow.

The interesting part is not getting bytes out of Alfresco once. The interesting part is keeping the repository context: site, path, type, aspects, properties, permissions, and the query language the repository already has.

The examples in this article are available as a runnable Python project in the OpenDMA Alfresco–LlamaIndex sample repository. You can clone the repository and follow along with the examples below.

OpenDMA between LlamaIndex and Alfresco

OpenDMA is a vendor-neutral API for Document Management and ECM systems. An OpenDMA adaptor plays a similar role to a database driver: it maps a concrete system like Alfresco to the OpenDMA model.

For a Python LlamaIndex application, the important part is the OpenDMA REST endpoint. The application talks to OpenDMA over HTTP. Behind that endpoint, an Alfresco adaptor maps Alfresco objects, folders, documents, content streams, metadata, classes, aspects, and search into the OpenDMA API.

This keeps the LlamaIndex code at the ECM level. The application does not need to scatter Alfresco Content Services REST API calls for nodes, content download, sites, search, aspects, and properties through its own code.

The same application shape can later be used with other ECM systems through other OpenDMA adaptors, for example Documentum, FileNet P8, OnBase, CMOD, OpenText, or SharePoint. In an enterprise deployment, the OpenDMA or ECI layer is also the place where concerns like auditing, identity translation, RBAC, SIEM integration, or identity forwarding belong.

Use `AlfrescoReader` when you want to build an index

AlfrescoReader is the LlamaIndex Alfresco reader for ingestion. Use it when you want to load Alfresco content into a LlamaIndex Index, for example a VectorStoreIndex.

It is a convenience reader for Alfresco repositories exposed through OpenDMA. It uses Alfresco defaults and understands Alfresco site short names. The following example reads from the swsdp site of the standard Alfresco sample setup and uses Docling for legacy Word documents:

from llama_index.core import VectorStoreIndex
from llama_index.readers.docling import DoclingReader
from llama_index.readers.opendma import AlfrescoReader

reader = AlfrescoReader(
    endpoint="http://localhost:7070/opendma/alf",
    username="admin",
    password="admin",
    sites=["swsdp"],
    file_extractor_per_mimetype={
        "application/msword": DoclingReader(),
    },
)

documents = reader.load_data()
index = VectorStoreIndex.from_documents(documents)

Each returned LlamaIndex Document contains the extracted text in text and OpenDMA metadata in metadata.

The sites parameter is useful for Alfresco, but it is not the only loading strategy. The reader also supports document IDs, folder IDs, recursive folder traversal, and OpenDMA queries. When reading a site, do not assume this only means the Document Library. Alfresco sites can also contain wiki pages, links, and other objects below the site folders.

In a production application, this ingestion step usually should not run over the whole repository every time. The normal shape is to run it for new and changed documents and use a persistent vector store.

Keep the Alfresco metadata

With ECM content, metadata is not decoration. It is often the difference between a demo and a usable application.

Documents loaded through OpenDMA do not only carry text chunks. They also carry OpenDMA metadata, Alfresco metadata, and integration metadata. That includes values such as:

opendma:Title
opendma:CheckedOut
alfresco:Site
alfresco:Path
alfresco:cm:name
alfresco:cm:creator
alfresco:cm:accessed
content_state

You can inspect the metadata before inserting documents into an index:

for doc in documents[:3]:
    print(doc.id_)
    print(doc.metadata.get("opendma:Title"))
    print(doc.metadata.get("alfresco:Site"))
    print(doc.metadata.get("alfresco:Path"))

This matters because a real Alfresco repository is not a small set of clean tutorial files. It may contain hundreds of thousands or millions of documents, many teams, meeting notes, contracts, agreements, product specifications, working drafts, and project folders with similar vocabulary.

A plain similarity search across all indexed repository content can return irrelevant chunks. If the question is about a particular project or team site, alfresco:Site and alfresco:Path are useful signals. If checked-out content should be excluded, opendma:CheckedOut can be part of the retrieval logic.

The metadata-aware retrieval tutorial shows this more explicitly. It first indexes the Alfresco sample site, then adds similar content from a second site and demonstrates how retrieval quality degrades when all chunks are treated as one flat pool.

Why not just write a small Alfresco REST reader?

For a prototype, a small custom reader is tempting. Download content from Alfresco, turn it into text, and hand it to LlamaIndex.

That works until the reader needs to know more about the repository.

The code quickly grows from "download this node's content" into site discovery, folder traversal, metadata extraction, content type handling, aspects and properties, path reconstruction, checked-out state, full-text search, MIME-specific parsing, and access-control-aware deployment choices.

OpenDMA puts these concerns behind an ECM abstraction. The LlamaIndex application can still be plain Python, but it does not become the place where the Alfresco integration is rebuilt piece by piece.

This also affects content conversion. The OpenDMA reader decodes plain text directly and delegates richer formats to LlamaIndex file readers through MIME-type mappings. In the example above, legacy Word files are explicitly mapped to Docling. Where repository renditions are part of the OpenDMA/adaptor deployment, they belong in the repository integration layer rather than being reimplemented separately in every application.

Use `AlfrescoRetriever` when you do not want a vector store

Sometimes a vector store is the right choice. If you need semantic retrieval over a curated corpus, AlfrescoReader plus a LlamaIndex index is a good fit.

But building a vector store has a cost. You need to ingest content, extract text, chunk it, calculate embeddings, store the result, and keep it synchronized with Alfresco. In an enterprise repository, access rights and compliance boundaries are often the harder part.

AlfrescoRetriever is the other option. It implements the LlamaIndex retriever API and performs live full-text search against Alfresco through OpenDMA.

from llama_index.core.node_parser import SentenceSplitter
from llama_index.readers.docling import DoclingReader
from llama_index.retrievers.opendma import AlfrescoRetriever

retriever = AlfrescoRetriever(
    endpoint="http://localhost:7070/opendma/alf",
    username="admin",
    password="admin",
    sites=["swsdp"],
    file_extractor_per_mimetype={
        "application/msword": DoclingReader(),
    },
    transformations=[
        SentenceSplitter(chunk_size=1024, chunk_overlap=100),
    ],
    similarity_top_k=8,
)

nodes = retriever.retrieve("meeting notes")

The retriever turns the input string into an Alfresco AFTS TEXT query. If sites is set, it adds site restrictions. The result is converted into LlamaIndex nodes and returned as NodeWithScore.

This is important: AlfrescoRetriever is full-text retrieval, not semantic vector search. The similarity_top_k parameter limits the number of LlamaIndex nodes returned after document loading and node parsing. It is not a vector similarity score.

The advantage is that every retrieval call goes through Alfresco via OpenDMA. There is no up-front ingestion of the whole repository, no embeddings for all content, and no separate copy of repository text that needs to be synchronized.

With effective-user authentication or identity forwarding, Alfresco remains the system deciding what the query can return, including repository permissions and governance/security markings enforced in the Alfresco/OpenDMA path. If the OpenDMA endpoint is called with a shared technical or admin account, the application still has to handle user-level authorization. That part does not disappear.

Agentic retrieval without a vector store

A live full-text retriever works especially well when an agent is allowed to make more than one search attempt.

The first query might be too specific:

localisation of new website design

The next query might use fewer terms:

website design

Or it might focus on the domain word that actually appears in the documents:

localisation

This does not turn Alfresco full-text search into semantic search. A vector store will often retrieve better when the user's words do not match the document text. But an agentic workflow can compensate in many practical cases by changing the query terms and restricting the search to the relevant site.

The Agentic RAG with OpenDMA Retriever tutorial shows this pattern with an agent that uses AlfrescoRetriever inside a search_content tool.

Use `AlfrescoToolSpec` when the agent needs to browse

AlfrescoRetriever is for retrieval. AlfrescoToolSpec is for agents that need to inspect the repository.

That is a different task. Sometimes the answer is not found by retrieving the best text chunks. The agent may first need to list sites, browse a folder, inspect metadata, find a candidate document, and only then read text from it.

AlfrescoToolSpec exposes tools such as:

alfresco_list_sites
opendma_list_children
opendma_get_metadata
opendma_describe_class
opendma_search
opendma_read_text

The tools are configured for a fixed OpenDMA endpoint, account, and repository. This is a better surface for an agent than a generic HTTP client and arbitrary credentials.

from llama_index.core.agent import FunctionAgent
from llama_index.llms.openai import OpenAI
from llama_index.tools.opendma import AlfrescoToolSpec

tool_spec = AlfrescoToolSpec(
    endpoint="http://localhost:7070/opendma/alf",
    username="admin",
    password="admin",
)

agent = FunctionAgent(
    name="AlfrescoAgent",
    tools=tool_spec.to_tool_list(),
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt=(
        "Use repository metadata and listings before reading document text. "
        "Read document text only when metadata is not enough."
    ),
)

The prompt matters. Reading document text is more expensive than listing children or getting metadata. A useful agent should browse first, inspect metadata, and read text only when it has a candidate document.

The text-reading tool returns chunks with continuation tokens. That is important for long documents and large repositories. The agent should not request a full document when the metadata already answers the question.

The tool-calling agent tutorial shows this with an agent that first locates a document, inspects metadata, and only reads text when needed.

Choosing the surface

Start with AlfrescoReader if you need semantic search over a controlled indexed corpus.

Start with AlfrescoRetriever if keeping search live in Alfresco is more important than vector similarity.

Use AlfrescoToolSpec when the agent needs repository navigation, metadata inspection, and selective reading.

Try the examples yourself

The complete runnable examples for AlfrescoReader, AlfrescoRetriever, and AlfrescoToolSpec are available in the GitHub sample project.

Clone the repository to experiment with the different integration approaches in your own environment.

For complete runnable flows, see the existing tutorials:

OpenDMA: https://opendma.org/
LlamaIndex OpenDMA integration: https://github.com/OpenDMA/llama-index-opendma
Basic RAG
Metadata-Aware Retrieval
Agentic RAG with OpenDMA Retriever
Tool-Calling Agent with ToolSpec
Adaptors and ECI Server

In all three cases, the LlamaIndex code works against OpenDMA instead of becoming a custom Alfresco REST integration.

Connecting LangChain to Alfresco Without Writing Another REST Loader

Stefan Kopf — Thu, 15 Oct 2026 08:45:29 +0000

You already have a LangChain application. The content you need is in Alfresco Content Services.

At first, it is tempting to write a small loader around the Alfresco REST API: search a couple of nodes, download the content, extract text, add the chunks to a vector store.

That works for the first demo. Then the edge cases arrive.

You need the path, the site, the content type, custom properties, aspects, checked-out state, versions, permissions, and security markings. For some information, like Type and Aspect definitions, there is no matching Alfresco REST API. Your production repository may also contain custom or exotic file formats for which there is no useful Python implementation. Alfresco Content Services may already be configured to handle those formats, but your LangChain application does not know that.

This is where a simple REST loader quickly turns into a rabbit hole.

OpenDMA provides another boundary. The Alfresco adaptor maps Alfresco into the OpenDMA model. The LangChain integration talks to the OpenDMA REST endpoint and returns normal LangChain Document objects. The same application code can then use the OpenDMA model instead of spreading Alfresco REST details across the RAG pipeline.

Unlike CMIS, OpenDMA is not only an abstraction layer. It is a framework for putting functionality between the repository and the application: auditing, identity translation, content transformations, SIEM integration, and repository federation belong in that layer, not in every LangChain script.

The examples below assume that an OpenDMA endpoint for Alfresco is already available at:

http://localhost:7070/opendma/alf

Install the LangChain OpenDMA Integration with:

pip install langchain-opendma

The examples use admin/admin only to keep the snippets short.

A runnable version of the examples is available here: https://github.com/xaldon/opendma-demo-alfresco-langchain-basics

Load Alfresco Content Into LangChain

Use AlfrescoLoader when you want to ingest Alfresco content into a LangChain application, for example to build a vector store.

from langchain_opendma import AlfrescoLoader
from langchain_opendma.content_handlers import UnstructuredLoaderContentHandler

handler = UnstructuredLoaderContentHandler(
    chunking_strategy="by_title",
    max_characters=4000,
    new_after_n_chars=3000,
    combine_text_under_n_chars=1000,
)

loader = AlfrescoLoader(
    endpoint="http://localhost:7070/opendma/alf",
    username="admin",
    password="admin",
    repository_id="Alfresco",
    sites=["swsdp"],
    content_handlers=[handler],
)

documents = loader.load()

Each returned LangChain Document contains extracted text in page_content and OpenDMA metadata in metadata.

for document in documents[:5]:
    print(document.metadata.get("opendma:Title"))
    print(document.page_content[:200])

The AlfrescoLoader is a convenience loader on top of the generic OpenDMALoader. It adds Alfresco defaults and Alfresco-specific concepts like sites. With sites=["swsdp"], the loader searches the Alfresco site with that short name and loads the document nodes below the matching site folder.

The content handler controls how binary content becomes text. The default handler processes plain text. For Office documents, PDFs, HTML, and similar formats, use an Unstructured or Docling handler.

When the content handler chunks a document, one Alfresco document can become multiple LangChain Document objects. This is the usual shape for vector-store ingestion.

from langchain_core.vectorstores import InMemoryVectorStore
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")
vector_store = InMemoryVectorStore(embeddings)

vector_store.add_documents(documents)

In production, the indexing job normally runs for new and changed documents and writes to a persistent vector store. The important part is not the vector store used in this snippet. The important part is that the documents still carry Alfresco and OpenDMA metadata after loading.

The sample repository contains a small CLI version of this flow. It loads one Alfresco site, builds an in-memory vector store, and then lets you ask questions against it.

Keep The Metadata

The metadata is not decorative.

After loading content from Alfresco nodes, the returned documents can contain metadata such as:

print(document.metadata.get("opendma:Title"))
print(document.metadata.get("opendma:CheckedOut"))
print(document.metadata.get("alfresco:Site"))
print(document.metadata.get("alfresco:Path"))
print(document.metadata.get("alfresco:cm:name"))
print(document.metadata.get("alfresco:cm:creator"))
print(document.metadata.get("alfresco:cm:accessed"))

This matters as soon as the repository stops looking like a small demo. A real Alfresco system can contain meeting notes for many teams, several generations of project documents, contracts, specifications, scanned content, and old versions. A plain similarity search across everything can return text chunks that are close to the question but from the wrong site or the wrong context.

You can use the metadata for filtering:

results = vector_store.similarity_search(
    "state of localisation of the new website design",
    k=10,
    filter=lambda doc: (
        doc.metadata.get("alfresco:Site") == "swsdp"
        and doc.metadata.get("opendma:CheckedOut") is False
    ),
)

This article is not about metadata-aware retrieval as a complete pattern. That deserves its own article. The basic point is simpler: preserve repository metadata from the start. If your loader throws it away, you have already removed information that the retrieval step will need later.

Search Alfresco Live With `AlfrescoRetriever`

A vector store is not always the right first choice.

Building one means extracting content, chunking it, calculating embeddings, storing the chunks, keeping them up to date, and securing a second copy of repository text. That can be useful, but it is not free.

There is also a retrieval quality issue in the other direction. Similarity search is good when the wording of the user question differs from the wording of the document. It is less appropriate when exact terms matter. Product codes, customer numbers, invoice IDs, claim numbers, or part numbers should not be "semantically similar". They should match.

For these cases, use AlfrescoRetriever to run a live full-text search through OpenDMA:

from langchain_opendma import AlfrescoRetriever
from langchain_opendma.content_handlers import UnstructuredLoaderContentHandler

handler = UnstructuredLoaderContentHandler(
    chunking_strategy="by_title",
    max_characters=4000,
    new_after_n_chars=3000,
    combine_text_under_n_chars=1000,
)

retriever = AlfrescoRetriever(
    endpoint="http://localhost:7070/opendma/alf",
    username="admin",
    password="admin",
    repository_id="Alfresco",
    sites=["swsdp"],
    content_handlers=[handler],
    k=8,
)

documents = retriever.invoke("meeting notes")

AlfrescoRetriever implements LangChain's retriever API. The input string is converted into an Alfresco AFTS full-text query, including escaping of special characters. If sites is set, the query is restricted to those Alfresco sites.

The result is still a list of LangChain Document objects.

Because the search runs through Alfresco Content Services via the OpenDMA endpoint, repository access control, governance rules, and security markings remain in the live retrieval path. This is different from querying a separate vector store that contains copied text.

For some applications, this is enough. For others, live full-text search and vector search can both be useful, depending on the question.

The sample repository also contains the same idea as a small live-search command.

Give An Agent Alfresco Tools

Sometimes the agent should not only retrieve chunks. It needs to inspect the repository.

For example:

Which Alfresco sites exist?
Which documents are in this folder?
What type and aspects does this object have?
Is the answer already in metadata?
Which document text should be read?

For that, use AlfrescoToolkit.

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain_opendma import AlfrescoToolkit
from langchain_opendma.content_handlers import DoclingLoaderContentHandler

toolkit = AlfrescoToolkit(
    endpoint="http://localhost:7070/opendma/alf",
    username="admin",
    password="admin",
    repository_id="Alfresco",
    content_handlers=[DoclingLoaderContentHandler()],
)

agent = create_agent(
    model=init_chat_model("openai:gpt-4o-mini", temperature=0),
    tools=toolkit.get_tools(),
    system_prompt=(
        "You answer questions using documents stored in Alfresco. "
        "Use repository tools to find documents and inspect metadata before "
        "reading document text."
    ),
)

The toolkit exposes tools such as:

alfresco_list_sites
opendma_list_children
opendma_get_metadata
opendma_describe_class
opendma_search
opendma_read_text

This gives the agent a different way to work. It can list sites, browse folders, inspect metadata, search, and read selected text chunks.

Reading document text is more expensive than listing children or reading metadata. A good agent prompt should make that visible. Often the agent should first locate candidate documents, inspect their metadata, and only then read text.

The toolkit example in the sample repository runs this as an interactive agent.

This is still the basic toolkit usage. More elaborate agentic RAG flows, where the agent decides how often to search and how to assess retrieved context, are a separate topic.

Why Not Start With cmislib Or Direct REST?

CMIS used to be the obvious abstraction to mention around ECM systems. For new LangChain work, I would not start there.

Apache Chemistry's cmislib project is retired. Its documentation is visibly stale. It may still be useful in old systems, but it is not a good foundation for a new LangChain integration.

Calling Alfresco REST directly is different. It is often the right choice for a small script with a narrow job. The problem starts when that small script becomes the content layer for an LLM application.

Then you need to model:

metadata
Type and Aspect definitions
paths and sites
versions and checked-out state
permissions and security markings
content conversion
query escaping
errors and partial failures

For custom and exotic file formats, you may also end up rebuilding in Python what Alfresco Content Services is already configured to handle.

OpenDMA keeps the Alfresco-specific work in the adaptor and integration layer. The LangChain application sees Document objects, retrievers, and tools.

OpenDMA also models renditions. That matters because production Alfresco repositories often already know how to turn custom formats into PDF or extractable text. A LangChain application should not become the place where all of that repository-specific conversion logic is rebuilt.

Enterprise Notes

The OpenDMA endpoint is also the place where enterprise concerns can be handled without putting them into every LangChain application:

auditing repository requests made by an agent
identity forwarding or token-based sessions
identity translation
RBAC
SIEM integration
federation across multiple ECM systems
repository-side rendition support

Those are adaptor, middleware, and deployment concerns. The LangChain code should stay small.

Which OpenDMA Integration Surface To Use

Use AlfrescoLoader when you want to ingest Alfresco content into a vector store or another knowledge base.

Keep the Alfresco metadata in the LangChain documents from the start. Later filtering and metadata-aware retrieval depend on it.

Use AlfrescoRetriever when live Alfresco full-text search is preferable to a second indexed copy of repository content.

Use AlfrescoToolkit when an agent needs to navigate Alfresco, inspect metadata, search, and read selected text chunks.