TrustAPI Docs

Migrating from First Generation to Second Generation Managed Package

Overview

This guide provides step-by-step instructions for migrating from the soon to be deprecated First Generation Managed Package to the Second Generation Managed Package.

The Second Generation package offers:

  • Reduced custom code in your org

  • Elimination of secrets stored within Salesforce

  • Faster implementation and easier maintenance

  • New Lightning Web Components including Global Search

  • Leverages modern Salesforce packaging tools

Important: Both packages can coexist in your Salesforce org during the migration process, allowing you to minimize downtime for your users.

Prerequisites

The following are required before beginning this migration:

  • GRAX Application: Ensure you have a healthy GRAX application running with Backup enabled

  • Salesforce Permissions: You need permissions to install/uninstall Managed Packages (System Admin profile is sufficient)

  • Testing Environment: We strongly recommend testing this migration in a sandbox org before executing in production

Migration Process Overview

Document Current First Generation Component Usage

Before making any changes, document where First Generation components are currently deployed.

  1. Open Setup in Salesforce

  2. Use Quick Find to navigate to Lightning App Builder

  3. For each page that contains GRAX components:

    • Note the object type (e.g., Case, Account, Contact)

    • Document which GRAX components are present

    • Record any custom configuration settings for each component

    • Take screenshots if helpful

This documentation will be your reference when adding Second Generation components later.

Install Second Generation Managed Package

The Second Generation package can be installed while First Generation is still running, preventing downtime for your users.

Choose the Correct Installation Link

For Production Orgs (including Developer Edition):

For Sandbox Orgs:

For detailed installation information, see the Second Generation Installation Guide.

Install the Package

  1. Log in to your Salesforce org as a System Administrator

  2. Open the appropriate installation link above

  3. On the package installation screen, select Install for All Users (recommended) or Install for Admins Only

    • Install for All Users: Enables all internal users to access Second Generation components immediately

    • Install for Admins Only: Requires manual permission assignment later for non-admin users

  4. Click Install

  5. Wait for the installation to complete (typically less than one minute)

  6. You will receive a confirmation email when installation succeeds

If you installed for Admins Only and later need to grant access to other profiles:

  1. Go to Setup > Installed Packages

  2. Locate GRAX Lightning Web Components

  3. Click View Components

  4. For each component (Versions Apex Class, CustomSettings Apex Class):

    • Click Security

    • Add the required user profiles

  5. Assign the GRAX Search Tab to desired Salesforce user apps

Configure Second Generation Settings

The Second Generation package requires configuration before components will function.

Configure Custom Settings

  • In Setup, use Quick Find to search for Custom Settings

  • Find GRAX Settings and click Manage

  • Click New to create an organization-level default setting

  • In the GRAX URL field, enter your GRAX application URL:

    • Format: https://[your-grax-domain].com

    • Click Save

Ensure that there is no trailing slash in the GRAX URL field

Configure Trusted URL for GRAX Application

  • In Setup, use Quick Find to search for Trusted URLs

  • Click New Trusted URL

  • Configure the following:

    • API Name: GRAX_Application (or any name you prefer)

    • URL: Your GRAX application URL (same as Custom Settings, e.g., https://mycompany.grax.io)

    • Check: frame-src

    • Leave checked: img-src

  • Click Save

Configure Trusted URL for GRAX HQ

  • Still in Trusted URLs, click New Trusted URL again

  • Configure the following:

    • API Name: GRAX_HQ (or any name you prefer)

    • URL: https://hq.grax.com

    • Check: frame-src

    • Leave checked: img-src

  • Click Save

Update Page Layouts with Second Generation Components

Now that Second Generation is installed and configured, update your page layouts to use the new components.

Understanding Component Differences

Second Generation includes three components:

  • Related Records: View related records (live, deleted, or archived)

  • Record Versions: Explore single-record history and restore data

  • Global Search: Search for data within GRAX using filters and conditions

For detailed information about each component, see the Second Generation Features Guide.

Update Each Page Layout

For each page layout documented in this step:

  • Navigate to the object record page in Salesforce

  • Open the Setup sidebar (gear icon)

  • Click Edit [Object] Page under Customization

  • In the Lightning App Builder, find Second Generation components under Custom - Managed

Place GRAX components on a separate tab that is not loaded by default to improve page load times

  • Drag the appropriate Second Generation component onto the page

  • Configure the component settings

Related Records Component Settings

  • Related Object: API name of the object type to display

  • Dataset Selection: Choose All, Archived, Deleted, or Archived or Deleted

  • Child Level: Hierarchy level (1 = immediate children, 2 = grandchildren, etc.)

  • Fields: Comma-separated list of Field API names to display

  • Records Per Page: Number of records per page

  • Override Title: (Optional) Custom title

  • Height: Component height

  • Additional Configuration: (Optional) Advanced settings

Record Versions Component Settings

  • Records Per Page: Number of versions per page

  • Override Title: (Optional) Custom title

  • Height: Component height

  • Click Save to save the page layout

  • Repeat for all page layouts that need GRAX components

Optional: Add Global Search Tab

The Global Search component can be added as a standalone Custom Tab:

  • The GRAX Search Tab is automatically included with the Second Generation package

  • Add it to relevant Salesforce apps via App Manager

  • Configure search behavior via Custom Settings if needed:

    • Search Tab: Template Search: Enable for template-based search

    • Search Tab: Show Template ID: Specify a template ID to display

Verify Second Generation Functionality

Before uninstalling First Generation, verify that Second Generation components work correctly.

Verification Checklist

  • Test Component Access:

    • Log in as different user types (admin, standard user, etc.)

    • Navigate to pages with Second Generation components

    • Verify users can see the components based on their permissions

  • Test Component Functionality:

    • Verify components load GRAX content correctly

    • Test Related Records component: confirm it displays related records

    • Test Record Versions component: confirm it shows record history

    • If applicable, test Global Search: run a search and verify results

  • Test Permissions:

    • Confirm users with GRAX Console permissions can access components

    • Users should have one of these permission sets:

      • GRAX Console Standard Permission

      • GRAX Console Seeding Permission

      • GRAX Console Purge Permission

      • GRAX Console Power Permission

      • GRAX Console Admin Permission

  • First-Time User Authorization:

    • Users must self-authorize the GRAX Connected App on first use

    • Have users open the GRAX application in a separate tab to complete authorization

    • Alternatively, admins can pre-authorize users via Connected App settings

  • Document Any Issues:

    • Note any components that don't load correctly

    • Record any error messages

    • Contact support if you encounter unexpected behavior

Do not proceed to uninstall First Generation until Second Generation is fully verified.

Uninstall First Generation Managed Package

Once Second Generation is verified and working, you can safely remove First Generation.

Prepare for Uninstallation

  1. Notify Users: Inform users that First Generation components will be temporarily unavailable during uninstallation

  2. Remove First Generation Components from Page Layouts:

    • Edit each page layout that has First Generation components

    • Remove the First Generation GRAX components

    • Save the page layouts

  3. Remove Permission Set Assignments:

    • In Setup, navigate to Permission Sets

    • Find permission sets that start with GRAX -

    • Remove these permission sets from all users

Uninstall the Package

For detailed uninstallation information, see the First Generation Uninstallation Guide.

  1. In Setup, use Quick Find to search for Installed Packages

  2. Find GRAX (First Generation) in the packages list

  3. Click Uninstall

  4. Check the confirmation checkbox

  5. Click Uninstall

Handle Uninstall Errors

On the first attempt, you may receive errors about components still being used. Common issues include:

Users still assigned permission sets:

  • Remove package permission sets (those starting with GRAX -) from all users

Lightning Web Components still present in page layouts:

  • Remove First Generation components from all page layouts

Apex classes still referenced in Scheduled Jobs:

  • Navigate to Setup > Apex Jobs > Scheduled Jobs

  • Delete any jobs named GRAXScheduledWorker

Retry Uninstallation

  • After resolving reported issues, repeat the uninstallation steps

  • Continue resolving issues and retrying until uninstallation succeeds

  • You will receive a confirmation email when uninstallation is complete

Troubleshooting

Second Generation Components Not Loading

Issue: Components show blank or display errors

Solutions:

  • Verify Custom Settings contain the correct GRAX application URL

  • Verify both Trusted URLs are configured correctly

  • Check that users have appropriate GRAX Console permission sets

  • Confirm users have authorized the GRAX Connected App

  • Verify the GRAX application is running and healthy

Users Cannot See Second Generation Components

Issue: Components are not visible to certain users

Solutions:

  • If package was installed for Admins Only, manually assign component access to user profiles

  • Verify users have GRAX Console permission sets assigned

  • Check that the GRAX Search Tab is added to the user's Salesforce app

First Generation Uninstall Fails Repeatedly

Issue: Uninstallation continues to fail after resolving reported issues

Solutions:

  • Check for custom code, workflows, or process builders that reference GRAX objects or classes

  • Look for validation rules that reference GRAX fields

  • Review all page layouts thoroughly for remaining First Generation components

  • Contact GRAX Support for assistance

Getting Help

If you encounter issues during migration or have questions not covered in this guide:

Last updated

Was this helpful?