48 KiB
MCP Integration Architecture
1. The Core Concept
The Model Context Protocol (MCP) is an open standard that enables LLMs to discover and invoke tools from external systems through a unified protocol. Instead of building custom integrations for each enterprise application, MCP provides standardized tool discovery and execution.
For Dynamixs.AI, this means:
- As MCP Server: External AI systems (e.g., Claude Desktop) can interact with our workflow engine.
- As MCP Client: Our platform can leverage tools from external systems (e.g., SAP, Salesforce) without custom adapters.
1.1. The Problem
LLMs make mistakes. When an AI agent can directly execute actions across multiple systems, a single misinterpretation can cause significant damage:
User: "Create the new partner Müller GmbH"
LLM interprets: Partner → Supplier (wrong: should be Customer)
LLM executes: 1. Create supplier in SAP
2. Start invoice process in Imixs
3. Send invoice to supplier
Result: Wrong data in two systems, manual cleanup required by human interaction.
Autonomous AI execution without human oversight creates unacceptable business risk.
1.2.The Solution
We combine MCP's integration capabilities with Dynamixs.AI's process control. The AI proposes actions – humans approve them through a standard BPMN process:
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ AI creates │────►│ Human reviews │────►│ Workflow │
│ action plan │ │ and approves │ │ executes │
└─────────────┘ └──────────────────┘ └─────────────┘
This approach delivers:
- AI-powered automation – intelligent tool selection and planning
- Human oversight – every critical action requires explicit approval
- Full audit trail – all decisions documented in the workflow history
- Unlimited customization – the standard AI execution process serves as a foundation; organizations can extend it into complex, domain-specific workflows with additional approval steps, escalations, conditional routing, or multi-level authorization
2. Architecture
2.1 High-Level Overview
The architecture consists of five core components:
┌──────────────────────────────────────────────────────────────────────────────┐
│ Dynamixs.AI │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ AI Orchestrator │ │
│ │ │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Tool Registry │ │ LLM Client │ │ MCP Client │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────┐ ┌────────────────────────┐ │
│ │ AI Execution Process │ │ External MCP Servers │ │
│ │ (BPMN) │ │ (SAP, Salesforce...) │ │
│ │ │ └────────────────────────┘ │
│ │ • Human Review Task │ │
│ │ • Action Execution │ │
│ │ • Audit Trail │ │
│ └─────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ Imixs Workflow Engine │ │
│ │ + Internal REST Services │ │
│ └─────────────────────────────┘ │
│ │
├──────────────────────────────────────────────────────────────────────────────┤
│ MCP Server Endpoint │
│ (exposes tools externally) │
└──────────────────────────────────────────────────────────────────────────────┘
│
▼
External MCP Clients
(Claude, SAP, etc.)
Components
| Component | Description |
|---|---|
| AI Orchestrator | Central coordinator. Receives user requests, interacts with the LLM to create execution plans, and initiates the approval workflow. |
| Tool Registry | Maintains a catalog of all available tools – both internal Imixs services and external tools discovered from MCP servers. Provides tool definitions to the LLM for function calling. |
| LLM Client | Connects to the local LLM (llama.cpp via OpenAI API). Sends prompts with tool definitions and receives structured execution plans. |
| MCP Client | Discovers and invokes tools from external MCP servers (e.g., SAP, Salesforce). Translates MCP protocol calls into the Tool Registry format. |
| MCP Server Endpoint | Exposes Imixs workflow capabilities to external AI systems. Allows tools like Claude Desktop or third-party orchestrators to start processes or query tasks. |
| AI Execution Process | A BPMN process that handles human review and approval. Stores the execution plan, presents it to the user, and executes approved actions through the workflow engine. |
2.2 Request Flow
The following sequence illustrates how a user request flows through the system:
┌──────┐ ┌──────────────┐ ┌─────┐ ┌──────────────┐ ┌─────────┐
│ User │ │ Orchestrator │ │ LLM │ │ AI Execution │ │ Workflow│
└──┬───┘ └──────┬───────┘ └──┬──┘ │ Process │ │ Engine │
│ │ │ └──────┬───────┘ └────┬────┘
│ 1. Request │ │ │ │
│───────────────►│ │ │ │
│ │ │ │ │
│ │ 2. Get tools │ │ │
│ │────────────────│ │ │
│ │ (from Tool Registry) │ │
│ │ │ │ │
│ │ 3. Create plan │ │ │
│ │───────────────►│ │ │
│ │ │ │ │
│ │ 4. Return plan │ │ │
│ │◄───────────────│ │ │
│ │ │ │ │
│ │ 5. Start process │ │
│ │───────────────────────────────►│ │
│ │ │ │ │
│ 6. Review task appears in user's tasklist │ │
│◄────────────────────────────────────────────────│ │
│ │ │ │ │
│ 7. Approve │ │ │ │
│────────────────────────────────────────────────►│ │
│ │ │ │ │
│ │ │ │ 8. Execute │
│ │ │ │─────────────────►│
│ │ │ │ │
│ 9. Result │ │ │ │
│◄───────────────────────────────────────────────────────────────────│
│ │ │ │ │
- User submits a natural language request (e.g., "Create customer Müller GmbH in SAP and start invoice process")
- Orchestrator retrieves available tools from the Tool Registry (internal + external MCP tools)
- Orchestrator sends the request along with tool definitions to the LLM
- LLM analyzes the request and returns a structured execution plan
- Orchestrator creates a new AI Execution Process instance with the plan attached
- A review task appears in the user's tasklist
- User reviews the plan and approves (or rejects/modifies)
- Upon approval, the workflow engine executes the planned actions
- User receives confirmation with results
2.3 AI Orchestrator
Dynamixs.AI already provides powerful LLM integration within BPMN processes. Process designers can embed prompts directly into the model using BPMN Text Annotations. A generic plugin evaluates these annotations at runtime, calls the LLM, and uses the response to drive process decisions – for example, routing a document based on its AI-classified content or generating a summary for the next approver.
This approach works well for predefined workflows. The process designer knows in advance which LLM calls are needed and where. The prompts are fixed, the integration points are explicit, and the sequence flow controls everything.
But what happens when the user's intent is not predefined? When a user types "Create a customer in SAP and start an invoice process", there is no existing BPMN model for that specific request. The system would need a process for every possible combination of actions – which is impossible.
This is where the AI Orchestrator comes in. Instead of embedding AI into fixed workflows, the Orchestrator inverts the relationship: The AI creates the workflow. The user expresses intent in natural language, the LLM selects the appropriate tools and assembles an execution plan, and the result flows into a BPMN process for human approval and execution.
The two approaches complement each other:
Key Design Decisions:
| Approach | Use Case |
|---|---|
| BPMN with embedded AI | Predefined processes where AI enhances specific steps (classification, summarization, decision support) |
| AI Orchestrator | Ad-hoc requests where the user defines the goal and AI determines the steps |
The AI Orchestrator does not replace the existing LLM integration. It adds a new capability: Letting users initiate complex, cross-system actions through natural language – with full BPMN-based control over execution.
2.3.1 Implementation
The AI Orchestrator is the central coordinator between the user, the LLM, and the workflow engine. It has one primary job: Transform a natural language request into a controlled, auditable workflow process.
It does not execute actions itself. It does not make decisions. It coordinates.
Think of it as a receptionist: It receives the request, consults with the right people (the LLM), prepares the paperwork (the execution plan), and hands it off to the proper department (the workflow engine). The receptionist never performs the actual work – but nothing happens without going through them first. The Orchestrator is responsible for:
- Receiving requests – Natural language input from users via UI, chat interface, or API
- Gathering context – Retrieving available tools, user permissions, and relevant business data
- Consulting the LLM – Sending the request along with tool definitions and receiving a structured execution plan
- Quality control – Checking if the LLM response is valid, complete, and within acceptable confidence levels
- Initiating the workflow – Creating an AI Execution Process instance that contains the plan for human review
@ApplicationScoped
public class AiOrchestrator {
@Inject
ToolRegistry toolRegistry;
@Inject
LlmClient llmClient;
@Inject
WorkflowService workflowService;
/**
* Processes a user request and starts an AI Execution Process.
*
* @param prompt The natural language request
* @return The created workitem containing the execution plan
*/
public ItemCollection processRequest(String prompt) {
// 1. Get available tools
List<ToolDefinition> tools = toolRegistry.getAllTools();
// 2. Create execution plan via LLM
ExecutionPlan plan = llmClient.createPlan(prompt, tools);
// 3. Start AI Execution Process
ItemCollection workitem = new ItemCollection();
workitem.setModelVersion("ai-execution-1.0");
workitem.setTaskID(1000);
workitem.setItemValue("ai.prompt", prompt);
workitem.setItemValue("ai.plan", plan.toJson());
workitem.setItemValue("ai.confidence", plan.getConfidence());
return workflowService.processWorkItem(workitem);
}
}
2.3.2 How This Component Works
When a request arrives, the Orchestrator follows a strict sequence:
Step 1: Collect available tools. The Orchestrator asks the Tool Registry for all tools the current user is allowed to use. This includes internal Imixs services and external MCP tools. The result is a list of tool definitions with names, descriptions, and parameter schemas.
Step 2: Build the LLM prompt. The Orchestrator constructs a prompt that contains the user's request, the available tools, and any relevant context (e.g., current user, business domain). The prompt instructs the LLM to analyze the request and return a structured execution plan.
Step 3: Call the LLM. The request goes to the local LLM via the OpenAI-compatible API. The LLM responds with a JSON structure containing the selected tools, parameters, execution order, and a confidence score.
Step 4: Validate the response. The Orchestrator checks if the plan is well-formed. Are all referenced tools valid? Are required parameters present? Is the confidence score above the minimum threshold? If validation fails, the Orchestrator may retry with a refined prompt or return an error to the user.
Step 5: Start the AI Execution Process. The Orchestrator creates a new workflow instance of type "AI Execution Request". The execution plan is stored as process data. From this point on, the workflow engine takes over – the Orchestrator's job is done.
The Orchestrator is intentionally simple. It contains no business logic, no tool-specific code, no execution capabilities. This separation ensures that all critical actions flow through the controlled environment of the BPMN process.
2.4 Tool Registry
The AI Orchestrator needs to tell the LLM what actions are possible. Without this information, the LLM would have no idea what tools exist, what they do, or how to call them. It would be like asking someone to cook dinner without telling them what ingredients and appliances are available.
In a simple system with only internal services, this could be hardcoded. But Dynamixs.AI operates in a heterogeneous environment. Some tools are internal REST services – starting a process, querying tasks, updating documents. Others come from external MCP servers – creating a customer in SAP, sending an email through Microsoft Graph, querying Salesforce records. New tools may be added at runtime when an administrator connects a new MCP server.
Managing this complexity requires a dedicated component. The Tool Registry serves as the single source of truth for all available tools – regardless of where they come from or how they are implemented.
2.4.1 Implementation
The Tool Registry is a catalog of tool definitions. Each definition describes one atomic action the system can perform: a name, a description, input parameters, and metadata about the tool's origin and risk level. The registry has three core responsibilities:
Aggregation. It collects tools from multiple sources. Internal tools are registered at application startup. External tools are discovered dynamically by querying connected MCP servers. The registry merges these into a unified catalog.
Normalization. Tools from different sources use different formats. Internal services might be defined as Java methods with annotations. MCP servers deliver tool definitions in their own JSON schema. The registry normalizes everything into a consistent format that the LLM can understand.
Access Control. Not every user should see every tool. A clerk should not be offered tools that delete financial records. The registry filters the available tools based on the current user's roles and permissions. When the Orchestrator asks for tools, it receives only those the user is authorized to use.
The Tool Registry does not execute tools. It only knows about them. Execution is handled by other components – internal services are called directly, MCP tools go through the MCP Client.
2.4.2 How it works
The Tool Registry operates in two phases: initialization and runtime.
Initialization Phase
At application startup, the registry loads internal tool definitions. These are typically defined through annotations on service methods or through configuration files. Each internal tool maps directly to an existing REST endpoint or service method in Dynamixs.AI – for example, imixs.startProcess, imixs.getOpenTasks, or imixs.completeWorkitem.
Next, the registry contacts all configured MCP servers. For each server, it calls the standard MCP discovery endpoint to retrieve the server's tool catalog. These external tools are added to the registry with metadata indicating their origin – for example, sap.createCustomer or salesforce.queryAccounts.
If an MCP server is unavailable at startup, the registry logs a warning but continues. Missing servers can be re-discovered later through a manual refresh or scheduled polling.
Runtime Phase
When the Orchestrator requests the tool catalog, the registry performs the following steps:
First, it identifies the current user and their roles. This information comes from the security context of the current request.
Second, it filters the catalog. Each tool definition includes a required permission level. Tools that exceed the user's authorization are excluded from the result.
Third, it formats the output. The LLM expects tool definitions in a specific JSON schema compatible with OpenAI function calling. The registry transforms its internal representation into this format.
The result is a list of tool definitions ready for inclusion in the LLM prompt. The Orchestrator receives only what it needs – no internal implementation details, no execution logic, just clean definitions.
Dynamic Updates
The tool catalog is not static. Administrators can connect new MCP servers at runtime. When this happens, the registry discovers the new server's tools and adds them to the catalog. Existing workflow instances are not affected – they continue with the tools that were available when they started. New requests see the updated catalog immediately.
This dynamic behavior is essential for enterprise environments where integrations evolve over time. Connecting a new system should not require application restarts or code deployments.
2.5 MCP Client
The Tool Registry knows about external tools. But knowing about a tool and actually calling it are two different things. When the workflow engine needs to execute sap.createCustomer, something has to translate that request into an actual call to the SAP MCP server, handle the response, and deal with any errors that occur.
This is not a trivial task. MCP is a protocol with its own conventions for authentication, request formatting, error handling, and response parsing. Each MCP server might have slightly different behavior. Network issues can cause timeouts. Servers might be temporarily unavailable. Responses need validation before they can be trusted.
Without a dedicated component, this complexity would leak into the workflow engine, the Orchestrator, or worse – into individual BPMN process scripts. Every place that needs to call an external tool would implement its own HTTP calls, its own error handling, its own retry logic. This leads to inconsistency, bugs, and maintenance nightmares.
The MCP Client encapsulates all of this. It provides a clean interface: Give me a tool name and parameters, and I will handle the rest.
2.5.1 Implementation
The MCP Client is the gateway to the external world. It handles all communication with external MCP servers – discovery, invocation, and error management.
The client has three core responsibilities:
Discovery. When the application needs to know what tools an MCP server offers, the client queries the server's discovery endpoint. It retrieves the list of available tools, their descriptions, and their parameter schemas. This information feeds into the Tool Registry.
Invocation. When a workflow needs to execute an external tool, the client translates the request into the MCP protocol format, sends it to the appropriate server, waits for the response, and returns the result in a normalized format that Dynamixs.AI can process.
Resilience. External systems fail. Networks have latency. Servers go down for maintenance. The MCP Client handles these realities gracefully. It implements timeouts, retries with exponential backoff, circuit breakers for repeatedly failing servers, and meaningful error messages when things go wrong.
The MCP Client does not decide which tools to call. That decision is made by the LLM and approved by the user. The client simply executes what it is told – reliably and predictably.
2.5.2 How it works
The MCP Client manages a pool of server connections. Each connection represents one external MCP server – SAP, Salesforce, Microsoft Graph, or any other MCP-compliant system.
Server Configuration
Administrators configure MCP servers through the Dynamixs.AI administration interface. For each server, they provide:
- A unique identifier (e.g., sap-production, salesforce-emea)
- The server's base URL
- Authentication credentials (API keys, OAuth tokens, or other mechanisms)
- Optional settings like timeout values and retry policies
The client stores these configurations and establishes connections on demand. It does not maintain permanent connections – each request opens a new HTTP connection, which aligns with the stateless nature of REST-based MCP servers.
Tool Discovery
When the Tool Registry requests tools from an external server, the MCP Client performs a discovery call. It sends a request to the server's /tools endpoint (or equivalent, depending on MCP version) and receives a JSON response listing all available tools.
The client parses this response and transforms it into the internal tool definition format. It adds metadata about the server origin so that later invocations know where to route requests. The transformed definitions are returned to the Tool Registry for inclusion in the catalog.
Discovery happens at application startup and can be triggered manually by administrators when they know a server's capabilities have changed.
Tool Invocation
When the workflow engine executes an external tool, the MCP Client receives a request containing:
- The fully qualified tool name (e.g., sap.createCustomer)
- The parameters as a key-value map
- Context information like correlation IDs for tracing
The client identifies the target server from the tool name prefix. It constructs an MCP-compliant request payload, adds authentication headers, and sends the request to the server's execution endpoint.
The response follows one of three paths:
Success. The server returns a result. The client extracts the relevant data, transforms it into a normalized format, and returns it to the workflow engine. The workflow continues with the next step.
Transient failure. The server returns a temporary error (timeout, rate limit, server overload). The client waits and retries according to its retry policy. If all retries fail, it returns an error that the workflow can handle – perhaps by creating a manual task for an administrator.
Permanent failure. The server returns a definitive error (invalid parameters, resource not found, permission denied). The client returns this error immediately without retry. The workflow decides how to proceed – maybe by notifying the user, maybe by taking an alternative path.
Security Considerations
The MCP Client handles sensitive data. Authentication credentials must be stored securely. Request and response payloads might contain personal or financial information that should not be logged in full. The client implements appropriate safeguards:
- Credentials are stored encrypted and never logged
- Payload logging is configurable and defaults to minimal (tool name and status only)
- All communication uses TLS
- Authentication tokens are refreshed automatically when they expire
2.6 MCP Server Endpoint
So far, we have discussed how Dynamixs.AI consumes external tools. But integration is a two-way street. Just as our platform benefits from calling SAP or Salesforce, other systems might benefit from calling us.
Consider a consultant working in Claude Desktop. They want to check the status of an approval process in Dynamixs.AI. Without an MCP Server, they would have to switch applications, log into Dynamixs.AI, navigate to the right screen, and search for the process. With an MCP Server, they simply ask Claude: "Show me the open approval tasks for project Alpha." Claude calls our MCP endpoint, retrieves the data, and presents it directly.
Or consider a scenario where SAP needs to trigger a Dynamixs.AI workflow. When a new purchase order is created in SAP, an approval process should start in our system. If SAP's AI orchestrator can discover and call our tools, this integration becomes configuration rather than custom development.
The MCP Server Endpoint transforms Dynamixs.AI from a closed system into a participant in a larger ecosystem. We become a tool provider, not just a tool consumer.
2.6.1 Implementation
The MCP Server Endpoint exposes selected Dynamixs.AI capabilities as MCP-compliant tools. External AI systems can discover what we offer and invoke our tools using the standard MCP protocol.
The endpoint has three core responsibilities:
Tool Publication. It defines which internal capabilities are exposed externally. Not everything should be accessible from outside – only a curated set of tools that make sense for external consumption. Each published tool has a clear description, well-defined parameters, and documented behavior.
Protocol Compliance. External clients expect MCP-standard behavior. The endpoint implements the required discovery and invocation interfaces according to the MCP specification. Any MCP-compliant client should be able to connect without custom integration code.
Security Enforcement. External access requires strict security. Every request must be authenticated. Every tool invocation must be authorized. The endpoint validates that the caller has permission to perform the requested action before anything executes. The MCP Server Endpoint is not a full mirror of our internal capabilities. It is a carefully designed external API that exposes what we choose to share, in the way we choose to share it.
2.6.2 How it works
The MCP Server Endpoint is implemented as a set of JAX-RS resources within the Dynamixs.AI application. It exposes two primary interfaces: discovery and invocation.
Tool Discovery
External clients begin by asking what tools are available. They call the discovery endpoint – typically a GET request to /mcp/tools. The endpoint responds with a JSON array of tool definitions.
Each tool definition includes:
- A unique name (e.g., dynamixs.startProcess, dynamixs.getOpenTasks)
- A human-readable description explaining what the tool does
- A parameter schema defining required and optional inputs
- Metadata like version information and documentation links
The discovery response is generated dynamically. It reflects the current state of published tools, filtered by the caller's permissions. An authenticated administrator might see management tools that are hidden from regular API consumers.
Tool Invocation
When an external client wants to execute a tool, it sends a POST request to the invocation endpoint – typically /mcp/execute. The request body contains the tool name and parameters in JSON format.
The endpoint processes the request through several stages:
Authentication. The request must include valid credentials – an API key, OAuth token, or other configured mechanism. Invalid or missing credentials result in immediate rejection.
Authorization. The endpoint checks whether the authenticated caller is permitted to invoke the requested tool. Permissions are configured per tool and per client. A client might be allowed to query tasks but not to complete them.
Validation. The parameters are validated against the tool's schema. Missing required parameters, wrong data types, or invalid values are rejected with descriptive error messages.
Execution. The endpoint translates the MCP request into an internal service call. This might mean calling the WorkflowService to start a process, the DocumentService to retrieve a file, or any other internal component. The execution happens within a proper transaction context with full audit logging.
Response. The result is transformed into MCP-compliant format and returned to the caller. Success responses include the operation result. Error responses include error codes and messages that help the caller understand what went wrong.
Published Tools
The initial set of published tools focuses on core workflow operations:
| Tool | Description |
|---|---|
| dynamixs.startProcess | Creates a new process instance of a specified type |
| dynamixs.getOpenTasks | Retrieves tasks assigned to a user or group |
| dynamixs.getProcessStatus | Returns the current state of a process instance |
| dynamixs.completeTask | Completes a task with provided form data |
| dynamixs.searchWorkitems | Searches for workitems matching specified criteria |
| dynamixs.getDocument | Retrieves a document attached to a process |
This list will evolve based on real-world usage. Tools that prove valuable will be enhanced. Tools that create security concerns might be restricted or removed. The goal is a stable, useful API – not a complete exposure of every internal function.
Security Considerations
The MCP Server Endpoint is an attack surface. It accepts requests from external systems over the network. Security is not optional – it is fundamental to the design.
All communication requires TLS. Plain HTTP requests are rejected.
Authentication is mandatory. Anonymous access is not supported. Clients must be registered and issued credentials before they can make any calls.
Rate limiting prevents abuse. Clients that send too many requests in a short period are throttled. This protects the system from accidental overload and deliberate denial-of-service attempts.
Audit logging captures every request. Who called what, when, with which parameters, and what was the result. This creates accountability and supports incident investigation.
Input validation is strict. The endpoint assumes all input is potentially malicious. Parameters are validated, sanitized, and bounded before use. SQL injection, path traversal, and similar attacks are blocked by design.
2.7 AI Execution Process
Everything we have discussed so far – the Orchestrator, the Tool Registry, the MCP Client – is infrastructure. Important infrastructure, but infrastructure nonetheless. None of it matters if we cannot answer one fundamental question: Who controls the AI?
The uncomfortable truth about AI systems is that they make mistakes. They misinterpret requests. They hallucinate capabilities. They confidently execute the wrong action. In a demo, this is embarrassing. In a production system handling real business data, this is dangerous.
Most AI integration approaches try to solve this through technical means: Better prompts. Confidence thresholds. Guardrails and filters. These help, but they do not eliminate the problem. An LLM that is 95% accurate still fails one in twenty times. In a system processing hundreds of requests per day, that means multiple failures per week.
The real solution is not technical – it is organizational. Humans must remain in control. The AI proposes, the human decides. This is not a limitation to work around. It is a feature to embrace.
And here is where Dynamixs.AI has an unfair advantage: We are a process management platform. Controlled execution with human decision points is literally what we do. We do not need to invent a new approval mechanism. We do not need to build a task management system. We do not need to implement audit trails. We have all of this already.
The AI Execution Process is simply a BPMN process like any other in our system. It uses the same engine, the same task management, the same user interface, the same audit logging. The only difference is what triggers it and what it contains.
2.7.1 Implementation
The AI Execution Process is a BPMN workflow that governs the lifecycle of an AI-generated execution plan. It receives the plan from the Orchestrator, presents it to a human for review, and executes the approved actions through the workflow engine.
The process has four core responsibilities:
Presentation. The execution plan is technical – a JSON structure with tool names, parameters, and metadata. Users need to see this in a human-readable form. The process transforms the plan into a clear summary: What will happen, in what order, affecting which systems.
Decision Capture. The user reviews the plan and makes a decision: Approve, reject, or modify. This decision is recorded as part of the process history. Not just what was decided, but who decided it, when, and with what justification.
Controlled Execution. Upon approval, the process executes each action in the plan. This happens sequentially, with error handling at each step. If one action fails, the process can pause, notify the user, and wait for guidance rather than blindly continuing.
Result Documentation. Every action's outcome is recorded. Success or failure, returned data, error messages – everything becomes part of the permanent process record. Weeks or months later, anyone can look at the process history and understand exactly what happened.
2.7.1 How it works
The AI Execution Process follows a straightforward flow with well-defined stages.
Stage 1: Initialization
The Orchestrator creates a new process instance and populates it with the execution plan. The process data includes:
- The original user prompt
- The complete execution plan as generated by the LLM
- Metadata: timestamp, requesting user, confidence score, source context
- A human-readable summary generated from the plan
The process starts in a "Pending Review" state. A task appears in the user's task list.
Stage 2: Human Review
The user opens the review task and sees a structured presentation of what the AI wants to do:
╔══════════════════════════════════════════════════════════════════╗
║ AI Execution Request ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ Your request: ║
║ "Create customer Müller GmbH in SAP and start invoice process" ║
║ ║
║ Planned actions: ║
║ ║
║ ┌────┬─────────────────────┬─────────────────────────────────┐ ║
║ │ # │ Action │ Details │ ║
║ ├────┼─────────────────────┼─────────────────────────────────┤ ║
║ │ 1 │ sap.createCustomer │ Name: Müller GmbH │ ║
║ │ │ │ Type: Customer │ ║
║ │ │ │ Country: Germany │ ║
║ ├────┼─────────────────────┼─────────────────────────────────┤ ║
║ │ 2 │ dynamixs.start │ Process: Invoice │ ║
║ │ │ Process │ Link to: Customer from Step 1 │ ║
║ └────┴─────────────────────┴─────────────────────────────────┘ ║
║ ║
║ Confidence: 94% ║
║ ║
║ ┌──────────┐ ┌──────────┐ ┌──────────┐ ║
║ │ Approve │ │ Reject │ │ Modify │ ║
║ └──────────┘ └──────────┘ └──────────┘ ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
The user has three options:
Approve – The plan is correct. Proceed with execution.
Reject – The plan is wrong or unwanted. Cancel the process. The user can optionally provide a reason for rejection. Modify – The plan is partially correct but needs adjustment. The user can edit parameters, remove actions, or add comments. The modified plan is saved and can be approved or sent back to the AI for revision.
Stage 3: Execution
Upon approval, the process moves to the execution stage. A script task iterates through the planned actions and executes them one by one.
For each action:
- The process identifies whether this is an internal tool or an external MCP tool
- Internal tools are executed via direct service calls
- External tools are executed via the MCP Client
- The result is captured and stored in the process data
- Success or failure determines the next step
If an action fails, the process does not automatically abort. Instead, it moves to an error handling state where the user can decide: Retry the failed action, skip it and continue, or abort the entire execution. This human-in-the-loop error handling prevents cascading failures.
Stage 4: Completion
After all actions complete (or the user aborts), the process moves to its final state. A summary is generated:
- Total actions attempted
- Successful actions with their results
- Failed actions with error details
- Overall execution time
The user receives a notification. The process remains in the archive as a permanent record.
BPMN Model Structure
┌─────────┐ ┌─────────────┐ ┌──────────────────────────────────────┐
│ Start │────►│ Review │────►│ Approved? │
└─────────┘ │ (Human │ └───────────────┬──────────────────────┘
│ Task) │ │
└─────────────┘ ┌─────────┼─────────┐
│ │ │
▼ │ ▼
┌──────────┐ │ ┌───────────┐
│ Execute │ │ │ Rejected │
│ Actions │ │ │ (End) │
│ (Script) │ │ └───────────┘
└────┬─────┘ │
│ │
▼ │
┌──────────────┐ │
│ Success? │ │
└───────┬──────┘ │
┌─────┴─────┐ │
│ │ │
▼ ▼ ▼
┌───────────┐ ┌─────────────┐
│ Completed │ │ Handle Error│
│ (End) │ │ (Human │
└───────────┘ │ Task) │
└──────┬──────┘
│
┌──────┴──────┐
│ │
▼ ▼
[Retry] [Abort]
│ │
└──────┬──────┘
│
▼
(back to execution or end)
Customization
This standard process is a starting point – not a limitation.
Organizations can clone and extend this process to match their specific requirements. A financial services company might add a second approval step for actions exceeding a certain value. A pharmaceutical company might require digital signatures for compliance. A multinational might route approvals to different teams based on the affected systems.
Some examples of customization:
| Requirement | Customization |
|---|---|
| Four-eyes principle | Add a second review task assigned to a different role |
| Value-based escalation | Add a gateway that routes high-value actions to management |
| Time-sensitive actions | Add timer events that escalate if review takes too long |
| Audit requirements | Add intermediate events that log to external compliance systems |
| Partial approval | Split the plan and allow approving some actions while rejecting others |
The process can also integrate with the existing BPMN-embedded prompts. After an action executes, a subsequent step could call the LLM to verify the result or generate a follow-up action. The two AI integration approaches – Orchestrator-initiated and BPMN-embedded – can work together in a single process.
This is the power of building AI control on top of a real process engine. We are not inventing a new paradigm. We are extending a proven one.