Overview

OpenAI Widgets - A secure, scalable module that brings advanced OpenAI capabilities directly into your Mendix applications. This module features a built-in proxy server for enhanced security and includes powerful widgets for AI integration.

Why This Module?

This module solves critical security vulnerabilities found in standalone widget implementations by moving API key management server-side and implementing a secure proxy architecture.

Key Security Features:

- Server-side API key management - No client-side exposure of sensitive credentials 

- Built-in proxy server - Secure communication layer mounted to Mendix runtime 

- Authentication-based access control - Only authorized users can access AI features

What's Included:

- JA_StartProxy Java Action - Secure proxy server initialization 

- Chat-Stream Widget - Advanced OpenAI chat interface with real-time streaming

- Image Generation Widget - AI-powered image creation with streaming preview

- Document Processor Widget - Extract structured data from documents and images

- JA_AgentRouter Java Action - Intelligent message routing utility

Chat-Stream Widget Highlights:

✅ Dual API Support - Chat Completions API or Responses API 

✅ Real-time Streaming - Character-by-character responses with SSE 

✅ Flexible Configuration - Custom JSON request bodies for advanced parameters 

✅ Complete Chat Interface - Ready-to-use UI with message history 

✅ Developer-Friendly - Simple Studio Pro configuration

Image Generation Widget Highlights:

✅ Streaming Preview - Real-time progressive image display during generation 

✅ Extensive Prompts - Support for up to 32,000 character descriptions 

✅ Multiple Formats - PNG, JPEG, and WebP output options 

✅ Flexible Display - Responsive or fixed-size image rendering 

✅ Background Options - Auto, transparent, or opaque backgrounds 

✅ Download Support - Direct image download capability for users

Document Processor Widget Highlights:

✅ Multi-Format Support - Process PNG, JPEG, WebP images and TXT files

✅ Structured Data Extraction - Convert documents to JSON using custom schemas

✅ Drag & Drop Interface - Intuitive file upload with format validation

✅ Real-time Processing Status - Visual feedback during document analysis

✅ Debug Mode - Built-in logging for troubleshooting and development

 JA_AgentRouter Utility Highlights:

✅ Intelligent Classification - AI-powered analysis and routing of text input

✅ User-Defined Routes - Create custom routes using the Route entity with your own names and descriptions

Perfect For:

- Building conversational AI interfaces in Mendix apps 

- Creating intelligent assistants with streaming responses 

- Implementing custom AI workflows requiring advanced OpenAI parameters 

- Generating AI images with detailed prompts and real-time preview 

- Creating visual content generation features in business applications

- Extracting structured data from documents and images 

- Building automated document processing workflows

- Routing messages to appropriate handlers based on content 

- Building intelligent workflows with automated text classification

Documentation

Typical usage scenario

This module enables Mendix developers to easily implement OpenAI's AI capabilities within their apps in a scalable and secure way. Build AI-powered features using OpenAI's advanced large language models, vision capabilities, and image generation models with enterprise-grade security through a server-side proxy architecture that eliminates client-side API key exposure. Create conversational interfaces, intelligent assistants, visual content generation features, document processing workflows, and intelligent routing systems that leverage the power of OpenAI's APIs.

Features and limitations

Module Features: 

• Secure server-side API key management through proxy server 
• Support for multiple OpenAI API endpoints 
• Extensible architecture for additional widgets

Current Widgets: 

• Chat-Stream Widget: Real-time streaming chat interface with dual API support (Chat Completions/Responses), flexible JSON configuration, debug mode, and complete UI
• Image Generation Widget: AI-powered image creation with streaming preview, support for 32K character prompts, multiple output formats (PNG/JPEG/WebP), responsive display options, and direct download capability
• Document Processor Widget: Extract structured data from documents and images (PNG/JPEG/WebP/TXT), custom JSON schema configuration, drag-and-drop interface, processing status feedback

Utility Actions:

• JA_AgentRouter: Intelligent text classification and routing using AI analysis, user-defined routes via Route entity, seamless proxy integration, and optional debug logging (logRequest)

Module Limitations: 

• Anonymous users cannot access the proxy server when security is enabled, protecting your OpenAI API from unauthorized use and unexpected charges

Dependencies

• Mendix Studio Pro 10.x or higher 
• Active OpenAI API account with valid API key 
• Internet connectivity for API communication 

Installation

1. Import the OpenAI_Widgets.mpk module into your Mendix project 
2. Navigate to your project's After Startup (ASU) microflow  
3. Add the JA_StartProxy Java action to the ASU microflow 
4. Configure the Java action with your OpenAI API key as a parameter 
5. Save and deploy your application to test the proxy initialization 
6. Verify successful initialization by checking the application logs

Configuration

Module Setup (Required for all widgets): 

In your After Startup microflow, configure JA_StartProxy with:   

• API Key (String): Your valid OpenAI API key

Chat-Stream Widget

1. Find "OpenAI Chat" in the Studio Pro widget toolbox 
2. Drag the widget onto your page 
3. Configure properties:   
   • API Type: Select "Chat Completions" or "Responses"   
   • Request Configuration: JSON string (e.g., {"model": "gpt-4",   "stream": true})   
   • System Prompt: Define AI behavior   
   • Max Messages: History limit (default: 50)   
   • Min/Max Height: Widget dimensions   
   • Debug Mode: Enable logging and display proxy server connection status

Example request configuration:

'{  "model": "o4-mini",  "reasoning": {    "effort": "high"  }}' 

Image Generation Widget

1. Find "OpenAI Image Generation" in the Studio Pro widget toolbox 
2. Drag the widget onto your page
3. Configure properties:
   • Background Type: Auto, Transparent, or Opaque 
   • Output Format: PNG, JPEG, or WebP 
   • Result Attribute: Mendix attribute to store generated image (base64) 
   • Display Result: Toggle result visibility 
   • Display Width/Height: Responsive or fixed dimensions 
   • Debug Mode: Enable to show proxy status and generation details

Document Processor Widget: 

1. Find "OpenAI Document Processor" in the Studio Pro widget toolbox 
2. Drag the widget onto your page 
3. Configure properties:   
   • Allowed Formats: Comma-separated extensions (e.g., png,jpg,txt). Supports: PNG, JPEG, WebP, TXT 
   • Max File Size: Maximum upload size in MB   
   • System Prompt: Instructions for document processing   
   • JSON Schema: Define structure for extracted data   
   • Result Attribute: Store extracted JSON data   
   • Actions: Configure start/complete/error callbacks   
   • Debug Mode: Enable proxy status and API logging

Example JSON schema configuration:

' {    "type": "object",    "properties": {      "title": {        "type": "string",        "description": "The main title or heading of the document",        "default": ""      },      "subtitle": {        "type": "string",        "description": "The secondary title or subheading",        "default": ""      },      "type": {        "type": "string",        "description": "The document or content type/category",        "default": ""      },      "productNumber(s)": {        "type": "array",        "items": {          "type": "string"        },        "description": "Reference numbers, IDs, or codes found in the document",        "default": []      }    },    "required": [      "title",      "subtitle",      "type",      "productNumber(s)"    ],    "additionalProperties": false  }'

JA_AgentRouter Action

1. Create Route entities with custom names and descriptions for your routing needs 
2. In your microflow, add the JA_AgentRouter Java action 
3. Configure parameters:
   • RouteList: List of Route entities defining your routing options 
   • StringToClassify: The text input to be analyzed and routed 
   • BaseURL: The proxy server URL (typically your app URL) 
   • LogRequest: Enable/disable cURL command logging for debugging 
4. The action returns the selected Route entity based on AI classification

For more information about OpenAI's API visit the docs: https://platform.openai.com/docs/