> For the complete documentation index, see [llms.txt](https://documentation.grax.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.grax.com/reuse-data/managed-package/migrating-from-first-generation-to-second-generation-managed-package.md).

# 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](https://documentation.grax.com/reuse-data/managed-package/first-generation) to the [Second Generation Managed Package](https://documentation.grax.com/reuse-data/managed-package/second-generation).

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

{% hint style="info" %}
**Important:** Both packages can coexist in your Salesforce org during the migration process, allowing you to minimize downtime for your users.
{% endhint %}

## 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](#document-current-first-generation-component-usage)
* [Install Second Generation Managed Package](#install-second-generation-managed-package)
* [Configure Second Generation settings](#configure-second-generation-settings)
* [Update page layouts with Second Generation components](#update-page-layouts-with-second-generation-components)
* [Verify Second Generation functionality](#verify-second-generation-functionality)
* [Uninstall First Generation Managed Package](#uninstall-first-generation-managed-package)

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

{% hint style="info" %}
This documentation will be your reference when adding Second Generation components later.
{% endhint %}

### 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):

* Use: <https://getgrax.co/prod-gen2>

**For Sandbox Orgs:**

* Use: <https://getgrax.co/sandbox-gen2>

For detailed installation information, see the [Second Generation Installation Guide](https://documentation.grax.com/reuse-data/managed-package/second-generation/install).

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

{% hint style="danger" %}
Ensure that there is no trailing slash in the `GRAX URL` field
{% endhint %}

#### 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](https://documentation.grax.com/reuse-data/managed-package/second-generation/features).

#### Update Each Page Layout

For each page layout documented in [this step](#document-current-first-generation-component-usage):

* 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`

{% hint style="danger" %}
Place GRAX components on a separate tab that is not loaded by default to improve page load times
{% endhint %}

* 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

{% hint style="danger" %}
Do not proceed to uninstall First Generation until Second Generation is fully verified.
{% endhint %}

### 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](https://documentation.grax.com/reuse-data/managed-package/first-generation/uninstall).

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:

* **Review Documentation:**
  * [Second Generation Managed Package Overview](https://documentation.grax.com/reuse-data/managed-package/second-generation)
  * [Second Generation Features](https://documentation.grax.com/reuse-data/managed-package/second-generation/features)
  * [Second Generation Installation Guide](https://documentation.grax.com/reuse-data/managed-package/second-generation/install)
  * [First Generation Uninstallation Guide](https://documentation.grax.com/reuse-data/managed-package/first-generation/uninstall)
  * [Managed Package FAQ](https://documentation.grax.com/reuse-data/managed-package/frequently-asked-questions)
* **Contact GRAX Support:**
  * Visit: <https://documentation.grax.com/support/get-support>
  * Email: <help@grax.com>
  * Support is available to assist with migration issues