Templates Migration Guide

Documentation for Sessions

Property Templates Migration Guide

Overview

This guide explains how to migrate property_templates from space-specific databases to the global gograb-core database.

Problem

Previously, property templates were incorrectly stored in space-specific databases:

They should be stored globally in:

Solution

We've created a safe, automated migration process that:

  1. Scans all space databases for property_templates
  2. Copies templates to gograb-core (deduplicating by ID)
  3. Preserves original data (no destructive operations)
  4. Updates the PropertiesService to use gograb-core going forward

Migration Steps

Step 1: Dry Run (Recommended)

First, perform a dry run to see what will be migrated without modifying any data:

# Using curl
curl -X POST "http://localhost:3000/api/spaces/any-space-id/properties/migrate-templates-to-core?dryRun=true"

# Or using httpie
http POST "http://localhost:3000/api/spaces/any-space-id/properties/migrate-templates-to-core?dryRun=true"

Note: The spaceId parameter doesn't matter for this endpoint - it scans all spaces.

Expected Output:

{
  "success": true,
  "data": {
    "success": true,
    "spacesScanned": 5,
    "templatesFound": 30,
    "templatesMigrated": 25,
    "templatesDeduplicated": 5,
    "errors": [],
    "details": [
      {
        "spaceId": "679fe44376823",
        "spaceName": "Chrome Space 1",
        "databaseName": "space_chrome-space-1_79fe44376823",
        "templatesFound": 10,
        "templatesMigrated": 8,
        "templates": ["template_sizing_dimensions", "template_spacing", ...]
      }
    ]
  }
}

Step 2: Review Results

Check the dry run output for:

Step 3: Perform Migration

If the dry run looks good, run the actual migration:

# Using curl
curl -X POST "http://localhost:3000/api/spaces/any-space-id/properties/migrate-templates-to-core?dryRun=false"

# Or using httpie
http POST "http://localhost:3000/api/spaces/any-space-id/properties/migrate-templates-to-core?dryRun=false"

Step 4: Verify Migration

Check the gograb-core.core_property_templates collection in MongoDB Compass:

  1. Open MongoDB Compass
  2. Connect to your MongoDB instance
  3. Navigate to gograb-core database
  4. Open core_property_templates collection
  5. Verify all templates are present

Step 5: Test Application

After migration:

  1. Restart your backend API: yarn serve:backend
  2. Test creating/editing widgets to ensure templates load correctly
  3. Check browser console for any errors
  4. Verify templates appear in the property panel

Step 6: Cleanup (Optional)

After verifying everything works, you can optionally remove the old property_templates collections from space databases.

⚠️ WARNING: This is destructive and cannot be undone! Only do this after thorough testing.

# Clean up a specific space (replace with actual spaceId)
curl -X DELETE "http://localhost:3000/api/spaces/679fe44376823/properties/cleanup-space-templates"

To clean up all spaces, you'll need to call this endpoint for each space ID.

What Changed

Before Migration

After Migration

Backward Compatibility

The PropertiesService now:

  1. Reads from gograb-core first (primary)
  2. Falls back to space database if not found (legacy support)
  3. Writes to gograb-core for new templates

This ensures no disruption during migration.

Troubleshooting

Templates Not Loading

If templates don't load after migration:

  1. Check backend logs for errors:
# In the backend terminal
# Look for lines starting with 📋 or ❌
  1. Verify gograb-core collection exists:
# MongoDB shell
use gograb-core
db.core_property_templates.find().count()
  1. Check for built-in templates:
# Should show at least 10 built-in templates
db.core_property_templates.find({ "metadata.isBuiltIn": true }).count()

Migration Errors

If you see errors in the migration result:

  1. Check the errors array in the response
  2. Review backend logs for detailed error messages
  3. Ensure MongoDB connection is stable
  4. Verify you have write permissions to gograb-core

Rollback

If something goes wrong:

  1. The original templates are still in space databases (unmodified)
  2. To rollback, simply remove the migrations by:
# MongoDB shell
use gograb-core
db.core_property_templates.drop()
  1. The application will fall back to space-specific templates automatically

Testing Checklist

Support

If you encounter issues:

  1. Check backend logs: apis/backend-api/logs
  2. Review MongoDB logs
  3. Check the migration service code: apis/backend-api/src/app/properties/property-templates-migration.service.ts
  4. Review the updated PropertiesService: apis/backend-api/src/app/properties/properties.service.ts

Files Modified

New Files

Updated Files

Architecture After Migration

┌─────────────────────┐
│   gograb-core       │
│  ┌───────────────┐  │
│  │ core_property_│  │ ← All templates here
│  │  templates    │  │
│  └───────────────┘  │
└─────────────────────┘
          ↑
          │ PropertiesService reads from here
          │
┌─────────────────────┐
│ All Spaces          │
│  - Chrome Space 1   │
│  - Test Space       │
│  - Production Space │
└─────────────────────┘

Next Steps

After successful migration:

  1. Monitor the system for a few days
  2. If stable, proceed with cleanup (Step 6)
  3. Update documentation to reflect new architecture
  4. Consider adding more global templates to gograb-core

Risk Level: Low (non-destructive, with rollback)