Use Cases and Best Practices

This guide presents the different usage scenarios of AutoUpgradeTool and the best practices to adopt to ensure successful version upgrades.

Types of Version Upgrades

Minor Version Upgrade

A minor version upgrade is an evolution within the same major version.

Examples:

• 23.14 → 23.15
• 26.0 → 26.1
• 21.10 → 21.12
• 19.24 → 19.25

Characteristics:

• ✅ Low risk
• ✅ Generally no breaking changes
• ✅ Bug fixes and improvements
• ✅ Short upgrade time (10-20 minutes)
• ✅ Can be performed in production with reduced maintenance window

::: tip Recommendation Minor version upgrades can be performed every 2-3 months to benefit from the latest fixes and improvements. :::

Major Version Upgrade

A major version upgrade is a significant version change.

Examples:

• 23.18 → 26.0
• 21.25 → 23.0
• 19.25 → 21.0

Characteristics:

• ⚠️ High risk
• ⚠️ May contain breaking changes
• ⚠️ Major new features
• ⚠️ Possible architecture changes
• ⚠️ Longer upgrade time (30-60 minutes)
• ⚠️ Thorough testing required

Critical Precautions

Major version upgrades require:

1. Complete backup mandatory (DB + files)
2. Pre-production testing before production
3. Planning an extended maintenance window
4. Presence of a technical team during and after the upgrade
5. Complete functional validation post-upgrade
6. Defined and tested rollback plan

Typical Usage Scenarios

Scenario 1: Minor Production Upgrade

Context: You are on version 23.14 and want to upgrade to 23.15 to benefit from bug fixes.

Recommended Steps:

1. Preparation (D-7)

   • Access the Bastille server: S:\3-PRODUIT\ReleaseUpgrades\Patches\v23.x\
   • Copy the patch aps.upgrade.v23.14.v23.15.7z locally
   • Read the 23.15 release notes
   • Identify potential impacts

2. Backup (D-1)

   • Perform a complete backup of the directory DB
   • Perform a complete backup of all application DBs
   • Perform a backup of installation directories

3. Version Upgrade (D, during maintenance window)

   📅 Maintenance window: 2 hours (8:00 PM - 10:00 PM)

   • 7:45 PM: Inform users of maintenance
   • 8:00 PM: Disconnect all users
   • 8:05 PM: Launch AutoUpgradeTool
   • 8:20 PM: Version upgrade completed
   • 8:25 PM: Post-upgrade checks
   • 8:30 PM: Basic functional tests
   • 9:00 PM: Reopen to users
   • 9:00-10:00 PM: Log monitoring

4. Validation (D+1)

   • Check daily logs (errors, performance)
   • Collect user feedback
   • Verify proper Scheduler operation

Total Duration: ~1h (+ 1h safety margin)

Scenario 2: Major Upgrade with Prior Testing

Context: You are on version 23.18 and want to upgrade to 26.0 (major upgrade).

Recommended Steps:

1. Preparation Phase (D-30)

   • Carefully read the 26.0 release notes
   • Identify breaking changes
   • Retrieve the patch from Bastille: S:\3-PRODUIT\ReleaseUpgrades\Patches\v26.x\
   • Plan pre-production testing

2. Pre-production Testing (D-14)

   • Clone production environment to pre-production
   • Perform version upgrade on pre-production
   • Perform complete test campaign:
     • Functional tests (critical processes)
     • Integration tests (connectors, APIs)
     • Performance tests
     • Regression tests
   • Document all encountered problems
   • Prepare necessary fixes

3. Pre-production Validation (D-7)

   • Functional validation by key users
   • Technical validation by IT team
   • Write production upgrade plan
   • Write rollback plan

4. Production Backup (D-1)

   • Complete DB backup (with integrity check)
   • File backup
   • IIS configuration backup
   • Test backup restoration

5. Production Version Upgrade (D, weekend)

   📅 Maintenance window: 4 hours (Saturday 8:00 AM - 12:00 PM)

   • 7:00 AM: Technical team in place
   • 8:00 AM: Close environment to users
   • 8:15 AM: Launch AutoUpgradeTool
   • 9:00 AM: Version upgrade completed
   • 9:00-10:00 AM: Thorough technical checks
   • 10:00-11:00 AM: Validation functional tests
   • 11:00-12:00 PM: Load testing (pilot users)
   • 12:00 PM: Complete reopening

6. Post-upgrade Monitoring (D+7)

   • D+1: Enhanced log and performance monitoring
   • D+2 to D+7: Daily monitoring
   • D+7: Version upgrade assessment

Total Duration: ~3-4h (+ 4h testing and validation)

Scenario 3: Progressive Upgrade Across Multiple Versions

Context: You are on version 23.10 and want to upgrade to 23.18 (8 versions apart).

Option A: Cumulative Patch (recommended)

If a cumulative patch exists on Bastille aps.upgrade.v23.10.v23.18.7z:

1. Use this patch directly
2. AutoUpgradeTool automatically handles intermediate steps
3. Duration: ~30-40 minutes

Option B: Individual Patches

If you only have individual patches:

Step 1: 23.10 → 23.14 (patch v23.10.v23.14.7z)
  ⏱️ Duration: 15 min

Step 2: 23.14 → 23.16 (patch v23.14.v23.16.7z)
  ⏱️ Duration: 15 min

Step 3: 23.16 → 23.18 (patch v23.16.v23.18.7z)
  ⏱️ Duration: 15 min

TOTAL: ~45 minutes

Recommendation:

• Prioritize option A (cumulative patch)
• If option B is necessary, perform all upgrades in a single maintenance window
• Never leave the environment in production on an unstable intermediate version
• Consult the Bastille server to identify available cumulative patches

Scenario 4: Multi-application Instance

Context: Your Process Studio instance hosts 3 distinct applications with different profiles.

Configuration Example:

Instance APS 23.14
├── Application "HR" (master) - Profile HR_PROD
├── Application "ACCOUNTING" - Profile ACCOUNTING_PROD
└── Application "PURCHASING" - Profile PURCHASING_PROD

Particularities:

1. Automatic Detection

   • AutoUpgradeTool automatically detects all 3 applications
   • Each application can have its own database
   • Each application can have its own version (rare but possible)

2. Simultaneous Version Upgrade

   • AutoUpgradeTool updates all applications at the same time
   • Patches are applied to each application
   • SQL scripts are executed on each database

3. Specific Precautions

   • Back up all databases (directory + 3 application databases)
   • Plan a longer maintenance window (proportional to number of apps)
   • Test all applications after the version upgrade

Estimated Duration: Base (20 min) + 10 min per additional application = 50 minutes

Scenario 5: Partner Intervention at Client Site

Context: You are an Avanteam partner and need to perform a version upgrade at a client site.

Intervention Checklist:

Before Intervention (D-7)

• Obtain connection information (server access, DB)
• Verify client's current version
• Download AutoUpgradeTool from Bastille
• Download necessary patches from Bastille
• Plan maintenance window with client
• Ask client to perform complete backup

Day of Intervention

• Connect via remote desktop with administrator account
• Verify backup was properly performed
• Copy AutoUpgradeTool to client server
• Copy patches to client server
• Perform version upgrade
• Perform post-upgrade checks
• Perform manual actions from README
• Conduct functional tests with client

After Intervention (D+1)

• Call client to verify no problems
• Record intervention in ticketing tool
• Archive upgrade logs
• Clean temporary files on client server

Scenario 6: Multi-stage Major Upgrade (19.x → 26.x)

Context: Client on version 19.25 wanting to upgrade to 26.0 (3 major versions).

Progressive Upgrade Plan:

Phase 1: 19.25 → 21.0 (major upgrade, ~45 min)
  📦 Patch: S:\3-PRODUIT\ReleaseUpgrades\Patches\v21.x\aps.upgrade.v19.25.v21.0.7z
  ⚠️ Thorough testing required
  
Phase 2: 21.0 → 21.25 (cumulative minor upgrade, ~20 min)
  📦 Patch: S:\3-PRODUIT\ReleaseUpgrades\Patches\v21.x\aps.upgrade.v21.0.v21.25.7z
  ✅ Stabilization on latest 21.x version

Phase 3: 21.25 → 23.0 (major upgrade, ~45 min)
  📦 Patch: S:\3-PRODUIT\ReleaseUpgrades\Patches\v23.x\aps.upgrade.v21.25.v23.0.7z
  ⚠️ Thorough testing required

Phase 4: 23.0 → 23.18 (cumulative minor upgrade, ~20 min)
  📦 Patch: S:\3-PRODUIT\ReleaseUpgrades\Patches\v23.x\aps.upgrade.v23.0.v23.18.7z
  ✅ Stabilization on latest 23.x version

Phase 5: 23.18 → 26.0 (major upgrade, ~45 min)
  📦 Patch: S:\3-PRODUIT\ReleaseUpgrades\Patches\v26.x\aps.upgrade.v23.18.v26.0.7z
  ⚠️ Thorough testing required

TOTAL: ~3h (phases) + intermediate testing

Recommendations:

• Perform each phase in pre-production before production
• Plan 1 week between each major phase for validation
• Document all problems encountered at each phase
• Backup before each phase

General Best Practices

Backups

::: danger Golden Rule Always perform a complete backup before any version upgrade, regardless of its criticality. :::

Recommended Backups:

Element	Method	Frequency
Directory DB	Complete SQL backup	Before each upgrade
Application DBs	Complete SQL backup	Before each upgrade
APS Files	Complete copy of installation directory	Before each major upgrade
IIS Configuration	PowerShell export	Before each major upgrade

Complete Backup PowerShell Script:

$Date = Get-Date -Format "yyyyMMdd_HHmmss"
$BackupRoot = "D:\Backups\APS_Backup_$Date"

New-Item -ItemType Directory -Path $BackupRoot -Force

$Databases = @("APS_Directory", "APS_App_HR", "APS_App_ACCOUNTING")
foreach ($DB in $Databases) {
    $BackupFile = "$BackupRoot\$DB.bak"
    Invoke-Sqlcmd -Query "BACKUP DATABASE [$DB] TO DISK = '$BackupFile' WITH COMPRESSION"
}

$APSPath = "C:\Program Files\Avanteam\"
Copy-Item -Path $APSPath -Destination "$BackupRoot\Files" -Recurse

Export-IISConfiguration -Path "$BackupRoot\IIS_Config"

Write-Host "✅ Complete backup finished: $BackupRoot" -ForegroundColor Green

Version Upgrade Planning

When to Perform a Version Upgrade?

Type	Recommended Frequency	Optimal Time
Minor	Every 2-3 months	Weekday evening (8 PM-10 PM)
Major	Once a year	Weekend (Saturday morning)
Urgent Fix	If necessary	As soon as possible (with validation)

Periods to Avoid:

• ❌ High business activity periods (closings, campaigns)
• ❌ Eve of technical team vacations
• ❌ Vacation periods (summer, year-end)

Risk Management

Risk Assessment

Before each version upgrade, assess the risk level:

🔴 HIGH RISK (major upgrade + critical production)
   → Pre-production testing mandatory
   → Long maintenance window (4-6h)
   → Complete technical team present
   → Validated rollback plan

🟠 MEDIUM RISK (minor upgrade + important production)
   → Pre-production testing recommended
   → Standard maintenance window (2-3h)
   → Technical lead available
   → Validated backup

🟢 LOW RISK (minor upgrade + dev/test environment)
   → Basic testing
   → Short maintenance window (1-2h)
   → Standard backup

Rollback Plan

For each version upgrade, define a rollback plan:

Rollback Trigger Criteria:

• Critical blocking error during upgrade
• Inability to connect to Process Studio after upgrade
• Data loss detected
• Major performance degradation
• Critical bug in production not quickly resolvable

Rollback Procedure:

net stop "PStudio.Services.Remoting*"
net stop "PStudio.Scheduler*"

Stop-WebAppPool -Name "APP*"

# Restore database backups
# Restore file backups

iisreset /restart

net start "PStudio.Services.Remoting*"
net start "PStudio.Scheduler*"

Estimated Rollback Time: 30-60 minutes (depending on DB size)

User Communication

Information Email (D-7)

Subject: [PLANNED MAINTENANCE] Process Studio Version Upgrade - Saturday DD/MM at 8:00 AM

Hello,

As part of the continuous improvement of our Process Studio platform,
a version upgrade will be performed on Saturday DD/MM from 8:00 AM to 12:00 PM.

📅 Date: Saturday DD/MM/YYYY
⏰ Hours: 8:00 AM - 12:00 PM
🔧 Type: Version upgrade 23.14 → 26.0

During this period, Process Studio will be UNAVAILABLE.

Thank you for your understanding.

The Technical Team

Confirmation Email (D after upgrade)

Subject: ✅ [COMPLETED] Process Studio Version Upgrade Successful

Hello,

The Process Studio version upgrade was successful.

✅ Current version: 26.0
✅ Services operational
✅ Validation tests OK

The platform is accessible again. If you encounter any problems,
please contact technical support.

The Technical Team

Using Bastille Server

Access Best Practices

net use S: \\bastille\S$ /persistent:yes

Test-Path "S:\3-PRODUIT\ReleaseUpgrades"

$LocalPath = "C:\Avanteam\Temp\"
Copy-Item "S:\3-PRODUIT\ReleaseUpgrades\AutoUpgradeTool\v2.4\*" -Destination $LocalPath -Recurse

Download Organization

Create a local structure to facilitate interventions:

C:\Avanteam\
├── AutoUpgradeTool\         # Latest tool version
└── Patches\                 # Version upgrade patches
    ├── 2019\
    ├── 2021\
    ├── 2023\
    └── 2026\

Complete Version Upgrade Checklist

Preparation Phase

• Reading release notes
• Downloading tool from Bastille
• Downloading necessary patches from Bastille
• Planning maintenance window
• User information (D-7)
• Pre-production testing (major upgrades only)

Backup Phase

• Directory DB backup
• All application DB backups
• Installation directory backup
• IIS configuration backup
• Backup integrity verification

Version Upgrade Phase

• Disconnect all users
• Launch AutoUpgradeTool as administrator
• Patch selection
• Instance detection validation
• Target version selection
• Start version upgrade
• Real-time log monitoring

Validation Phase

• Windows services verification
• IIS pools verification
• Process Studio Web connection
• Displayed version verification
• Basic functional tests
• Application log consultation
• Manual actions execution (README)

Post-upgrade Phase

• Reopen to users
• Log monitoring (H+2)
• User confirmation email
• Performance monitoring (D+1)
• User feedback collection (D+2)
• Version upgrade assessment (D+7)

Next Steps

To resolve common problems encountered during version upgrades:

➡️ Troubleshooting and FAQ

Additional Resources

• 📖 Introduction to AutoUpgradeTool
• 🛠️ Installation and Configuration
• 📝 Step-by-step Usage Guide
• 📁 Bastille Server: S:\3-PRODUIT\ReleaseUpgrades\

Related Articles

• AutoUpgradeTool
• ImportDocs
• Getting Started Guide