--- schema_version: "1" id: 629f9d392af1c8f55f8007a62daf0b091ff1d842712632b1c51fbf74e2b3ab22 title: Post-Install Maintenance collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/post-publication.md canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/post-publication.html source_site: developer.salesforce.com content_type: documentation content_hash: a1b707c9e895b07055798a4dccf6afc7841127424de1e246f7e2d93868efe7e7 products: - Composable Storefront - Salesforce APIs --- # Post-Install Maintenance Manage updates, replication, and support after a Commerce App is installed — whether it was published to the registry or installed privately from WebDAV. ## Updating Your App Package and test every update as a new CAP. ISVs publish the new version through the App Registry; private-app producers deliver the new `.zip` directly to the merchant. Compare updates with the producer's retained release artifact. For registry apps, `b2c cap pull --site-id ` can retrieve the registry package. Private WebDAV packages can be pulled only when the installed record has a persisted version and the uploaded archive was retained. Include versioned migration directories in `impex/` (for example, `v1.1.0/`) for schema changes that need to run on upgrade. ## Replication Compatibility ### Recommended Merchant Workflow The expected lifecycle for promoting a Commerce App from staging to production: 1. **Install on staging.** Use Business Manager or `b2c cap install` to install the app on the staging instance for the target site. 2. **Configure and test on staging.** Complete every task in the app's `tasksList.json` (entering API credentials, setting site preferences, running test transactions). Validate end-to-end behavior on the staging storefront before promoting. 3. **Replicate code to production.** Run Code Replication first to move cartridges to the production realm. The app won't function on production until cartridges are present. 4. **Replicate supported site data to production.** Select the applicable site preferences and metadata, including the separate `CommerceFeatureState` replication task. Replicate the cartridge path only after the cartridges are present. 5. **Configure non-replicated resources.** Import or configure service definitions and profiles separately, and enter production credentials on the target instance. Re-run any `tasksList.json` step required for that instance. 6. **Integrate storefront code.** Merge or otherwise deploy Storefront Next code separately; B2C code replication doesn't deploy the merchant's storefront repository. 7. **Verify on production.** Confirm the cartridge path, `CommerceFeatureState`, services, credentials, storefront code, and end-to-end behavior before opening to live traffic. ### How Replication Moves a Commerce App Commerce Apps are designed to be replication-friendly. An app installed on a staging instance can be promoted to production using standard Commerce Cloud replication: - Code Replication moves cartridges (realm-scoped) - Data Replication moves selected supported site data; select `CommerceFeatureState` as its own replication task - Service definitions and profiles require separate import or target-instance configuration - Storefront Next code follows the merchant's storefront source-control and deployment process > **Important:** Code replication must complete before data replication. If the cartridge path is updated before the cartridges exist on the production realm, the storefront fails to initialize the feature. > **Important:** Standard Data Replication doesn't move service configurations or credentials. Import or configure the required service metadata separately, and enter API keys, passwords, and other secrets on the target instance. Include a credential configuration step in your app's `tasksList.json` for every instance where the app is activated. See: [Web Services in B2C Commerce](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html) ## Multi-Site Considerations Commerce Apps support installation across multiple sites within the same realm. For the full mechanism — cartridge sharing, per-site state, deferred cleanup on the last-site uninstall, and feature toggle handling — see [Multi-Site Behavior](/docs/commerce/b2c-commerce/guide/reference.md#multi-site-behavior). > **Tip for ISVs:** If your app stores site-specific data in custom objects, make sure your uninstall IMPEX handles per-site data cleanup. Instance-scoped resources (service definitions, custom object type definitions) are removed only by the last-site uninstall, which the platform handles automatically. ## Version Management Version tracking in `catalog.json` applies to **ISVs** publishing to the App Registry. Private apps have no registry entry; ship a new `.zip` and reinstall. When publishing a new version to the App Registry: - Update the ZIP and root manifest entry (`version`, `zip`, `sha256` fields). Do **not** manually add new version entries to `catalog.json` — CI generates those automatically when your PR merges. Allow up to 15 minutes after merge for the new version to appear in existing Business Manager sessions; see [Manifest and Catalog Cache TTL](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reference.md#manifest-and-catalog-cache-ttl). - To deprecate a previous version, add `"deprecated": true` to the **existing** version entry in `catalog.json`. This is the only manual edit to `catalog.json` that is expected. Use deprecation for versions with critical bugs or known issues that should prevent new installations. - Version upgrades are currently a manual process: merchants uninstall the old version and install the new one. Automated in-place upgrades are planned for a future release (Wave 3). ## Monitoring and Support For the initial release, implement your own logging within your cartridge scripts and monitor through standard Commerce Cloud mechanisms: - **Job execution logs:** Installation, uninstallation, and IMPEX processing results are logged in Business Manager under **Administration** > **Operations** > **Job Schedules**. The install job writes detailed step-by-step progress to the job log. - **Custom script logging:** Use the `dw.system.Logger` API in your hook implementations. Log at appropriate levels: `debug` for detailed flow, `info` for key operations, `warn` for recoverable issues, `error` for failures. - **CommerceFeatureState:** Query the `CommerceFeatureState` system object to check installation status, configuration progress, and error messages for a specific site. The `InstallationMetadata` JSON field contains the job execution ID, cartridge names, and any error details.