Process-Aware Enterprise RAG: Announcing the Alfresco Process Services Repository Connector (APS 26.2)

1. Why Workflow Engines Matter for Enterprise RAG

In modern enterprise architectures, organizations frequently pair Alfresco Content Services (ACS) with Alfresco Process Services (APS) to power automated case management and core operational workflows. While ACS holds static files, APS records the living history of business operations: who approved an invoice, what credit risk score was assigned, what comments were submitted by underwriting agents, and what documents were attached during process execution.

Until now, connecting Large Language Models (LLMs) to enterprise workflow data required complex custom ETL pipelines that stripped out BPMN state, discarded form variables, and lost crucial candidate group access controls.

The new Alfresco Process Services Repository Connector (oc-aps-repository-connector) bridges APS directly to OpenCrawling, allowing enterprise AI assistants and Retrieval-Augmented Generation (RAG) applications to retrieve real-time and historical workflow context safely.

2. Core Capabilities: From BPMN Instances to Vector Stores

Targeted specifically for Alfresco Process Services version 26.2.0 (via the Enterprise REST API under /activiti-app/api/enterprise), the connector provides complete coverage of BPMN operational data:

• Historic & Active Instance Crawling: Paginates through workflow executions via POST /historic-process-instances/query, capturing process definition keys, execution durations, start/end timestamps, and initiator IDs.
• Dynamic BPMN Variable Extraction: Automatically resolves typed process variables (strings, doubles, booleans, dates, JSON payloads) via GET /historic-process-instances/{id}/variables and maps them into structured metadata attributes prefixed with aps_var_.
• Candidate Group & User ACLs: Evaluates assigned user tasks and candidate groups via POST /tasks/query, transforming BPMN roles into Open Ingestion Standard (OIS) security.permissions.
• Workflow Attachment Ingestion: Recursively discovers documents and attachments uploaded to process instances (/process-instances/{id}/content) or user tasks (/tasks/{id}/content), downloads raw binary content streams via /content/{id}/raw into the Claim-Check store, and extracts text using Apache Tika.
• Model Context Protocol (MCP) Integration: The included ApsMcpClient connects to the APS MCP Server to dynamically discover deployed workflow definitions, variable schemas, and candidate groups over standard JSON-RPC 2.0.

3. Zero-Trust Security & Candidate Group Enforcement

A critical hazard in enterprise generative AI is context leakage: an employee asking an AI assistant a question about corporate financials must never see invoices or sensitive approval decisions intended solely for the executive committee or finance department.

The APS connector addresses this by inspecting the workflow initiator, assigned users, and candidate groups for every process instance and attachment. These identities are translated directly into OIS security permissions:

{
  "id": "aps://process-instances/10042",
  "action": "UPSERT",
  "metadata": {
    "aps.processDefinitionKey": "invoiceApproval",
    "aps.businessKey": "INV-2026-9041",
    "aps_var_invoiceNumber": "INV-2026-9041",
    "aps_var_amount": "14500.50"
  },
  "security": {
    "inheritanceEnabled": false,
    "permissions": [
      { "identity": "finance_agent_1", "identityType": "user", "access": "read" },
      { "identity": "group:finance-managers", "identityType": "group", "access": "read" },
      { "identity": "group:accounting", "identityType": "group", "access": "read" }
    ]
  }
}

When an AI agent queries OpenCrawling's Secure Model Context Protocol (MCP) Server, permissions are verified in real time against the user's active session, strictly preventing unauthorized data retrieval.

4. Configuring the APS Repository Connector

Enabling the connector in OpenCrawling is simple. You can configure it via application.yml or environment variables:

Docker Compose Example

services:
  oc-crawler:
    image: opencrawling/oc-runtime:latest
    environment:
      CONNECTOR_TYPE: aps
      SCAN_PATH: /
      APS_URL: http://aps:8080/activiti-app/api/enterprise
      APS_USERNAME: admin@app.activiti.com
      APS_PASSWORD: admin
      APS_INCLUDE_VARIABLES: "true"
      APS_INCLUDE_TASKS: "true"
      APS_INCLUDE_ATTACHMENTS: "true"

5. Enterprise Licensing & Testing Modes

Because Alfresco Process Services is an enterprise commercial product, the connector and its test suites are designed to support two modes:

1. Community Evaluation Mode (Unlicensed): If no enterprise license is provided, the connector connects to APS, verifies authentication, checks health, and performs queries against an empty repository. The test scripts (test-aps-connector.sh and test-aps-decoupled.sh) detect the unlicensed state gracefully and validate the pipeline cleanly.
2. Enterprise Licensed Mode: If you possess Alfresco license files (activiti.lic and/or transform.lic), the test runner automatically discovers them from ~/.activiti/enterprise-license/ or environment variables, mounts them into the container, registers the license via POST /activiti-app/api/enterprise/license, imports a sample BPMN 2.0 invoice approval workflow, and seeds real process instances with variables and attachments.