> 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 managed package. Install it alongside 3.x, copy and check your data, update your customizations, then uninstall 3.x. The namespace separates Kernel's components from other Salesforce customizations 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 customization or provide an automatic rollback.

## Before you start

Agree on a maintenance window, a customer approver, and a recovery owner with Kernel. Confirm which copy and recovery controls your target package version includes. **Quiesce Now** stops selected activity inside Salesforce; it does not pause every customer automation or every write from Kernel. Agree how those writers will stay paused through the final checks, including after 3.x is removed.

Have the following ready:

* A Salesforce admin who can install and uninstall packages, manage scheduled jobs and custom metadata, and assign permission sets.
* A 4.x installation link for the target org. Use the migration offer in your Salesforce connection in Kernel if available, or request the link from your Kernel team. A normal package-update link is not a substitute for a migration. 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-job names, owners, scheduling-user timezones and frequencies, and permission assignments. Include unscheduled sync configurations and assignments to inactive users. 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 migration 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 managed **Admin** permission set to the admin carrying out the migration. In Salesforce, check that its API name is `Admin` and namespace is `kernel`, commonly written `kernel__Admin`. The unnamespaced **Kernel Admin (Standard Access)** helper is a different permission set and does not replace managed Admin or its credential access.
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.

Before opening Kernel Setup as an admin, review the users holding managed Kernel roles and the standard-access grants those roles require. Newer 4.x packages create or update matching **Standard Access** helper permission sets during that visit and assign them across eligible role holders. Check any reported failures or license restrictions.

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 class, namespace, owner, scheduling-user timezone, configuration names, and frequency. Keep this record even if the assistant also logs them.
3. In **Migration Assistant**, compare every listed scheduled job with your saved inventory, including jobs marked safe to stop. Resolve uncertain ownership before clicking **Quiesce Now**, because the action can stop jobs automatically.
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. Newer assistants discover scheduled and unscheduled configurations. If discovery fails, they fall back to default configurations and names found in scheduled jobs. Compare the copied set with your full backup.

Stopping a job removes its schedule. Newer assistants capture stopped `KernelSync_` schedules for recreation under 4.x after uninstall. This does not cover every job that quiescing can stop, so retain your independent inventory. Captured schedules retain their names and cron expressions, but not their original owner or timezone. Recreation uses the administrator who opens Setup. Plan that user and timezone before restoring schedules.

## 3. Copy settings, configuration, and data

1. Click **Copy Settings** explicitly. This carries the organization'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 check the final deployment result. Compare scheduled and unscheduled configurations against your backup. Resolve discovery failures and recreate any missing configuration with Kernel.
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.

A completed batch status alone does not prove that every record copied successfully. If a response is lost, check the job and its row-level results before retrying. Rerunning Account copy can update existing new records from legacy values, so review any later edits and keep writes paused before a retry.

## 4. Restore your customizations and access <a href="#id-4.-restore-your-customisations-and-access" id="id-4.-restore-your-customisations-and-access"></a>

The assistant does not recreate customer fields, reports, record pages, or automation. It also does not copy old application logs, audit history, or every related record. Back up and migrate any of these that your organization 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.
* If your assistant includes **Copy Permission Set Assignments**, review its plan and use it to add the matching new sets for active users and permission set groups. Resolve each reported failure and confirm effective access. Otherwise, assign the appropriate new packaged sets manually. Review inactive users separately. 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 connection** uses the current Salesforce user's credential access; permissions on a different integration user do not cover that session. Test an actual call from Salesforce to Kernel, such as search or feedback, under the intended user's permissions when Kernel confirms it is appropriate to do so. Verify Kernel's OAuth connection to Salesforce separately.

## 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.

### Reconcile skipped records and counts

The copy keeps one new Kernel Account per distinct linked Salesforce Account. Reconcile these populations separately:

| Population                                   | What to check                                                                                          |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| All old Kernel Accounts                      | Matches your backup before migration.                                                                  |
| Unlinked old records                         | No Salesforce Account link, so the normal Account copy skips them.                                     |
| Extra old records linked to the same Account | Only one new record is kept per Account. Check whether the skipped duplicates contain values you need. |
| Distinct linked Accounts                     | The population expected to receive new Kernel Accounts and links.                                      |
| Copied feedback                              | Reconcile copied, skipped, and failed rows separately from the Account counts.                         |

A difference between the old and new totals can reflect deliberately skipped records. It is not permission to discard them. Record whether each skipped population will be migrated separately, retained in an accessible archive, or intentionally retired with the customer's agreement. Do this before uninstalling the object that holds it. Older verification screens may combine these categories in a missing-record warning; ask Kernel to reconcile the underlying records.

### Check links, fields, and workflows

The built-in verification checks counts, link coverage, and four fields on a sample of up to 20 mirrors. It is not a full comparison of every field or customer customization. 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. Check automatic-record-creation filters against the saved original.
* Resolve missing Account backlinks. Read the reported Salesforce error, correct the underlying record or access problem, then use **Retry links** if your assistant offers it. Verify the links again.
* 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, customization, and connection checks are complete and the customer approver and Kernel agree the org is ready.

{% hint style="warning" %}
Plan restart controls before uninstalling. Once 3.x is gone, Kernel can detect that migration has ended and allow writes again. Enabled automatic record creation can also resume. Opening the new Kernel Setup as an admin can recreate captured sync schedules and resume package jobs. Delaying that Setup visit is not a complete pause.
{% endhint %}

1. Confirm the new API key is configured, your independent backups are complete, and skipped-data decisions are recorded. Confirm the maintenance restrictions that will stay in place through acceptance.
2. Resolve references that still depend on 3.x. Use **Check for References** if available, and review customer Flows, reports, pages, actions, and Apex. After replacement access is verified, use **Remove 3.x Permission Set Assignments** if available. Resolve skipped users, permission set groups, and inactive-user assignments. Salesforce can block uninstall while dependencies remain.
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. At the agreed restart time, open the new **Kernel Setup** as an admin. The package can resume enabled analytics, seed missing default configuration, and recreate captured sync schedules. Review any restoration failures.
6. Compare every stopped job with your saved inventory. Confirm the new class, owner, scheduling-user timezone, configuration, and cadence. Compare **Next Run** with the saved baseline before allowing the first run; the same cron expression can run at a different time under another user's timezone. Recreate missing jobs deliberately or record their agreed retirement. Include retention and other jobs outside the captured `KernelSync_` schedules.
7. Have Kernel verify the new schema and review the Salesforce inbound filters and enabled states against the baseline. Do not assume paused inbounds were re-enabled automatically.
8. Confirm a successful inbound update, call from Salesforce to Kernel, mapped writeback, and scheduled run with the expected data in the expected fields. Include your own deployment or regression checks where the migration affects them. Check **Recent Job Runs**, including record errors, after the next scheduled run. Record who verified each workflow and when before ending the maintenance window.

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 customizations](https://docs.kernel.ai/integrations/salesforce-integration/upgrade-and-preserve-customisations), for upgrades within the existing package.

Last reviewed November 16, 2026. Confirm the controls available in your installed build with Kernel before starting.
