Upgrade and preserve customisations

Preserve customer permissions, record pages, custom fields, mappings and schedules when upgrading the Kernel Salesforce package.

Upgrade the Kernel Salesforce package to receive new features and fixes. Before you start, record the configuration your team depends on and check which parts belong to the package.

Kernel uses an unlocked Salesforce package. Installing a new version can overwrite changes made directly to packaged metadata, including permission sets and pages. Keep your organisation's extra permissions and page customisations in components you own.

Customer-created fields on Kernel Account are separate from fields supplied by the package. Record their API names, data types, lengths and permissions before upgrading, then check that the fields and mappings still work afterwards. Do not delete and recreate a field because its label or page position changed.

Prerequisites

• Salesforce administrator access to the target org.

• The installed Kernel SF Connected App version from Setup → Installed Packages.

• The target package version and install link from your Salesforce integration in the Kernel web app.

• A record of the integration user's permissions and your current layouts, mappings, and schedules.

Review the release notes for every version between your installed version and the target version. If your org has custom Account automation, permission sets, or record pages, test the upgrade in a sandbox before production.

Record the current setup

Use this list for the before-and-after comparison.

Area	Record before upgrading
Package	Installed version, target version, and target Salesforce org.
Connection	Integration-user username, active status, and connection status. Do not include API keys or tokens in the review.
Permissions	Profile, permission-set and group assignments, and the saved Kernel permission policy. Include object, field, Apex, app, tab, credential, and system access.
Record pages	Page layouts and Lightning record pages used for Account and Kernel Account, their assignments, and customer changes to fields, actions, and related lists.
Field mappings	Source and destination object, each field's API name, direction, filters, and enabled configuration.
Schedules	Frequency, selected configurations, next expected run, and recent result. Record Kernel web-app refresh settings separately from schedules inside Salesforce.

Compare fields by object and API name. A changed label is not evidence that a field was deleted or that its API name changed.

Preserve extra permissions

If your team has edited a packaged Kernel permission set, compare its current definition with the package version you plan to install.

1. Save the current definition and its assignments.

2. Identify the grants your organisation added or changed. Review object and field access as well as system permissions, Apex classes, apps, tabs, and credential access.

3. Put the additional permissions you still need into a customer-owned permission set.

4. Assign that set to the relevant users and test the affected workflows in your sandbox.

5. If you are replacing a broader packaged set, review the profile and all other assignments before removing access. Also confirm the saved Kernel permission policy.

A copy of the current permissions gives you a reference. You still need to compare it with the target package and decide which differences to keep. Salesforce combines grants from every permission source, so adding a narrower set does not reduce existing access.

See the Salesforce Integration User Permission Matrix for workflow requirements.

Preserve page customisations

Salesforce page layouts and Lightning record pages control different parts of the record experience. Review both on Account and Kernel Account.

• A page layout controls fields, related lists, and the actions made available by that layout.

• A Lightning record page controls the components shown on the page and where that page is activated.

Use a customer-owned copy when you need to customise a packaged page or layout. Record its assignments so you can check the experience for each relevant app, profile, and record type after upgrading.

A customer-owned copy also needs maintenance. After an upgrade, review whether it should include new Kernel actions, fields, or components. For example, adding Send Kernel Feedback to a standard Account requires the layout steps in the feedback guide.

Review sync configuration

Version 3.10.6 introduced preservation of customer changes to standard sync configurations during package upgrades. Continue to record and check those configurations when upgrading, especially when your starting version is earlier than 3.10.6. If you have both sync directions enabled, check each configuration separately. A reverse-sync mapping can write values back to Account.

Check mappings by source object, destination object, and field API name. Review both directions if you sync between Account and Kernel Account. The preservation of sync configuration does not mean that direct edits to every packaged component are preserved.

Install the upgrade

1. In Salesforce, open Setup → Installed Packages and confirm the installed Kernel SF Connected App version.

2. In the Kernel web app, open the Salesforce integration for the org you intend to upgrade and select its package install link.

3. Confirm the Salesforce org and target package version on the installation screen.

4. Choose Install for All Users so the packaged forms and components are available to end users.

5. Complete the upgrade and wait for Install Complete.

6. Return to Setup → Installed Packages and confirm the installed version.

7. Open Kernel Setup and check the selected integration user and connection status. Complete any setup or authorization prompts.

8. Complete the checks below before your team resumes normal use.

Keep your saved configuration until you have checked the connection and a successful sync after the upgrade.

Check the result

1. Confirm that the integration user is active, the expected permission sets remain assigned, and the connection is working.

2. Compare permission definitions and assignments with your saved copy. Confirm that customer-owned extensions still provide the required access.

3. Open an Account and a Kernel Account as the intended users. Check fields, actions, related lists, record-page activation, and any page-layout assignments your team uses.

4. Check the source and destination of each active mapping. Test one known account and confirm the expected value on the correct Salesforce object and field.

5. Check schedule status, the next expected run, and the result of the next scheduled run. Confirm that each schedule uses the intended configurations. A "next scheduled" time alone does not confirm that a job has run successfully.

6. Test the features your team uses with their actual roles. Include search and creation, enrichment, and feedback where enabled. Validate merge and hierarchy workflows in your sandbox with representative related records.

In version 3.13.0, recent sync runs are available in Sync Schedules inside Salesforce. Use Troubleshoot sync when a run fails, does not start, or finishes with record errors.

If something changed or the upgrade failed

Keep the exact error text and the name of the affected component. If a field disappeared from a page, check its object, API name, permissions, and page assignment before changing mappings or recreating the field.

For an installation failure, contact Kernel Support with:

• Salesforce org ID and whether it is a sandbox or production org.

• Installed and target package versions.

• The full installation error and any named Apex class or component.

• The time of the attempt, including timezone.

For a problem after installation, add the affected workflow, user's role, record or sync-job ID, and the before-and-after difference. Keep credentials out of screenshots and support messages.