hm_ai_qc_report_tool/MIGRATION_GUIDE.md

Migration Guide: v2.0.0 → v2.1.0

This guide helps you upgrade from the previous version to the new CAMPAIGNS folder structure with progress indicators.

What's Changed?

1. Box Folder Structure

Old Structure:

REPORT_FOLDER_ID (303321539397)/
└── 10107-06/
    ├── file1_QC.html
    └── file2_QC.html

New Structure:

CAMPAIGNS (133295752718)/
└── 2069052/              # Campaign number
    ├── CAMPAIGN_ASSETS/
    ├── JOBS/
    └── QC/               # QC reports here
        ├── file1_QC.html
        └── file2_QC.html

2. Search Behavior

• Old: Searched in a single folder or by filename
• New: Searches through 3500+ campaigns, navigates to QC subfolder
• Duration: 5-10 seconds (shows progress bar)
• Pagination: Automatic, handles large folder lists

3. User Interface

• Added: Real-time progress bar during search
• Added: Status messages (Connecting, Searching, Processing, Success)
• Improved: Visual feedback with spinner and progress percentage

Step-by-Step Migration

Step 1: Backup Current Configuration

# Backup your current .env file
cp .env .env.backup

# Backup box config
cp config/box_config.json config/box_config.json.backup

Step 2: Update Environment Variables

Edit .env file:

# Change this line:
# BOX_REPORT_FOLDER_ID=303321539397

# To this:
BOX_REPORT_FOLDER_ID=133295752718

Or use sed:

sed -i '' 's/BOX_REPORT_FOLDER_ID=303321539397/BOX_REPORT_FOLDER_ID=133295752718/' .env

Step 3: Update Box Configuration (if needed)

If you received a new box_config.json file:

# Copy new config file
cp /path/to/new/box_config.json config/box_config.json

# Set proper permissions
chmod 600 config/box_config.json

Step 4: Verify Box Access

Ensure the Box service account has access to the CAMPAIGNS folder:

# Test connection
python3 -c "
from box_client import BoxReportClient
client = BoxReportClient('config/box_config.json', '133295752718')
print('✅ Connection successful!')
"

Expected output:

INFO:box_client:Authenticated as Box user: Oliver-Box-Uploader
✅ Connection successful!

Step 5: Test Search Functionality

# Start the application
python3 app.py

# In another terminal, test the API
curl -s http://localhost:7183/health | python3 -m json.tool

Expected output:

{
  "box_connected": true,
  "status": "healthy",
  "timestamp": "2025-12-17T..."
}

Step 6: Test with Real Campaign

1. Open http://localhost:7183 in your browser
2. Sign in with Microsoft
3. Search for campaign: 2069052
4. You should see:
   • Progress bar appear
   • Status: "Connecting to Box..."
   • Status: "Searching campaigns folder..."
   • Status: "Processing results..."
   • Status: "Success! Found 19 reports"
   • Redirect to dashboard

Step 7: Verify Dashboard

After searching:

• Dashboard should load with 19 reports
• All HTML files should be from the QC subfolder
• Check that reports are displaying correctly

Troubleshooting Migration Issues

Issue: "No reports found"

Check 1: Campaign folder exists

python3 -c "
from box_client import BoxReportClient
client = BoxReportClient('config/box_config.json', '133295752718')
folder = client.client.folder('133295752718').get()
items = list(folder.get_items(limit=20))
print('First 20 campaigns:')
for item in items:
    if item.type == 'folder':
        print(f'  - {item.name}')
"

Check 2: QC subfolder exists

python3 -c "
from box_client import BoxReportClient
client = BoxReportClient('config/box_config.json', '133295752718')

# Replace 2069052 with your campaign number
reports = client.search_by_job_number('2069052')
print(f'Found {len(reports)} reports')
for report in reports[:5]:
    print(f'  - {report[\"name\"]}')
"

Check 3: Verify folder structure

• Log into Box.com
• Navigate to CAMPAIGNS folder
• Find your campaign number
• Verify QC subfolder exists
• Check that HTML files are inside QC folder

Issue: "Search takes too long"

This is expected behavior! The search:

• Paginates through 3500+ campaigns
• Campaign 2069052 is at position ~3507
• Takes 5-10 seconds (4 API calls)
• Progress bar shows status

To verify it's working:

• Check browser console (F12)
• Look for network requests to Box API
• Progress bar should be updating
• Status messages should be changing

Issue: "Box authentication failed"

Check 1: Config file exists

ls -la config/box_config.json
# Should show: -rw------- (permissions 600)

Check 2: Service account has access

• Box service account: AutomationUser_2239684_XmNAVhQUsB@boxdevedition.com
• Must have access to CAMPAIGNS folder (ID: 133295752718)
• Share folder with this account if needed

Check 3: JWT credentials valid

python3 -c "
import json
with open('config/box_config.json') as f:
    config = json.load(f)
    print(f'Client ID: {config[\"boxAppSettings\"][\"clientID\"]}')
    print(f'Enterprise ID: {config[\"enterpriseID\"]}')
"

Rolling Back

If you need to revert to the old version:

Step 1: Restore Configuration

# Restore .env
cp .env.backup .env

# Restore box config
cp config/box_config.json.backup config/box_config.json

Step 2: Restore Code

# Revert box_client.py changes
git checkout HEAD -- box_client.py

# Revert template changes
git checkout HEAD -- templates/index.html

Step 3: Restart Application

# Stop current server (Ctrl+C)

# Start with old configuration
python3 app.py

Testing Checklist

After migration, verify:

• Application starts without errors
• Health check returns "box_connected": true
• Can sign in with Microsoft account
• Search shows progress bar
• Can find campaign 2069052 (or other test campaign)
• Dashboard loads with correct number of reports
• Reports display properly in dashboard
• Can switch between Parsed Data and Embedded views
• Can export to PDF (if WeasyPrint installed)
• Can sign out successfully

Performance Expectations

Search Times

Campaign Position	Expected Time	API Calls
1-1000	2-3 seconds	1
1001-2000	3-5 seconds	2
2001-3000	5-7 seconds	3
3001+	7-10 seconds	4+

What's Normal?

• Progress bar appearing immediately ✅
• Status messages updating ✅
• Search taking 5-10 seconds for later campaigns ✅
• Multiple Box API calls in logs ✅

What's NOT Normal?

• Search hanging without progress ❌
• No status updates in progress bar ❌
• Error messages in console ❌
• Search taking over 30 seconds ❌

Need Help?

If you encounter issues during migration:

1. Check the logs: Application logs show Box API calls and errors
2. Test the Box client directly (see troubleshooting commands above)
3. Verify folder structure in Box.com web interface
4. Review CHANGELOG.md for detailed technical changes
5. Contact the development team with:
   • Error messages from logs
   • Campaign number you're testing
   • Output of troubleshooting commands

Additional Resources

• README.md: Full application documentation
• CHANGELOG.md: Detailed version history
• test_local.sh: Automated testing script
• .env.example: Configuration template