← Back to Docs Index

User Guide

Getting Started

The RACE Management Console is your comprehensive platform for industrial data monitoring and AI-powered analysis. This guide will walk you through all features and capabilities.

Table of Contents

1. Initial Setup
2. Dashboard Overview
3. Configuration
4. Asset Management
5. Rule Management
6. Event Monitoring
7. AI Cognition
8. Form Builder
9. Plant Model
10. Administration

Initial Setup

1. API Configuration

Before using the system, configure your CONNECT Data Services credentials:

1. Navigate to Configuration → API Configuration
2. Fill in your credentials:
3. Client ID: Your CONNECT client identifier
4. Client Secret: Your CONNECT client secret
5. Region: Select your data region (US, EU, etc.)
6. Tenant ID: Your CONNECT tenant identifier
7. Namespace ID: Your CONNECT namespace identifier
8. Click Save Configuration
9. Test the connection using Test Connection button

2. Asset Discovery

Once API configuration is complete:

1. Go to Configuration → Asset Discovery
2. Click Discover Assets to scan your CONNECT namespace
3. Review discovered assets and streams
4. Enable monitoring for relevant streams

Dashboard Overview

The main dashboard provides real-time system status:

Key Metrics

• Total Streams: Number of monitored data streams
• Active Streams: Currently functioning streams
• Error Streams: Streams with communication issues
• Active Rules: Number of deployed monitoring rules

Recent Events

View the latest 10 system events with: - Event name and description - Severity level (Info, Warning, Error, Critical) - Timestamp - Associated equipment

Event Wall

Real-time visualization of active events: - Template View: Events grouped by rule templates - Category View: Events grouped by category - Timeline View: Chronological event timeline

Configuration

The Configuration section has been redesigned with modern industrial connectivity in mind. All configuration options are organized into logical groups for better usability.

Connection Sources

Access various data integration protocols through the Connection Sources menu:

Connect Data Source (AVEVA CONNECT)

Purpose: Connect to AVEVA CONNECT Data Services for real-time industrial data

Steps: 1. Navigate to Configuration → Connection Sources → Connect Data Source 2. Obtain credentials from your CONNECT administrator 3. Fill in your credentials: - Client ID: Your CONNECT client identifier - Client Secret: Your CONNECT client secret
- Region: Select your data region (US, EU, AP) - Tenant ID: Your CONNECT tenant identifier - Namespace ID: Your CONNECT namespace identifier 4. Click Save Configuration 5. Test the connection using Test Connection button

Future Connection Types

The following connection types are planned for future releases:

• Azure IoT Hub: Enterprise cloud IoT platform integration
• OPC UA Server: Industrial automation standard protocol
• MQTT Broker: Lightweight IoT messaging protocol
• Modbus TCP: Industrial communication protocol
• REST API: HTTP-based web service integration

Each connection type will provide specialized configuration interfaces tailored to the specific protocol requirements. 3. Test connection before proceeding 4. Monitor connection status in the dashboard

Asset Discovery

Purpose: Automatically discover available data streams

Features: - Bulk asset discovery from CONNECT - Stream metadata extraction - Automatic monitoring configuration - Asset status tracking

Best Practices: - Run discovery periodically to detect new assets - Review stream metadata for appropriate monitoring - Disable monitoring for non-critical streams

Asset Management

Monitored Assets

View and manage your monitored industrial assets:

1. Navigate to Configuration → Monitored Assets
2. Review asset list with status indicators
3. Enable/disable monitoring per asset
4. View associated data streams

Stream Management

Each asset contains multiple data streams: - Stream Name: CONNECT stream identifier - Description: Human-readable description - Status: Active/Inactive monitoring status - Last Value: Most recent data point - Last Updated: Timestamp of last update

Rule Management

The Rule Management system follows a hierarchical structure: Packages → Templates → Rules → Instances

Packages

Purpose: Organize rule templates by functional area

Creating Packages: 1. Go to Rules → Packages 2. Click Add Package 3. Enter name and description 4. Save package

Examples: - Manufacturing Operations - Equipment Health - Quality Control - Safety Monitoring

Rule Templates

Purpose: Create reusable rule definitions for similar equipment

Template Components: - Name: Descriptive template name - Category: Functional category (utilization, health, production) - Color: Visual identifier color - Rules: Collection of monitoring rules - Placeholders: Variables for equipment-specific customization

Creating Templates: 1. Select a package 2. Click Add Template 3. Configure template properties 4. Add rules to the template 5. Define placeholders for reusability

Rules

Purpose: Define specific monitoring conditions and actions

Rule Components: - Rule ID: Unique identifier - Name: Human-readable name - Description: Detailed description - Logic: AND/OR logical operators - Conditions: Stream value conditions - Actions: Response actions (events, notifications) - Priority: Execution priority - Stop Processing: Halt further rule evaluation

Condition Types: - Equals: Exact value match - Greater Than: Numeric comparison - Less Than: Numeric comparison - Between: Range validation - Contains: Text pattern matching - Changed: Value change detection

Creating Rules: 1. Within a template, click Add Rule 2. Configure rule properties 3. Define conditions with operators 4. Set up actions and responses 5. Test rule logic

Template Instances

Purpose: Deploy templates to specific equipment with customized settings

Instance Components: - Instance Name: Unique instance identifier - Plant Node: Associated plant equipment - Placeholder Mappings: Equipment-specific stream assignments - Deployment Status: Active/Inactive status

Deploying Instances: 1. Select a template 2. Click Deploy Instance 3. Choose target plant node 4. Map placeholders to actual streams 5. Activate instance

Placeholder System: Templates use <NAME:TYPE> syntax for flexibility: - <EQUIPMENT>: Equipment identifier - <LINE>: Production line identifier - <ZONE>: Plant zone identifier

Example: <EQUIPMENT>.Temperature.PV becomes Roaster022.Temperature.PV

Event Monitoring

Event Wall

Real-time visualization of system events:

Layout Modes: - Template: Events grouped by rule template - Category: Events grouped by functional category - Timeline: Chronological event display

Time Filters: - Last 1 hour - Last 24 hours - Last 7 days - Custom range

Event Information: - Event name and description - Severity level with color coding - Start/end timestamps - Duration (for completed events) - Associated equipment and template - Enrichment data (production IDs, values, etc.)

Active Events

Monitor currently active events:

1. Navigate to Events → Active Events
2. View real-time event list
3. Filter by severity or category
4. Click events for detailed information
5. Track event duration and status

Event History

Review historical event data:

1. Go to Events → Event History
2. Use pagination to browse events
3. Apply filters for specific analysis
4. Export data for reporting

AI Cognition

The Cognition Engine provides AI-powered autonomous investigation of MES operations.

AI Providers

Purpose: Configure AI services for autonomous analysis

Supported Providers: - OpenAI: GPT-4, GPT-4-turbo with function calling - Anthropic: Claude Sonnet models - Google: Gemini Pro models - Azure OpenAI: Enterprise integration

Provider Configuration: 1. Navigate to Cognition → AI Providers 2. Click Add Provider 3. Select provider type 4. Configure model and settings 5. Set system instructions 6. Test provider functionality

Assistant Types

Purpose: Define AI behavior patterns for different investigation types

Built-in Types: - Investigation: Technical problem analysis - Analysis: Data pattern analysis - Report: Comprehensive reporting - Maintenance: Equipment maintenance guidance

Creating Assistant Types: 1. Go to Configuration → Assistant Types 2. Click Add Assistant Type (requires admin password) 3. Define behavior instructions 4. Set specialized capabilities

Chat Interface

Purpose: Interactive conversation with AI assistants

Features: - Real-time conversation - Context-aware responses - Function calling for data retrieval - Conversation history - Multi-provider support

Using Chat: 1. Select AI provider from Cognition menu 2. Choose context type (Events, Rules, Assets, etc.) 3. Set time filter for context data 4. Type your question or analysis request 5. Review AI response with data insights

Function Calling

Purpose: Autonomous data retrieval by AI assistants

Context Types: - Events: Current and historical event data - Rules: Rule configurations and status - Assets: Equipment and stream information - Streams: Real-time data values - Plant Model: Facility structure

Capabilities: - Automatic context selection - Real-time data queries - Historical trend analysis - Cross-system data correlation

Assistant Interface

Advanced Features: - View Context Data: Inspect available system data - Conversation Logs: Review interaction history - Function Call Logs: Monitor autonomous data retrieval - API Usage: Track provider usage and costs - Raw Logs: Technical debugging information

Analysis Tools: - Copy context data for external analysis - Export conversation logs - Clear conversation history - Refresh data sources

Form Builder

The Dynamic Form Builder is an enterprise-grade AI-powered system for creating and managing dynamic forms with advanced version control and MES workflow integration.

Dashboard Overview

Access the Form Builder through Configuration → Form Builder.

Key Statistics Dashboard: - Total Forms: Number of forms in the system - Published Forms: Currently active forms - Draft Forms: Forms in development - AI Providers: Available AI services for form generation

Creating Forms with AI

AI-Powered Form Generation: 1. Click Create New Form 2. Select AI provider (OpenAI, Anthropic, Gemini) 3. Choose AI model for form generation 4. Start conversational form creation: - Describe your form requirements in natural language - AI suggests form structure and widgets - Refine through conversation - AI generates complete JSON form definition

Supported Widget Types: - Input Fields: text, number, email, password - Selection: dropdown, radio buttons, checkboxes - Advanced: date pickers, switches, buttons - Layout: cards, grids for complex arrangements - Interactive: buttons with ActionTemplate integration

Version Management System

4-Digit Versioning (major.minor.patch.build): - Major: Breaking changes or complete redesigns - Minor: New features or significant enhancements
- Patch: Bug fixes and minor improvements - Build: Automatic increments for each save

Step-by-Step Version Management:

1. Using Version Dropdown:
2. Located in the form editing interface next to version display
3. Click dropdown to see all previous versions for the form
4. Select any version to automatically reload page with that version
5. Grid layout and form content load from database for selected version

6. localStorage automatically cleared to ensure correct version data

7. Build Increment Control:

8. Checkbox labeled "Auto-increment build number" (checked by default)
9. Checked: Build number increments automatically when saving (1.0.0.0 → 1.0.0.1)
10. Unchecked: Build number stays the same, useful for saving without version change

11. Can be toggled before each save for granular control

12. Independent Status Management:

13. Each version (1.0.0.1, 1.0.0.2, etc.) has its own Draft/Published status
14. Status update button allows changing status without full form reload
15. Draft versions: Available for editing and testing

16. Published versions: Available in runtime for end users

17. Version-Specific Grid Layouts:

18. Each version maintains completely independent grid layout configuration
19. Drag & drop changes save to database with version-specific key
20. Version switching clears localStorage to force loading correct layout from database
21. Grid persistence ensures exact reproduction of each version's design

Form Editing Interface

Configuration Panel: - Form ID: Unique identifier - Version Display: Current version with increment controls - Version History: Dropdown to browse previous versions - Status Controls: Draft/Published status with update button - Build Control: Optional auto-increment on save

Grid Layout System: - Drag & Drop: Position widgets on responsive grid - Version-Specific: Each version maintains independent layout - Persistent Storage: Layouts saved to database per version - Grid Controls: Merge cells, resize, reposition widgets

Advanced Features

ActionTemplate Integration: - Connect form buttons to RACE ActionTemplates - Automatic parameter mapping from form fields - Integration with MES workflow automation - Real-time data integration capabilities

Status Management: - Independent Versioning: Each version has separate status - Update Button: Change status without full form reload - Publishing Control: Manage form lifecycle independently

URL Parameters: - Direct version access: ?ver=3.1.2.1&status=draft - Status filtering: ?status=draft or ?status=published - Combined parameters: ?ver=2.1.0.5&status=published - Deep linking to specific form versions

Runtime System

Unified Runtime: - Single runtime endpoint: /form-builder/runtime/<form_id>?ver=X.X.X.X&status=draft - Version-specific parameter support with exact version targeting - Real-time widget rendering with version-specific grid layouts - Data validation and submission with form-specific rules - ActionTemplate execution integration for workflow automation

Grid Layout Runtime: - Faithful reproduction of version-specific designer layouts - Automatic loading of grid_layout from database for selected version - Responsive design with mobile support and CSS Grid positioning - Widget interaction, validation, and real-time data submission - Version isolation ensures different versions display correctly

Permissions and Security

RBAC Integration: - Requires configuration.form_builder permission - Form-level access control - Version-specific permissions - Audit logging for all operations

Security Features: - Input validation and sanitization - CSRF protection on state-changing operations - Secure ActionTemplate integration - Comprehensive error handling

Plant Model

Hierarchy Management

Purpose: Define facility structure for equipment organization

ISA-95 Levels: - Enterprise: Top-level organization - Site: Physical locations - Area: Functional areas - Production Line: Manufacturing lines - Work Unit: Individual equipment

Managing Plant Model: 1. Navigate to Configuration → Plant Model 2. View hierarchical structure 3. Add new nodes with appropriate levels 4. Associate template instances with equipment 5. Track instance deployment status

Equipment Association

Purpose: Link template instances to specific equipment

Benefits: - Organized rule deployment - Equipment-specific monitoring - Structured reporting - Maintenance planning

Administration

System Settings

User Preferences: - Language settings (UI in English, user communication in Italian) - Theme preferences (dark theme default) - Notification settings - Display preferences

Performance Settings: - Monitoring intervals - Data retention periods - Cache configurations - API rate limits

Security

Access Control: - Session management - API key protection - Admin password protection - Secure credential storage

Data Protection: - Encrypted communications - Secure database connections - CSRF protection - Input validation

Maintenance

Regular Tasks: - Database cleanup - Log rotation - Cache clearing - Performance monitoring

Health Checks: - API connectivity - Database status - Background job status - AI provider availability

Troubleshooting

Common Issues

Connection Problems: - Verify API credentials - Check network connectivity - Confirm CONNECT service status - Review firewall settings

Rule Deployment Issues: - Validate placeholder mappings - Check stream availability - Verify template configuration - Review error logs

AI Provider Issues: - Confirm API key validity - Check provider service status - Review usage limits - Test with simple queries

Support Resources

Documentation: - API Reference for technical details - Architecture documentation - Configuration examples - Troubleshooting guides

Monitoring: - Application logs - Performance metrics - Error tracking - Health dashboards

Best Practices

Rule Design

• Use descriptive names and descriptions
• Implement proper priority ordering
• Test rules before production deployment
• Document rule logic and purpose

Template Organization

• Group related rules in packages
• Use consistent naming conventions
• Implement proper placeholder design
• Version control template changes

AI Usage

• Use specific, context-aware queries
• Review function calling results
• Monitor API usage and costs
• Implement proper conversation management

Performance

• Monitor system resource usage
• Optimize rule conditions
• Clean up old data regularly
• Balance monitoring frequency with performance

Monitoring Cleanup (Super Admin)

Path: Configuration → Database Management → Monitoring Cleanup

Purpose: Inspect and maintain the monitoring_event table. Super Admin permission (admin.full_access) required.

Features: - Current stats: total events, oldest/newest timestamp - Delta over max total (how many rows exceed global cap) - Top streams by event count with per-stream delta over cap - Manual cleanup button (runs retention + caps cleanup in batches)

Configuration keys (see Configuration Reference → Monitoring Event Retention & Cleanup): - monitoring.event_cleanup_days - monitoring.max_total_events - monitoring.max_events_per_stream - monitoring.batch_cleanup_size

Notes: - Cleanup runs hourly automatically; manual run is available for on-demand maintenance - Deletions are batched to minimize lock contention