Skip to content

AcuOps Upgrade Runbook

Pre-upgrade validation checklist for Acumatica version upgrades.

T-30 Days: Planning

  • [ ] Review Acumatica release notes for the target version
  • [ ] Check for breaking changes in the Customization Framework
  • [ ] Identify any deprecated APIs or types your code references
  • [ ] Run AcuOps Upgrade Check workflow (GitHub Actions)
  • [ ] Back up current production package

T-14 Days: Staging Validation

  • [ ] Upgrade staging/test instance to target version
  • [ ] Deploy customization to upgraded staging
  • [ ] Verify all screens load without errors
  • [ ] Test all custom fields and business logic
  • [ ] Check for CS0246 errors (type not found — moved/renamed in new version)
  • [ ] Run validation: python scripts/validate-project.py --strict project.xml

T-7 Days: Code Updates

If issues were found:

  • [ ] Update using statements for moved types
  • [ ] Fix any compilation errors found during staging validation
  • [ ] Update product-version attribute in project.xml
  • [ ] Re-validate against staging
  • [ ] Merge fixes to main (but do NOT deploy to production yet)

T-1 Day: Pre-Upgrade Backup

# Download current production package
scripts/backup.sh \
  --project MyCustomization \
  --output backups/pre-upgrade/

# Verify backup is valid
ls -la backups/pre-upgrade/

T-0: Upgrade Day

During Acumatica Upgrade Window

  1. Acumatica performs the version upgrade
  2. After upgrade completes, verify instance is accessible
  3. Deploy updated customization: 
    scripts/deploy.sh \
  --project MyCustomization \
  --package dist/MyCustomization.zip \
  --also-publish "OtherActiveProjects"
  4. Verify deployment in Acumatica System Monitor

If Deploy Fails

# Restore from pre-upgrade backup
scripts/restore.sh \
  --project MyCustomization \
  --package backups/pre-upgrade/MyCustomization_backup_*.zip

T+1 Day: Verification

  • [ ] All custom screens load correctly
  • [ ] Custom fields display and save properly
  • [ ] Business logic (event handlers, cascades) works
  • [ ] No errors in Acumatica System Monitor
  • [ ] Co-published projects all healthy

Common Upgrade Issues

Issue Cause Fix
CS0246 (type not found) Type moved to different namespace Update using statement
NullReferenceException <Table> elements Convert to <Sql> with IF NOT EXISTS
ARCustomerClass not found Not a public type in v24.2+ Use PX.Objects.AR.CustomerClass
Publish timeout Large project or slow instance Increase poll_timeout in acuops.yaml