guidewire-upgrade-migration

name	guidewire-upgrade-migration
description	Upgrade Guidewire InsuranceSuite versions and migrate between environments. Use when planning version upgrades, handling breaking changes, or migrating from self-managed to Cloud. Trigger with phrases like "guidewire upgrade", "version migration", "insurancesuite update", "cloud migration", "upgrade path".
allowed-tools	Read, Write, Edit, Bash(gradle:*), Bash(git:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Guidewire Upgrade & Migration

Overview

Plan and execute Guidewire InsuranceSuite version upgrades and migrations between self-managed and cloud environments.

Prerequisites

• Current version documentation
• Access to Guidewire Community and documentation
• Test environment for validation
• Backup of current system

Version Upgrade Planning

Guidewire Release Cadence

Release Type	Frequency	Support Period	Example
Major	Annual	3 years	2024.x
Minor	Quarterly	Until next minor	202503
Patch	Monthly	Until next patch	202503.1

Upgrade Path Matrix

Current Version     Target Version      Recommended Path
---------------     --------------      ----------------
2022.x             2024.x              2022 -> 2023 -> 2024
2023.x             2024.x              2023 -> 2024
On-Premise 10.x    Cloud 2024.x        Direct migration with PCF

Instructions

Step 1: Assess Current State

#!/bin/bash
# assess-current-version.sh

echo "=== Guidewire Version Assessment ==="

# Check current version from build files
CURRENT_VERSION=$(grep -m1 'guidewire.version' gradle.properties | cut -d= -f2)
echo "Current Guidewire Version: $CURRENT_VERSION"

# List custom Gosu files
echo ""
echo "Custom Gosu Files:"
find modules/configuration/gsrc -name "*.gs" -type f | wc -l
echo " Gosu source files"

# List PCF customizations
echo ""
echo "PCF Customizations:"
find modules/configuration/config -name "*.pcf" -type f | wc -l
echo " PCF files"

# List entity extensions
echo ""
echo "Entity Extensions:"
find modules/configuration/config -name "*_ext.xml" -type f | wc -l
echo " extension files"

# List integration points
echo ""
echo "Integration Points:"
grep -r "gw.api.rest" modules/configuration/gsrc --include="*.gs" | wc -l
echo 

grep -r  modules/configuration/gsrc --include= |  -l
 

Step 2: Review Breaking Changes

// Breaking change analysis script
interface BreakingChange {
  version: string;
  category: 'API' | 'Gosu' | 'Database' | 'Configuration';
  description: string;
  impact: 'High' | 'Medium' | 'Low';
  migration: string;
}

const breakingChanges: BreakingChange[] = [
  {
    version: '2024.03',
    category: 'API',
    description: 'Deprecated endpoints removed from Cloud API',
    impact: 'High',
    migration: 'Update to new endpoint paths - see migration guide'
  },
  {
    version: '2024.03',
    category: 'Gosu',
    description: 'Query API syntax changes for complex joins',
    impact: 'Medium',
    migration: 'Update Query.make() calls with new join syntax'
  },
  {
    version: '2024.01',
    category: 'Database',
    description: 'Column type changes for monetary amounts',
    impact: 'High',
    migration: 
  }
];

 ():  {
   applicableChanges = breakingChanges.( {
     (change., currentVersion) >  &&
           (change., targetVersion) <= ;
  });

  .();
  .();
  .();

   byCategory = applicableChanges.( {
    acc[change.] = acc[change.] || [];
    acc[change.].(change);
     acc;
  }, {}  <, []>);

  .(byCategory).( {
    .();
    changes.( {
      .();
      .();
    });
  });
}

Step 3: Database Upgrade

// build.gradle - Database upgrade tasks
tasks.register('backupDatabase') {
    doLast {
        exec {
            commandLine 'pg_dump', '-h', dbHost, '-U', dbUser,
                       '-d', dbName, '-F', 'c',
                       '-f', "backup-${dbName}-${new Date().format('yyyyMMdd-HHmmss')}.dump"
        }
    }
}

tasks.register('upgradeDatabase') {
    dependsOn 'backupDatabase'
    doLast {
        // Run Guidewire database upgrade
        exec {
            commandLine './gradlew', 'dbupgrade',
                       "-PdbHost=${dbHost}",
                       "-PdbName=${dbName}",
                       "-PdbUser=${dbUser}",
                       "-PdbPassword=${dbPassword}"
        }
    }
}

tasks.register('validateDatabaseUpgrade') {
    dependsOn 'upgradeDatabase'
    doLast {
        // Verify schema version
        def result = exec {
            commandLine 'psql', '-h', dbHost, '-U', dbUser, '-d', dbName,
                       '-c', 'SELECT version FROM schema_version ORDER BY id DESC LIMIT 1'
            standardOutput = new ByteArrayOutputStream()
        }
        println "Current schema version: ${result.standardOutput}"
    }
}

Step 4: Code Migration

// Automated code migration helpers
package gw.migration

uses gw.api.util.Logger

class CodeMigrationHelper {
  private static final var LOG = Logger.forCategory("Migration")

  // Replace deprecated API calls
  static function migrateDeprecatedAPIs(code : String) : String {
    var migrated = code

    // Example: Migrate old Query syntax
    migrated = migrated.replaceAll(
      "Query\\.make\\(([^)]+)\\)\\.withEqual",
      "Query.make($1).compare"
    )

    // Example: Migrate old date handling
    migrated = migrated.replaceAll(
      "new Date\\(\\)",
      "Date.Today"
    )

    // Example: Migrate deprecated methods
    migrated = migrated.replaceAll(
      "\\.getBundle\\(\\)",
      ".Bundle"
    )

    return migrated
  }

  // Check for deprecated patterns
  static function findDeprecatedPatterns(code : String) : List<String> {
    var issues = new ArrayList<String>()

    var patterns = {
      "deprecated_query" -> "Query.make.*withEqual",
      "old_date" -> "new java.util.Date\\(\\)",
      "string_concat_in_query" -> "\"SELECT.*\\+.*\\+",
      "deprecated_session" -> "SessionInfo.getCurrentSession"
    }

    patterns.eachKeyAndValue(\name, pattern -> {
      if (code.matches(".*${pattern}.*")) {
        issues.add("Found deprecated pattern: ${name}")
      }
    })

    return issues
  }
}

Step 5: Configuration Migration

#!/bin/bash
# migrate-configuration.sh

TARGET_VERSION="202503"
SOURCE_DIR="./modules/configuration"
BACKUP_DIR="./migration-backup-$(date +%Y%m%d)"

echo "=== Configuration Migration to $TARGET_VERSION ==="

# Backup current configuration
echo "Backing up current configuration..."
mkdir -p "$BACKUP_DIR"
cp -r "$SOURCE_DIR" "$BACKUP_DIR/"

# Update product model references
echo "Updating product model references..."
find "$SOURCE_DIR/config/products" -name "*.xml" -exec sed -i \
  's/xmlns="http:\/\/guidewire.com\/pc\/product\/[0-9]*"/xmlns="http:\/\/guidewire.com\/pc\/product\/'"$TARGET_VERSION"'"/' {} \;

# Update typelist references
echo "Updating typelist references..."
find "$SOURCE_DIR/config/typelist" -name "*.xml" -exec sed -i \
  's/schemaVersion="[0-9]*"/schemaVersion="'"$TARGET_VERSION"'"/' {} \;

# Validate XML files
echo "Validating XML files..."
find "$SOURCE_DIR/config" -name "*.xml" - xmllint --noout {} \; 2>&1

 

Step 6: Integration Migration

// API version migration
interface EndpointMigration {
  oldPath: string;
  newPath: string;
  changes: string[];
}

const endpointMigrations: EndpointMigration[] = [
  {
    oldPath: '/account/v1/accounts/{id}/policies',
    newPath: '/account/v1/accounts/{id}/active-policies',
    changes: ['Path renamed', 'Only returns in-force policies']
  },
  {
    oldPath: '/job/v1/submissions/{id}/quote',
    newPath: '/job/v1/submissions/{id}/actions/quote',
    changes: ['Moved to actions sub-resource']
  }
];

function migrateApiCalls(code: string, fromVersion: string, toVersion: string): string {
  let migratedCode = code;

  endpointMigrations.forEach(migration => {
    const oldPattern = new RegExp(
      migration.oldPath.replace(/\{[^}]+\}/g, '[^/]+'),
      'g'
    );

    if (oldPattern.test(migratedCode)) {
      .();
      .();

      migratedCode = migratedCode.(
        migration.,
        migration.
      );
    }
  });

   migratedCode;
}

Step 7: Testing Migration

// Migration test suite
package gw.migration.test

uses gw.testharness.v3.PLTestCase
uses gw.testharness.v3.PLAssert

class MigrationTestSuite extends PLTestCase {

  function testQueryAPICompatibility() {
    // Test new Query API syntax works
    var accounts = Query.make(Account)
      .compare(Account#AccountStatus, Equals, AccountStatus.TC_ACTIVE)
      .select()
      .toList()

    PLAssert.assertNotNull(accounts)
  }

  function testEntityExtensions() {
    // Verify custom entity extensions still work
    var policy = createTestPolicy()
    policy.CustomField_Ext = "Test Value"
    policy.Bundle.commit()

    var loaded = Query.make(Policy)
      .compare(Policy#ID, Equals, policy.ID)
      .select()
      .AtMostOneRow

    PLAssert.assertEquals("Test Value", loaded.CustomField_Ext)
  }

  function testIntegrationEndpoints() {
    // Verify integration endpoints respond correctly
    var client = new ExternalServiceClient()
    var response = client.healthCheck()
    PLAssert.assertTrue(response.isHealthy())
  }

  function testDataMigration() {
    // Verify migrated data integrity
    var count = Query.make(Account).select().Count
    PLAssert.assertTrue(count > 0, "Expected migrated accounts")
  }
}

Cloud Migration Checklist

Pre-Migration

#	Task	Status
1	Complete Guidewire Cloud readiness assessment	[ ]
2	Identify all integration points	[ ]
3	Document custom Gosu code	[ ]
4	Assess data volume and migration time	[ ]
5	Plan downtime window	[ ]

Migration Execution

#	Task	Status
6	Export configuration from on-premise	[ ]
7	Transform configuration for Cloud	[ ]
8	Deploy to Cloud sandbox	[ ]
9	Run smoke tests	[ ]
10	Migrate data	[ ]
11	Update integration endpoints	[ ]
12	Validate all functionality	[ ]

Post-Migration

#	Task	Status
13	Performance testing	[ ]
14	Security validation	[ ]
15	User acceptance testing	[ ]
16	Go-live approval	[ ]

Rollback Procedure

#!/bin/bash
# rollback-upgrade.sh

echo "=== Upgrade Rollback ==="

# Restore database backup
LATEST_BACKUP=$(ls -t backup-*.dump | head -1)
echo "Restoring from: $LATEST_BACKUP"

pg_restore -h "$DB_HOST" -U "$DB_USER" -d "$DB_NAME" -c "$LATEST_BACKUP"

# Restore code to previous version
git checkout previous-version
./gradlew clean build

# Restart services
./gradlew runServer

echo "Rollback complete - verify system functionality"

Output

• Version assessment report
• Breaking change analysis
• Migration scripts
• Test results
• Rollback procedure

Resources

• Guidewire Release Notes
• Cloud Migration Guide
• Upgrade Best Practices

Next Steps

For CI/CD integration, see guidewire-ci-integration.