Archived Configuration Errors After Package Upgrade — upgradeConfigurations API

Symptom

After upgrading CloudSense Configurator (cscfga) package and updating custom Apex classes to the new version, active configurations work correctly but archived configurations throw errors when accessed.

Typical error:

Attempt to dereference a null object

This occurs when opening an archived Product Configuration that references a custom lookup attribute (e.g., one that extends cscfga.ALookupSearch). The lookup attribute attempts to read a value from another attribute, but returns null because the archived PC has no attributes linked to it.

Cause

After a package upgrade, archived Product Configurations may lose their attribute associations. When the configuration is opened, custom Apex classes that depend on attribute values (e.g., searchFields.get('existingAddress')) receive null instead of the expected value, causing a NullPointerException.

The root cause is that the archived PC record exists but its child attribute records were not migrated or rebuilt during the upgrade process.

Resolution

Step 1: Verify the archived PC has missing attributes

Run the following SOQL query to check whether attributes exist for the archived Product Configuration:

SELECT Id, Name,
  (SELECT Id, Name FROM cscfga__Attributes__r)
FROM cscfga__Product_Configuration__c
WHERE Id = '<PC_ID>'

If the cscfga__Attributes__r subquery returns no records, the attributes are missing.

Step 2: Rebuild attributes using the upgradeConfigurations API

Call the cscfga.ProductConfigurationBulkActions.upgradeConfigurations Apex API for the affected Product Configuration. This will:

• Redirect the archived configuration to the active Product Definition
• Recreate the missing attribute records
• Un-archive the configuration, making it configurable again

Execute via Developer Console or Apex script:

List<Id> pcIds = new List<Id>{ '<PC_ID>' };
cscfga.ProductConfigurationBulkActions.upgradeConfigurations(pcIds);

Step 3: Verify the configuration is accessible

After running the API, navigate to the Product Configuration in the UI and confirm:
- The configuration loads without errors
- Lookup attributes function correctly
- Attribute values are populated as expected

How the Upgrade API Works

The cscfga.ProductConfigurationBulkActions.upgradeConfigurations() method delegates to an internal upgrader that provides three distinct upgrade operations:

• upgradeConfigurations() (used in this KBA): Redirects the archived configuration to the current active Product Definition, recreates missing child attribute records, and effectively un-archives the configuration.
• upgradeConfigurationsToCurrentDefinition(): Upgrades only the Product Definition reference without recreating attributes.
• upgradeConfigurationsToCurrentIteration(): Upgrades based on structural iteration changes within the same Product Definition.

Migration note: The standalone Configuration Upgrader package (csfgug1) is deprecated as of January 2026. Customers on Configurator v33.x+ should use the integrated cscfga.ProductConfigurationUpgrader with the cscfga. namespace prefix.

Additional Notes

• This issue is specific to archived configurations — active configurations typically compile and upgrade correctly.
• The upgradeConfigurations API redirects the archived config to the current active Product Definition, effectively un-archiving it.
• After running the API, verify that business-critical attribute values are intact, as the upgrade may reset some custom attribute values to defaults.
• If multiple archived PCs are affected, batch the IDs in the upgradeConfigurations call rather than processing one at a time.