# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.grax.com/reuse-data/managed-package/migrating-from-first-generation-to-second-generation-managed-package.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.