> For the complete documentation index, see [llms.txt](https://docs.kernel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kernel.ai/integrations/salesforce-integration/migrate-the-salesforce-package-from-3.x-to-4.x.md).

# Migrate the Salesforce package from 3.x to 4.x

Install the namespaced package alongside 3.x, move data and configuration, verify the result, then retire the old package.

This guide is for Salesforce admins moving an existing Kernel integration from 3.x to the namespaced 4.x package. Arrange the migration with your Kernel team and rehearse it in a sandbox before production.

4.x is a separate package. Install it alongside 3.x, copy and check your data, update your customisations, then uninstall 3.x. The namespace separates Kernel's components from other Salesforce customisations and reduces naming collisions.

> Keep 3.x installed until the checks in this guide are complete. Uninstalling removes the old package's objects and data. The Migration Assistant copies selected data and configuration; it does not move every customer customisation or provide an automatic rollback.

### Before you start

Agree a maintenance window with Kernel. Salesforce sync will be paused during the migration, and Kernel must separately pause inbound enrichment and hierarchy writes for your tenant. **Quiesce Now** only stops activity inside Salesforce.

Have the following ready:

* A Salesforce admin who can install and uninstall packages, manage scheduled jobs and custom metadata, and assign permission sets.
* The approved 4.x installation link for the target org, supplied by Kernel. Check the package version, namespace and release status on the install screen.
* Your Kernel API key, available securely. The new package has its own credential store and cannot copy the old key.
* A sandbox rehearsal using representative data, custom fields, permissions and automation.
* Confirmation from Kernel that its Salesforce object and field mappings support the target package.

Back up the old Kernel Account and feedback records, including record IDs and Account links. Also export any customer fields and other package data you need to retain. Save the current settings, all Record Sync configurations, field mappings, filters, scheduled jobs and permission assignments. Record page-layout and Lightning-page assignments, reports, formulas, Flows and Apex that reference Kernel components.

Keep an independent backup before uninstalling. Salesforce's uninstall process may offer a package-data export; this is an additional copy, not your migration plan. See [Salesforce's uninstall guidance](https://help.salesforce.com/s/articleView?id=distribution_uninstalling_packages.htm\&language=en_US\&type=5).

### What changes in 4.x

Kernel Account still stores Kernel's data about a Salesforce Account. Its API name changes, and copied Kernel Account and feedback records receive new Salesforce record IDs. The standard Salesforce Account keeps its ID.

The examples below use the production namespace `kernel`. Confirm the prefix in **Setup → Installed Packages** and use the actual API names in **Object Manager**. A rehearsal package may have a different prefix.

| Component                       | 3.x API name                                | 4.x API name                                |
| ------------------------------- | ------------------------------------------- | ------------------------------------------- |
| Kernel Account object           | `Kernel_Account__c`                         | `kernel__Account__c`                        |
| Lookup from standard Account    | `Account.Kernel_Account__c`                 | `Account.kernel__Kernel_Account__c`         |
| Lookup back to standard Account | `Kernel_Account__c.Linked_Account_Field__c` | `kernel__Account__c.kernel__CRM_Account__c` |
| Kernel ID on Kernel Account     | `Kernel_ID__c`                              | `kernel__Kern_Id__c`                        |
| Legal name on Kernel Account    | `Kernel_Legal_Name__c`                      | `kernel__Legal_Name__c`                     |
| Website on Kernel Account       | `Kernel_Website__c`                         | `kernel__Website__c`                        |
| Revenue on Kernel Account       | `Kernel_Revenue__c`                         | `kernel__Revenue_USD__c`                    |
| Feedback object                 | `Kernel_Feedback__c`                        | `kernel__Feedback__c`                       |

Use the complete rename map supplied by Kernel for your integration. Adding a namespace to the old name is not enough: several field names also change. Repoint external integrations, reports, formulas, Flows, Apex, list views and lookups to the new objects, fields and record IDs.

### 1. Install 4.x alongside 3.x

1. Open the approved install link for the intended sandbox or production org. Confirm the org and package details before installing.
2. Follow Kernel's installation instructions and wait for installation to complete. Leave 3.x installed.
3. Assign the new package's **Admin** permission set to the admin carrying out the migration. Old permission-set assignments do not grant access to the new package automatically.
4. Open the new Kernel app from the **App Launcher**, then open **Kernel Setup → Migration Assistant**. While both packages are installed, distinguish them by their namespace and API names.

While both packages are installed, the new package suppresses automatic mirror creation and default configuration seeding. Manual syncs and customer automation still need to be controlled. Do not enable competing syncs or allow users to edit data being copied.

### 2. Pause writes and quiesce 3.x

1. Ask Kernel to pause inbound enrichment and hierarchy writes for your tenant, and wait for confirmation.
2. Save your scheduled-job definitions, including configuration names and frequency. Keep this record even if the assistant also logs them.
3. In **Migration Assistant**, review the automatic-record-creation setting and the listed scheduled jobs, then click **Quiesce Now**.
4. Review any job that the assistant cannot confidently identify. Cross-check it in **Setup → Scheduled Jobs** before using **Stop**. Stop only the jobs that belong to the old Kernel package.
5. Confirm that old automatic record creation is disabled, old Kernel jobs have stopped, and any in-flight writes have finished.

Quiescing snapshots the old settings and starts copying sync configuration before stopping the old jobs. Customer sync configurations are discovered through scheduled-job names. An unscheduled configuration may need to be recreated manually, so compare the copy with your full backup.

Stopping a job removes its schedule. The assistant cannot recreate the old package's schedule for you.

### 3. Copy settings, configuration and data

1. Click **Copy Settings** explicitly. This carries the organisation's default settings and integration-user/tenant identity into the new package. Profile-level and user-level settings overrides need separate review and migration. Old sync completion flags and dates are not carried over.
2. Wait for the configuration deployment started by **Quiesce Now** to finish, then check the copied configurations in **Kernel Setup → Record Sync**. Use **Copy Sync Configs** if a retry is needed, and wait for its deployment. Once the old schedules are removed, a retry may not rediscover all customer configuration names; compare against your backup and recreate missing configurations.
3. Click **Run Kernel Account Copy** under **Account mirrors** and wait for the job to finish.
4. Click **Run Feedback Copy** after the Account mirror copy has finished.
5. Review the job results and migration logs for failed writes and skipped records.

The two default configurations change developer names:

| 3.x                         | 4.x                                  |
| --------------------------- | ------------------------------------ |
| `Account_to_Kernel_Account` | `Standard_Account_to_Kernel_Account` |
| `Kernel_Account_to_Account` | `Kernel_Account_to_Standard_Account` |

Customer configurations keep their developer names. Check each configuration's source and destination objects, field API names, direction, filters and enabled state. Recreate any configuration that was not discovered or copied.

The Account mirror copy fills the new Account lookup and leaves the old lookup in place. It skips mirrors with no linked Salesforce Account and duplicate legacy mirrors, and records skipped counts in migration logs. Feedback needs a link through an old mirror to a new mirror; rows without that path are skipped. Account-only feedback can therefore need separate handling. Resolve or explicitly account for every skipped record before uninstalling.

Copy jobs can be rerun after an interrupted or partly failed run. Keep writes paused and review the results again. A completed batch status alone does not prove that every record copied successfully.

### 4. Restore your customisations and access

The assistant does not recreate customer fields, reports, record pages, automation or permission assignments. It also does not copy old application logs, audit history or every related record. Back up and migrate any of these that your organisation needs to retain.

* Recreate customer fields on the new Kernel Account object and migrate their values separately. Subscriber-created fields remain customer-owned; a namespaced object can still have these fields.
* Repoint customer lookups and references using the new Kernel Account IDs. Do not reuse old mirror IDs.
* Update formulas, reports, Flows, Apex, actions and Lightning components to the new API names. Check page layouts and record-page activation for each relevant app, profile and record type.
* Assign the appropriate new packaged permission sets to the integration user and end users. Rebuild customer-specific grants against the new fields and objects in a customer-owned permission set.
* Compare each Record Sync configuration with the saved original, including both directions if you copy values between Account and Kernel Account.

The packaged permission sets have shorter names in 4.x:

| 3.x                                               | 4.x developer name, within the new namespace |
| ------------------------------------------------- | -------------------------------------------- |
| `Kernel_Admin_PermissionSet`                      | `Admin`                                      |
| `Kernel_SF_Connected_App_PermissionSet`           | `Integration_User`                           |
| `Kernel_Integration_User_Read_Only_PermissionSet` | `Integration_User_Read_Only`                 |
| `Kernel_Readonly_PermissionSet`                   | `Readonly`                                   |
| `Kernel_Sync_User_PermissionSet`                  | `Sync_User`                                  |
| `Kernel_Account_Management_PermissionSet`         | `Account_Management`                         |

Choose access for the workflows you enable. Migration administration does not mean the ongoing integration user needs the System Administrator profile. Review the user's profile, permission sets, field access and record access together. See the [permission matrix](https://docs.kernel.ai/integrations/salesforce-integration/salesforce-integration-user-permission-matrix).

### 5. Set the new package's API key

Open the new **Kernel Setup → Integration User** and confirm the copied integration user and tenant identity with Kernel. Enter and save your Kernel API key, then complete **Sync with Kernel**, **Resync** or **Reconnect** as prompted by the displayed state. If the connection screen hides the key field, use **Reconnect** to reopen the credential setup. Use **Test connection** and confirm that the Migration Assistant shows the key as configured before removing 3.x.

The old key is not copied and is removed with the old credential store. A **Connected** badge confirms only part of the setup. Test an actual outbound operation, such as search or feedback, under the intended user's permissions when Kernel confirms it is appropriate to do so.

### 6. Verify before removing 3.x

Click **Run Verification** in the Migration Assistant. Check the old and new row counts, missing Account links and reported field discrepancies. Confirm that the legacy count agrees with your backup. A zero count or empty discrepancy list can also result from an unreadable legacy object.

The built-in verification checks counts, link coverage and four fields on a sample of up to 20 mirrors. Complete these additional checks:

* Reconcile all copy errors, unlinked or duplicate mirrors, and unmapped feedback. Explain count differences rather than assuming they are harmless.
* Compare representative records, including custom-field values, hierarchy links and feedback history. Confirm the new Account lookup points to the expected new mirror.
* Confirm that all required sync configurations deployed and use the correct objects and fields.
* Test the pages and workflows your team uses under actual user roles. Include search, feedback, enrichment and customer automation where applicable.
* Confirm with Kernel that its connection uses the new package's schema and that inbound data will go to the new objects after cutover.
* Save the verification report, job results, configuration backup and the list of any separately migrated data.

Keep 3.x installed and syncing paused if a check fails. The assistant's report is one part of the decision to proceed.

### 7. Remove 3.x and resume 4.x

Only continue once the data, customisation and connection checks are complete and Kernel agrees the org is ready.

1. Confirm the new API key is configured and your independent backups are complete.
2. Resolve references that still depend on 3.x. Salesforce can block an uninstall when other components refer to the old package.
3. In **Setup → Custom Metadata Types**, locate the old **Sync Config** type with **no namespace**. Back up its records, confirm their new copies and any manual replacements, then delete the old records that block the uninstall. Keep the new namespaced type and its records.
4. In **Setup → Installed Packages**, uninstall the old 3.x Kernel package. Check the package version and namespace carefully.
5. Open the new **Kernel Setup** again as an admin. Once the old package is gone, the new package resumes its post-migration setup. It schedules analytics if enabled and seeds default sync configurations only when none exist.
6. Review your saved schedule definitions with Kernel. Recreate and enable your customer schedules in **Sync Schedules** at the agreed restart time. The resume step does not restore those schedules automatically.
7. Coordinate that restart with Kernel resuming inbound enrichment and hierarchy writes to the new package.
8. Confirm a successful inbound update, outbound operation and scheduled run with the expected data in the expected fields. Check **Recent Job Runs**, including record errors, after the next scheduled run.

Keep the backups until the team has checked normal operation after cutover. Use [Troubleshoot sync and check integration health](https://docs.kernel.ai/integrations/salesforce-integration/troubleshoot-sync) if a job fails or values do not arrive.

### If the migration stops or fails

Before uninstalling 3.x, keep both packages installed and writes paused. Save the exact error and job results. Resolve the failure with Kernel, then rerun the affected copy step and verification. If you abandon the migration, restore the old settings and schedules deliberately with Kernel; quiescing has already changed them.

After uninstalling 3.x, there is no automatic rollback. Recovery requires the saved data and configuration, a confirmed package installation path and a recovery plan with Kernel. Reinstalling a package does not restore deleted records or their original IDs.

Send Kernel Support your Salesforce org ID, sandbox or production status, both package versions and namespaces, the failed step, exact error, job IDs and the time with timezone. Include count differences or example record IDs. Keep API keys and tokens out of support messages.

### Related guides

* [Package installation](https://docs.kernel.ai/integrations/salesforce-integration/package-installation-guide)
* [Set up Record Sync and schedules](https://docs.kernel.ai/integrations/salesforce-integration/record-sync-backfill-and-schedules)
* [Upgrade and preserve customisations](https://docs.kernel.ai/integrations/salesforce-integration/upgrade-and-preserve-customisations), for upgrades within the existing package

Last reviewed 14 October 2026.