CMMS SCADA Excel Data Processor

A professional-grade VBA automation tool for processing and analyzing data from Maintenance Management Systems (CMMS) with SCADA integration. Automate data downloads, filter maintenance orders, assign tasks to teams, and correlate SCADA alarms—all from Excel.

🎯 What Does This Tool Do?

This tool automates your daily CMMS workflow:

1. Downloads data from your CMMS automatically using Chrome browser automation
2. Processes and filters maintenance orders, issues, and SCADA alarm data in Excel
3. Assigns tasks to team members using customizable algorithms
4. Creates planning reports by correlating maintenance needs with SCADA alarm history
5. Saves you hours of manual copying, filtering, and report generation

🚀 Key Features

• 🔄 Automated Data Downloads: Uses Selenium to log in and download data from your CMMS
• 🔐 Secure Credentials: PowerShell secure prompts—no passwords stored in code
• 📊 Advanced Excel Processing: Powerful filtering, sorting, and team assignment algorithms
• 👥 Team Management: Automatically distribute tasks based on equipment areas and workload
• ⚡ SCADA Integration: Correlate CMMS issues with SCADA alarm history for planning
• 🎨 User-Friendly Forms: Excel dialogs guide you through filtering and task selection
• 📝 Comprehensive Logging: All operations logged to %LOCALAPPDATA%\CMMSLogs\
• ⚙️ Fully Configurable: One configuration file controls all system-specific settings

📁 Project Structure

CMMS-SCADA-Excel-DataProcessor/
├── .github/                          # GitHub community health files
│   ├── CODEOWNERS                    # Code ownership and PR review assignments
│   ├── CONTRIBUTING.md               # Contribution guidelines
│   └── ISSUE_TEMPLATE/               # Issue & bug report templates
│       ├── bug_report.yml            # Bug report form
│       ├── config.yml                # Issue template configuration
│       ├── feature_request.yml       # Feature request form
│       └── general_issue.yml         # General questions/issues form
├── .vscode/
│   └── extensions.json               # Recommended VS Code extensions
├── src/
│   ├── modules/                      # Core VBA modules (7 files)
│   │   ├── MaintenanceManager.bas    # Main orchestration & task workflows
│   │   ├── WebAutomation.bas         # Selenium browser automation
│   │   ├── ExcelUtilities.bas        # Excel data processing & formatting
│   │   ├── DataFilters.bas           # Filtering & team assignment algorithms
│   │   ├── ConfigManager.bas         # Configuration loader & validator
│   │   ├── AppServices.bas           # Authentication & credential management
│   │   └── Logger.bas                # Error logging & debugging
│   └── config/
│       └── Config.bas                # ⚠️ YOUR PRIVATE CONFIG (create from template)
├── Forms/                            # VBA UserForms (14 .frm + .frx files)
│   ├── formTasks.frm                 # Main task selection dialog
│   ├── formMOs.frm                   # Maintenance Orders filtering
│   ├── formIssues.frm                # Issues/tickets filtering
│   ├── formPlanning.frm              # Planning mode selection
│   └── ...                           # Additional specialized forms
├── templates/
│   └── Config_Template.bas           # 📋 CONFIGURATION TEMPLATE (start here!)
├── tools/                            # Setup & maintenance utilities
│   ├── LaunchCMMS-Silent.vbs         # 🚀 Desktop launcher (shortcut points here)
│   ├── LaunchCMMS.vbs                # Main launcher logic
│   ├── Create-DesktopShortcut.ps1    # Creates desktop shortcut
│   ├── setup-checker.ps1             # Verify Selenium installation
│   ├── config-validator.vbs          # Validate your Config.bas
│   └── Update-ChromeDriver.ps1       # Auto-update ChromeDriver
├── .gitignore                        # Protects Config.bas from commits
├── LICENSE                           # MIT License
├── README.md                         # This file
└── TODO.md                           # Development roadmap

🛠️ Quick Start Guide

Step 1: Install Prerequisites

Before you begin, install these required components:

1.1 Microsoft Excel

• Required: Excel 2016 or later (32-bit or 64-bit)
• Check your version: Open Excel → File → Account → About Excel

1.2 Google Chrome Browser

• Download from: https://www.google.com/chrome/
• Note: The tool uses Chrome for web automation

1.3 Selenium Basic (COM Library)

• Download: Selenium Basic Releases
• Install: Run the installer (accepts all defaults)
• Default location: C:\Users\[YourUser]\AppData\Local\SeleniumBasic\
• Important: After installation, verify the Selenium Type Library appears in Excel VBA References

1.4 ChromeDriver (Automated via tool)

• Good news: The tool includes Update-ChromeDriver.ps1 which automatically downloads the correct version
• Manual option: Download from Chrome for Testing
• Must match: ChromeDriver version must match your Chrome browser version
• Location: Place in C:\Users\[YourUser]\AppData\Local\SeleniumBasic\

---

Step 2: Download the Project

Choose one option:

Option A: Clone with Git (recommended)

git clone https://github.com/KirilMT/CMMS-SCADA-Excel-DataProcessor.git
cd CMMS-SCADA-Excel-DataProcessor

Option B: Download ZIP

1. Click the green "Code" button on GitHub
2. Select "Download ZIP"
3. Extract to a folder (e.g., C:\Projects\CMMS-Automation\)

---

Step 3: Configure for Your CMMS System

This is the most important step—customize the tool for your specific CMMS.

3.1 Create Your Configuration File

1. Navigate to the templates/ folder
2. Copy Config_Template.bas
3. Paste into src/config/ folder
4. Rename to Config.bas

# PowerShell commands (or do manually):
Copy-Item templates\Config_Template.bas src\config\Config.bas

3.2 Edit Your Configuration

Open src\config\Config.bas in a text editor (Notepad++, VS Code, or even Notepad).

Required Changes (minimum to get started):

' 1. SYSTEM IDENTITY
Public Function GetSystemName() As String
    GetSystemName = "Your Company CMMS"  ' Change this
End Function

Public Function GetBaseUrl() As String
    GetBaseUrl = "https://cmms.yourcompany.com"  ' Your CMMS URL
End Function

' 2. AUTHENTICATION
Public Function GetUsername() As String
    GetUsername = "your.email@yourcompany.com"  ' Your login username
End Function

Public Function GetUsernameForFiltering() As String
    GetUsernameForFiltering = "yourname"  ' Just your name (for Excel filters)
End Function

' 3. FILE LOCATIONS
Public Function GetDownloadDirectory() As String
    GetDownloadDirectory = "C:\Users\YourUser\Downloads"  ' Your downloads folder
End Function

' 4. ASSET PREFIX (for SCADA integration)
Public Function GetAssetPrefix() As String
    GetAssetPrefix = "FACILITY_LINE1"  ' Your facility/line code
End Function

Advanced Configuration (optional, can configure later):

• XPath Selectors: Web element locators for your specific CMMS interface
• Team Members: Define your maintenance team and equipment areas
• Filter Criteria: Customize filtering rules for your workflow

💡 Tip: The template file has detailed comments for each function. Read them carefully!

---

Step 4: Set Up Excel Workbook

4.1 Create a New Workbook

1. Open Microsoft Excel
2. Create a new Excel Macro-Enabled Workbook (.xlsm)
3. Save it with a descriptive name (e.g., CMMS_Automation.xlsm)
4. Recommended location: Same folder as the project

4.2 Open VBA Editor

• Press Alt + F11 (or Tools → Macro → Visual Basic Editor)

4.3 Enable Selenium Type Library

1. In VBA Editor, go to Tools → References
2. Scroll down and check ✅ Selenium Type Library
3. Click OK

Troubleshooting: If you don't see "Selenium Type Library":

• Selenium Basic may not be installed correctly
• Run tools\setup-checker.ps1 to diagnose the issue

4.4 Import All Modules

Import the 7 core modules:

1. In VBA Editor: File → Import File (or drag & drop)
2. Navigate to src\modules\
3. Select ALL 7 .bas files:
   • MaintenanceManager.bas
   • WebAutomation.bas
   • ExcelUtilities.bas
   • DataFilters.bas
   • ConfigManager.bas
   • AppServices.bas
   • Logger.bas
4. Click Open

Import your configuration:

5. File → Import File
6. Navigate to src\config\
7. Select Config.bas (the one you customized)
8. Click Open

Import the user forms:

9. File → Import File
10. Navigate to Forms\
11. Select ALL .frm files (14 files—each has a matching .frx file that imports automatically):
    • formTasks.frm
    • formMOs.frm
    • formMOsCompleted.frm
    • formIssues.frm
    • formIssuesTeam.frm
    • formIssuesTeam2.frm
    • formIssuesTeamTask.frm
    • formPlanning.frm
12. Click Open

Verify the import:

In the VBA Project Explorer (left panel), you should see:

• Modules folder with 8 modules (7 core + Config)
• Forms folder with 8 forms

---

Step 5: Verify Installation

5.1 Run the Setup Checker

Before using the tool, verify everything is installed correctly:

Windows PowerShell:

cd tools
.\setup-checker.ps1

Command Prompt:

cd tools
setup-checker.bat

This will check:

• ✅ Selenium Basic installation
• ✅ ChromeDriver presence and version
• ✅ Chrome browser installation
• ✅ Network connectivity

5.2 Validate Your Configuration

Run the configuration validator to check for errors:

cd tools
cscript config-validator.vbs

This verifies:

• ✅ All required functions exist
• ✅ URLs are properly formatted
• ✅ Team member configuration is valid
• ✅ XPath selectors are defined

---

Step 6: First Run

6.1 Test the Tool

1. In VBA Editor, double-click MaintenanceManager module
2. Press F5 or click Run → Run Sub/UserForm
3. Select RunMaintenanceTasks from the list
4. Click Run

6.2 What Should Happen

1. Chrome opens automatically and navigates to your CMMS
2. Credential prompt appears (PowerShell secure window)
   • Username is pre-filled from Config.bas
   • Enter your password
   • ✅ Credentials are cached for multi-download tasks
3. Task selection dialog appears (formTasks)
4. Choose your task:
   • MOs = Download Maintenance Orders
   • Issues = Download Issues/Tickets
   • Planning = Multi-download planning mode
5. Data is downloaded and opened in Excel
6. Filtering forms appear based on your selection

6.3 Troubleshooting First Run

Issue	Solution
"ChromeDriver version mismatch"	Run tools\Update-ChromeDriver.ps1
"Selenium Type Library missing"	Re-install Selenium Basic, restart Excel
"Element not found" timeout	XPath selectors in Config.bas don't match your CMMS—needs customization
Password prompt doesn't appear	Check PowerShell execution policy: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
Chrome doesn't open	Verify Selenium Basic installation with tools\setup-checker.ps1

---

Step 7: Create Desktop Launcher (Recommended)

7.1 Automatic Setup

The easiest way to launch the tool is via a desktop shortcut:

1. Open PowerShell in the project directory
2. Run the shortcut creator:

   .\tools\Create-DesktopShortcut.ps1

3. A shortcut named "CMMS Tool" appears on your Desktop
4. Double-click to launch!

What happens:

• ✅ Excel opens invisibly (no window clutter)
• ✅ Only your task selection form appears
• ✅ No console windows
• ✅ Professional, clean experience

7.2 Manual Setup (Alternative)

If you prefer manual control:

1. Right-click tools\LaunchCMMS-Silent.vbs
2. Select "Send to" → "Desktop (create shortcut)"
3. Rename to "CMMS Tool"
4. Right-click shortcut → Properties → Change Icon (optional)

---

Step 8: Daily Usage Tips

8.1 Add to Quick Access Toolbar (Advanced)

If you prefer launching from within Excel:

1. Open Excel → Developer tab
2. Click Macros → Select RunMaintenanceTasks
3. Click Options → Assign shortcut (e.g., Ctrl+Shift+M)

8.2 Customize XPath Selectors (Advanced)

If web elements are not found, you need to update XPath selectors in Config.bas:

1. Open your CMMS in Chrome
2. Right-click an element → Inspect
3. In DevTools, right-click the HTML element → Copy → Copy XPath
4. Paste into the appropriate function in Config.bas → GetXpaths() array

Example:

Public Function GetXpaths() As Variant
    Dim xpaths(51) As String
    
    ' Login elements
    xpaths(1) = "//*[@id='username']"  ' Update with your XPath
    xpaths(2) = "//*[@id='password']"  ' Update with your XPath
    ' ... etc

8.3 Configure Team Members

Edit the GetTeam() function in Config.bas to define your team:

Public Function GetTeam() As Variant
    ' Columns: Name, AssetInclude, AssetExclude, SubgroupInclude, SubgroupExclude, Alarms Include, Exclude
    Dim team(1 To 5, 1 To 10) As Variant
    
    team(1, 1) = "John Doe"
    team(1, 2) = Array("LINE1_ST01", "LINE1_ST02")  ' Responsible areas
    ' ... configure for each team member
    
    GetTeam = team
End Function

---

✅ You're Ready!

Your CMMS automation tool is now installed and configured!

To launch:

• 🖱️ Desktop shortcut (recommended): Double-click "CMMS Tool" icon
• ⌨️ Excel macro (advanced): Press Ctrl+Shift+M or run RunMaintenanceTasks

What it does:

• Download and filter maintenance orders
• Assign issues to team members
• Create planning reports with SCADA data
• Process historical data for analysis

---

� How to Use

Basic Workflow

1. Launch the tool: Double-click desktop shortcut (or press macro shortcut)
2. Select task type: Choose from the main dialog
3. Filter your data: Use the filtering forms to refine results
4. Process in Excel: Data appears in a formatted, filterable worksheet

Task Types Explained

🔧 Maintenance Orders (MOs)

Downloads and filters maintenance work orders from your CMMS.

Available Filters:

• All - No filtering, shows everything
• ToDo MOs - New/Ready to Assign corrective/reactive work
• My MOs - Work orders assigned to you
• Completed MOs - Recently completed work (by shift or team)
• Weekend MOs - High priority work for weekend planning
• PM MOs - Preventive maintenance due soon
• RCA MOs - Root cause analysis tracking

Example Use Case:

Every morning, run "ToDo MOs" to see what new work needs to be assigned to your team.

🎫 Issues

Downloads and filters issues/tickets from your CMMS.

Available Filters:

• All - No filtering
• ToDo Issues - New/Pending high-priority issues
• My Issues - Issues assigned to you
• History Issues - Recently completed/closed issues
• Team Issues - Assign issues to team members automatically
• Correct New - New corrective issues for review

Example Use Case:

Run "Team Issues → All Members" to automatically distribute open issues across your team based on equipment areas and current workload.

📊 Planning Mode

Multi-download mode that combines three data sources:

1. Maintenance Orders - Open work orders
2. Issues - Open issues/tickets
3. SCADA Alarm History - Equipment faults and downtime

The tool correlates this data to help you:

• Identify equipment with recurring alarms
• Match alarms to existing work orders or issues
• Plan maintenance activities for upcoming shutdowns

Example Use Case:

Before a weekend shutdown, run Planning mode to see all high-alarm equipment, check if issues exist, and create work orders as needed.

Advanced Features

Team Assignment Algorithm

When using "Team Issues → All Members":

1. Tool filters issues by each team member's assigned equipment areas
2. Distributes work evenly based on current workload
3. Creates a summary sheet with all assignments
4. Sorts team members by total issue count (least busy first)

SCADA Asset Code Generation

In Planning mode, the tool automatically generates asset codes from SCADA alarm data:

• Extracts line, station, equipment, and device information
• Applies facility-specific naming conventions (configured in Config.bas)
• Creates standardized asset codes like: FACILITY_LINE1_ST001_CONV001_WC01

Credential Caching

For Planning mode (3 downloads):

• Enter credentials once
• Cached in memory for session
• Automatically cleared when task completes

For single downloads:

• Credentials prompted and cleared immediately after

---

🔧 Configuration Guide

What is Config.bas?

Config.bas is your private configuration file that tells the tool:

• Where your CMMS is located (URLs)
• How to log in (username, credential prompts)
• Where to find web elements (XPath selectors)
• Who your team members are
• What equipment areas they manage
• Where to save downloads

⚠️ IMPORTANT:

• This file contains company-specific information
• It is automatically ignored by Git (listed in .gitignore)
• Never commit this file to a public repository
• Always start from Config_Template.bas

Configuration Sections

1. System Identity & URLs

' Your CMMS system name (appears in dialogs)
Public Function GetSystemName() As String
    GetSystemName = "Your Company CMMS"
End Function

' Base URL of your CMMS
Public Function GetBaseUrl() As String
    GetBaseUrl = "https://cmms.yourcompany.com"
End Function

' Specific page URLs (usually base + path)
Public Function GetMaintenanceOrdersUrl() As String
    GetMaintenanceOrdersUrl = GetBaseUrl() & "/app/maintenance/orders"
End Function

2. Authentication

' Your login username
Public Function GetUsername() As String
    GetUsername = "your.email@company.com"
End Function

' Username for Excel filtering (just first/last name)
Public Function GetUsernameForFiltering() As String
    GetUsernameForFiltering = "yourname"
End Function

' Optional: Environment variable for password
Public Function GetPasswordEnvironmentVariable() As String
    GetPasswordEnvironmentVariable = "CMMS_PASSWORD"
End Function

Password is never stored in code. It's prompted via PowerShell secure dialog.

3. File Locations

' Where Chrome downloads files
Public Function GetDownloadDirectory() As String
    GetDownloadDirectory = "C:\Users\YourName\Downloads"
End Function

4. XPath Selectors (Advanced)

XPath selectors tell Selenium where to find elements on your CMMS web pages.

Public Function GetXpaths() As Variant
    Dim xpaths(51) As String
    
    ' Login page elements
    xpaths(1) = "//*[@id='username']"        ' Username field
    xpaths(2) = "//*[@id='password']"        ' Password field
    xpaths(3) = "//button[@type='submit']"   ' Login button
    
    ' Maintenance Orders page
    xpaths(10) = "//div[@class='first-mo']"  ' First MO (page loaded indicator)
    xpaths(15) = "//button[@title='Export']" ' Export button
    
    ' ... 52 total XPath selectors
    
    GetXpaths = xpaths
End Function

How to find XPaths:

1. Open your CMMS in Chrome
2. Press F12 to open DevTools
3. Click the "Select Element" tool (top-left corner)
4. Click the element you want
5. In DevTools, right-click the highlighted HTML → Copy → Copy XPath
6. Paste into Config.bas

5. Team Configuration

Define your maintenance team and their equipment responsibilities:

Public Function GetTeam() As Variant
    ' 10 columns: Name, AssetInclude, AssetExclude, SubgroupInclude, SubgroupExclude,
    '             AlarmInclude, AlarmExclude, IssuesCount, Tasks, NotOnsite
    Dim team(1 To 5, 1 To 10) As Variant
    
    ' Example: John manages Stations 1-3 on Line 1
    team(1, 1) = "John Doe"
    team(1, 2) = Array("LINE1_ST001", "LINE1_ST002", "LINE1_ST003")
    team(1, 3) = Array("")  ' No exclusions
    team(1, 4) = Array("Conveyors", "Robots")  ' Equipment types
    
    ' Example: Jane manages Stations 4-6
    team(2, 1) = "Jane Smith"
    team(2, 2) = Array("LINE1_ST004", "LINE1_ST005", "LINE1_ST006")
    ' ... etc
    
    GetTeam = team
End Function

6. Filter Criteria

Customize filtering rules:

' Which production lines to include in "ToDo" filter
Public Function GetToDoLineFilterInclude() As Variant
    GetToDoLineFilterInclude = Array("LINE1", "LINE2", "LINE3")
End Function

' Which areas to exclude
Public Function GetToDoLineFilterExclude() As Variant
    GetToDoLineFilterExclude = Array("Workshop", "Warehouse")
End Function

Updating Your Configuration

As your CMMS interface changes or your team structure evolves:

1. Open src\config\Config.bas in a text editor
2. Update the relevant function
3. Save the file
4. No need to re-import into Excel (changes take effect immediately)

---

� Security & Privacy

How Credentials Are Handled

1. Username: Stored in Config.bas (company email, not sensitive)
2. Password:
   • Never stored in any file
   • Prompted via PowerShell secure dialog (bullets, not visible)
   • Cached in memory only during multi-download sessions
   • Automatically cleared when task completes

Credential Caching Workflow

Single Download (MOs or Issues):
1. Prompt for password → 2. Download data → 3. Clear from memory immediately

Planning Mode (3 downloads):
1. Prompt for password → 2. Cache in memory → 3. Download MOs → 
4. Reuse cached password → 5. Download Issues → 6. Reuse cached password → 
7. Download SCADA → 8. Clear from memory

Optional: Environment Variable

For advanced users, you can set an environment variable to avoid password prompts:

PowerShell (persistent):

[System.Environment]::SetEnvironmentVariable('CMMS_PASSWORD', 'YourPassword', 'User')

Not recommended for shared computers!

Git Security

The .gitignore file automatically prevents committing:

• ✅ Config.bas (your private configuration)
• ✅ *.log files (may contain usernames)
• ✅ Downloaded data files
• ✅ Backup files

Before your first commit, verify:

git check-ignore src/config/Config.bas
# Should output: src/config/Config.bas

---

🔍 Logging & Debugging

Where Are Logs Stored?

All operations are logged to:

%LOCALAPPDATA%\CMMSLogs\YYYY-MM-DD_CMMS_automation.log

Example: C:\Users\YourName\AppData\Local\CMMSLogs\2025-10-08_CMMS_automation.log

Log Levels

• INFO: Normal operations (task started, file downloaded)
• WARNING: Non-critical issues (element not found but continuing)
• ERROR: Critical failures (login failed, file not found)
• DEBUG: Detailed technical information (XPath used, timing)

Viewing Logs

PowerShell:

# View today's log
Get-Content $env:LOCALAPPDATA\CMMSLogs\*$(Get-Date -Format 'yyyy-MM-dd')*.log

# View last 50 lines
Get-Content $env:LOCALAPPDATA\CMMSLogs\*$(Get-Date -Format 'yyyy-MM-dd')*.log -Tail 50

# Watch in real-time
Get-Content $env:LOCALAPPDATA\CMMSLogs\*$(Get-Date -Format 'yyyy-MM-dd')*.log -Wait

Common Error Messages

Error	Meaning	Solution
"Element not found: Username Input Field"	XPath selector doesn't match your CMMS	Update XPath in Config.bas
"ChromeDriver version mismatch"	ChromeDriver doesn't match Chrome browser	Run Update-ChromeDriver.ps1
"Timeout: Login failed"	Wrong credentials or MFA required	Check username/password, handle MFA manually
"File doesn't exist"	Download didn't complete	Check Chrome downloads, verify export worked

---

🧰 Utility Tools

The tools/ directory contains maintenance and validation scripts.

setup-checker.ps1 / .bat

Purpose: Verify all prerequisites are installed correctly

Run before first use:

cd tools
.\setup-checker.ps1

Checks:

• ✅ Selenium Basic installation and registration
• ✅ ChromeDriver presence and version compatibility
• ✅ Chrome browser installation
• ✅ Network connectivity to common sites
• ✅ PowerShell execution policy
• ✅ File system permissions

Output Example:

✅ Selenium Basic: Installed (v2.0.9.0)
✅ ChromeDriver: Found (v120.0.6099.109)
✅ Chrome Browser: Installed (v120.0.6099.109)
✅ Versions Match: Compatible
✅ Network: Connected

config-validator.vbs

Purpose: Validate your Config.bas before running

Usage:

cd tools
cscript config-validator.vbs

Validates:

• ✅ All required functions exist
• ✅ URLs are properly formatted (http/https)
• ✅ Download directory exists
• ✅ Team members are configured
• ✅ XPath selectors are defined (not empty)
• ✅ No placeholder values remain

Output Example:

Validating: src\config\Config.bas
✅ GetSystemName: OK
✅ GetBaseUrl: OK (https://cmms.company.com)
✅ GetUsername: OK
⚠️  Warning: GetDownloadDirectory path does not exist
✅ GetTeam: OK (5 members configured)

Result: Configuration Valid (1 warning)

Update-ChromeDriver.ps1 / .bat

Purpose: Automatically update ChromeDriver to match your Chrome version

Usage:

cd tools
.\Update-ChromeDriver.ps1

What it does:

1. Detects your installed Chrome browser version
2. Downloads matching ChromeDriver from official Google repository
3. Extracts to Selenium Basic directory
4. Backs up old driver (just in case)
5. Verifies new driver works

Run this when:

• Chrome updates automatically
• You see "ChromeDriver version mismatch" errors
• After installing Chrome for the first time

---

📂 Templates & Configuration

Config_Template.bas

Location: templates/Config_Template.bas

Purpose: Starting point for your private configuration

Contains:

• All required function definitions (30+ functions)
• Detailed inline comments explaining each setting
• Example values for every configuration option
• XPath selector placeholders with descriptions
• Sample team configuration structure

How to use:

1. Copy to src/config/Config.bas
2. Replace example values with your actual data
3. Save and import into Excel VBA

Never commit your customized Config.bas! It's in .gitignore for security.

---

🛠️ Troubleshooting

Installation Issues

"Selenium Type Library not found in References"

Cause: Selenium Basic not installed or not registered

Solution:

1. Download Selenium Basic (latest version)
2. Run installer as Administrator
3. Restart Excel completely
4. Try enabling the reference again
5. If still failing, run: regsvr32 "C:\Program Files\SeleniumBasic\Selenium.dll"

"ChromeDriver version mismatch"

Cause: ChromeDriver and Chrome browser versions don't match

Solution:

cd tools
.\Update-ChromeDriver.ps1

Or manually download matching version from Chrome for Testing.

"Import failed: File format is not valid"

Cause: Trying to import .frx files (these import automatically with .frm files)

Solution: Only import .frm files. The matching .frx files load automatically.

Runtime Issues

"Timeout: Element not found"

Cause: XPath selector doesn't match your CMMS interface

Solution:

1. Open your CMMS in Chrome
2. Press F12 (DevTools)
3. Click element selector tool (top-left)
4. Click the element causing timeout
5. In DevTools: Right-click HTML element → Copy → Copy XPath
6. Update the corresponding XPath in Config.bas → GetXpaths() function
7. Save Config.bas (no need to re-import)

"Password prompt doesn't appear"

Cause: PowerShell execution policy prevents running scripts

Solution:

# Check current policy
Get-ExecutionPolicy

# Set to allow scripts (run as Administrator)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

# Or bypass for this session only
powershell -ExecutionPolicy Bypass

"Chrome opens but doesn't navigate"

Cause: Base URL in Config.bas is incorrect

Solution:

1. Open src\config\Config.bas
2. Verify GetBaseUrl() returns correct CMMS URL
3. Test by pasting URL in Chrome manually

"File doesn't exist after download"

Cause: Download location mismatch or download didn't complete

Solution:

1. Check GetDownloadDirectory() in Config.bas matches your actual Chrome downloads
2. Open Chrome → Settings → Downloads → Check location
3. Update Config.bas if different
4. Verify CMMS export actually generates a file

"Multiple workbooks open" error

Cause: Previous run didn't close, or multiple Excel files match the pattern

Solution:

1. Close all Excel workbooks except your automation workbook
2. Delete any temporary downloaded files
3. Run the tool again

Performance Issues

"Tool is very slow"

Possible causes & solutions:

• Large datasets: Reduce date range in filters, or process in chunks
• Screen updating: Already optimized with Application.Wait
• Calculation mode: Consider disabling automatic calculations for very large datasets
• Network speed: CMMS downloads depend on your connection speed

"Excel becomes unresponsive"

Solution:

1. Don't interact with Excel while tool is running
2. For large datasets (>10,000 rows), consider filtering at CMMS level first
3. Close other applications to free memory

Configuration Issues

"Team assignment doesn't work correctly"

Cause: Team member configuration is incorrect

Solution:

1. Open Config.bas → GetTeam() function
2. Verify asset codes match your CMMS data exactly
3. Test with one team member first
4. Check logs in %LOCALAPPDATA%\CMMSLogs\ for filter details

"SCADA asset codes look wrong"

Cause: Asset code generation logic doesn't match your facility naming

Solution:

1. Review SCADASheetFormatting() in MaintenanceManager.bas
2. This function applies facility-specific patterns
3. May need customization for your naming conventions
4. Check generated codes against expected format

---

💡 Tips & Best Practices

Daily Workflow Tips

1. Morning routine: Run "ToDo MOs" to see new work
2. Team standup: Run "Team Issues → All Members" for distribution
3. Pre-shutdown: Run "Planning" mode to prepare weekend work
4. End of day: Run "Completed MOs → Shift" for reporting

Configuration Tips

1. Start simple: Configure basic URLs and auth first, test, then add advanced features
2. XPath fragility: Web interfaces change—review XPaths monthly
3. Team configuration: Start with 2-3 team members, expand once it works
4. Backup Config.bas: Keep a copy outside the project folder

Performance Tips

1. Filter at source: Use CMMS filters before download when possible
2. Date ranges: Don't download more than 30 days of data unless needed
3. Planning mode: Use sparingly (downloads 3 datasets)
4. Close other workbooks: Excel performs better with fewer files open

Security Tips

1. Never commit Config.bas: Always double-check before git push
2. Use environment variable: For automation/CI, not shared computers
3. Rotate passwords: Change CMMS password regularly
4. Review logs: Check logs for unusual activity

---

🤝 Contributing

Contributions are welcome! We'd love your help to make this project even better.

Please read our Contributing Guide for:

• 🐛 How to report bugs
• 💡 How to suggest features
• 🔧 How to submit code contributions
• 📝 Code standards and conventions
• 🧪 Testing guidelines

Quick links:

• Report a Bug
• Request a Feature
• Ask a Question
• Join Discussions

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

You are free to:

• ✅ Use commercially
• ✅ Modify for your needs
• ✅ Distribute
• ✅ Use privately

Under the condition that:

• ⚠️ You include the original copyright notice
• ⚠️ The software is provided "as-is" without warranty

---

🙏 Acknowledgments

• Selenium Basic by Florent Breheret - VBA COM wrapper for Selenium WebDriver
• Chrome for Testing by Google - Stable ChromeDriver builds
• VBA Community - For patterns and best practices

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: This README and inline code comments

---

Version: 1.0.0
Last Updated: October 8, 2025
Status: Production-Ready ✅
Tested With: Excel 2016-365, Chrome 120+, Selenium Basic 2.0.9.0