# Install

{% hint style="warning" %}

#### GRAX Application Required

The GRAX Managed Package consists of Lightning Web Components that send traffic to a GRAX application server in order to function. Make sure you have a healthy GRAX app running with Backup enabled before setting up the Managed Package.
{% endhint %}

Installing and configuring the second-generation Managed Package for the first time is quick and easy. The steps below cover everything from choosing the right org to getting a component added to your first page layout. If you become stuck or encounter unexpected issues while following these steps, feel free to [contact our Support team](https://app.gitbook.com/s/Ujmw35eIn7K36mAY2dSt/get-support) for assistance.

{% stepper %}
{% step %}

### Choosing the Right Salesforce Org

The Managed Package needs to be installed into the same Salesforce org that the GRAX application you'll be using is connected to. Make sure you're using that org for this process.
{% endstep %}

{% step %}

### Log in to Salesforce

Log in to the chosen Salesforce org via your standard login process as a user with the permissions to install Managed Packages. The standard "System Admin" profile is sufficient.
{% endstep %}

{% step %}

### Start the Installation

Depending on the type of org you've chosen, open the relevant link below to start the install process.

{% tabs %}
{% tab title="Production Orgs" %}
Use this link for any Salesforce org that is considered a production org or which uses the `login.salesforce.com` login page (like Developer Edition orgs).

{% embed url="<https://getgrax.co/prod-gen2>" %}
{% endtab %}

{% tab title="Sandbox Orgs" %}
Use this link for any Salesforce org that is considered a sandbox or which uses the `test.salesforce.com`  login page.

{% embed url="<https://getgrax.co/sandbox-gen2>" %}
{% endtab %}
{% endtabs %}

Opening the correct link will cause a package installation menu to appear.

Salesforce allows packages to be installed for all or some of your users and will present you with a few options. These options determine which users are granted access to the components and classes that power the package features. These options, and their impact, break down as follows:

{% tabs %}
{% tab title="Install for Admins Only" %}
Specifies the following settings on the installing administrator’s profile and any profile with the `Customize Application` permission:

* Apex classes - enabled
* Custom LWC tab - enabled
* Custom Settings record - enabled
* Second Generation LWCs - enabled

After installation, if you have Enterprise, Performance, Unlimited, or Developer Edition, set the appropriate user and object permissions on custom profiles as needed
{% endtab %}

{% tab title="Install for All Users" %}
Specifies the following settings on all internal custom profiles:

* Apex classes - enabled
* Custom LWC tab - enabled
* Custom Settings record - enabled
* Second Generation LWCs - enabled
  {% endtab %}

{% tab title="Install for Specific Profiles" %}
Enables you to choose the usage access for all custom profiles in your organization. You can set each profile to have full access or no access for the new package and all its components.

* Full Access
  * Apex classes - enabled
  * Custom LWC tab - enabled
  * Custom Settings record - enabled
  * Second Generation LWCs - enabled
* No Access&#x20;
  * Apex classes - disabled
  * Custom LWC tab - disabled
  * Custom Settings record - disabled
  * Second Generation LWCs - disabled
    {% endtab %}
    {% endtabs %}

Select the group you would like to install the package for and click "Install."

Please note that only power and admin users can see and use the restore button on the LWC.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F4fWbm5j3Fx2JtdfPXlwj%2FScreenshot%202025-11-10%20at%2011.22.17%E2%80%AFAM.png?alt=media&#x26;token=e4cad27a-91bb-4d1b-a69e-e9711944dd87" alt=""><figcaption><p>Installing for All Users</p></figcaption></figure>

Installation should take less than a minute in an average org, but may take longer if you have a very large or very customized org. During the wait, you will see a loading indicator.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FdRhZ5LO2slBD880IBmw2%2FScreenshot%202025-11-10%20at%2011.35.52%E2%80%AFAM.png?alt=media&#x26;token=4adee668-23cd-4b02-984b-194f99c41023" alt=""><figcaption><p>Waiting/Loading Message</p></figcaption></figure>

Once the installation is completed, a success message will show and you will receive a confirmation email.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FmpispBY9zRLuPDmDrfVS%2FScreenshot%202025-04-10%20at%202.09.31%E2%80%AFPM.png?alt=media&#x26;token=05dc7ba3-a06c-48a2-9774-0a015ea43403" alt=""><figcaption><p>Success Message</p></figcaption></figure>

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F9UvQLeCPMtem3DQw42DO%2FScreenshot%202025-04-10%20at%202.12.33%E2%80%AFPM.png?alt=media&#x26;token=7a5aed1b-9189-4caa-b116-d1439cddd184" alt=""><figcaption><p>Confirmation Email</p></figcaption></figure>

### Permissions Model <a href="#permissions-model" id="permissions-model"></a>

{% hint style="warning" %}
If the managed package was initially installed for Admins only, and access later needs to be granted to other profiles, certain components must be manually assigned to the appropriate user profiles in Salesforce.
{% endhint %}

The components included in the Managed Package are secured by the same permissions model that the normal GRAX application interface uses. To use the components, users must have one of the following permission sets:

* GRAX Console Standard Permission
* GRAX Console Seeding Permission
* GRAX Console Purge Permission
* GRAX Console Power Permission
* GRAX Console Admin Permission

These permission sets are created by Auto Config when you connect your GRAX app for the first time.

Users will also need to self-authorize the GRAX connected app by opening the GRAX application in a separate tab the first time they log in. This can be avoided by an admin pre-authorizing the users via the Manage Connected App settings.

#### Configure Permissions for Additional Users&#x20;

* In Salesforce, go to `Settings` - Search for Installed Packages
* Locate the GRAX Lightning Web Components installed package
* Click `View Components`&#x20;
* Click on the **`Versions`** Apex Class - click the `Security` button and add the user profiles as needed
* Repeat these steps for the **`CustomSettings`** Apex Class
* Additionally, assign the GRAX Search Tab to the desired Salesforce user apps.

OR alternatively,

* In Salesforce, go to `Settings` - Search for Manage Connected Apps
* Locate and Edit GRAX Oauth
* Adjust Permitted users to 'Admin approved users are pre-authorized'
* Click Save&#x20;
* Scroll down to locate Profiles and click Manage Profiles
* Select the profiles you desire to have access to the GRAX LWC
  {% endstep %}

{% step %}

### Configure Custom Settings

The components included in the package source the target server URL from a Custom Setting. Installing the package creates this custom setting, but it is empty by default. You will need to set an organization-default value for the setting before anyone can use the components.

Start by opening the custom settings menu.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FYJ9oetYD3GbYQTYIKtgx%2FScreenshot%202025-04-10%20at%202.24.43%E2%80%AFPM.png?alt=media&#x26;token=2620fb2d-97b2-43ea-9d22-55dbe0a5f68d" alt=""><figcaption></figcaption></figure>

Find the "GRAX Settings" item in the list and click "Manage."

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FnU6PnrqzGigo58FcRlmn%2FScreenshot%202025-04-10%20at%202.27.50%E2%80%AFPM.png?alt=media&#x26;token=bd1f6d61-85f8-4a73-a82c-2b532289cb69" alt=""><figcaption></figcaption></figure>

Click "New" to create a new organization-level default setting.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F5xiSbDREnjrdEHt2s1OP%2FScreenshot%202025-04-10%20at%202.28.54%E2%80%AFPM.png?alt=media&#x26;token=22bc3ca8-454a-4733-a323-5da69a9232d9" alt=""><figcaption></figcaption></figure>

Enter the full `https://[...].com`  formatted public domain name of your GRAX application without a trailing slash and click "Save."

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FS5sT2MFed3l7mpT74tEK%2FScreenshot%202025-04-10%20at%202.31.22%E2%80%AFPM.png?alt=media&#x26;token=5df62da4-007b-488e-9341-a99e5694db15" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Configure a Trusted URL (Application)

The components included in the package are iframed pages retrieved from your GRAX application server. Due to browser security restrictions, additional configuration is necessary to tell Salesforce that you trust the GRAX server to serve iframe content in your org.

To start, open the "Trusted URLs" menu.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FO2NNKVDePsV51OVCZhWa%2FScreenshot%202025-04-10%20at%202.34.15%E2%80%AFPM.png?alt=media&#x26;token=ebb11cb2-17a6-4531-8e62-cfdf1f8b5b3e" alt=""><figcaption></figcaption></figure>

To add a new Trusted URL for your GRAX application, click "New Trusted URL."

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F8pu20WJkZFY5NyCKuumd%2FScreenshot%202025-04-10%20at%202.35.41%E2%80%AFPM.png?alt=media&#x26;token=469c86bd-d4dd-4474-93a2-3fe6f0c326ed" alt=""><figcaption></figcaption></figure>

Make the following changes to the "New Trusted URL" form:

* Name it anything you'd like
* Use the same `https://[...].com`  formatted domain name as used in the Custom Setting as the URL
* Check the `frame-src`  box
* Leave the `img-src`  box checked

Now click "Save" to create the record.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FFinnkn1B2VPDQXmPCGqj%2FScreenshot%202025-04-10%20at%202.38.21%E2%80%AFPM.png?alt=media&#x26;token=933ce090-ecbe-4059-861c-ca1752d30823" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

### Configure Another Trusted URL (HQ)

Due to enhanced default Content Security Policy settings in recent Salesforce releases, it's necessary to also flag GRAX's centralized authentication server as trusted. Repeat the steps above to create another Trusted URL, but make the following modifications to the form:

* Name it anything you'd like
* Use `https://hq.grax.com`  as the URL
* Check the `frame-src`  box
* Leave the `img-src`  box checked

Now click "Save" to create the record.
{% endstep %}

{% step %}

### Add a Component to a Page Layout

To see a component in action and test it out, you'll need to modify a page layout for a standard object. Start by opening a standard object record (Case, for example) page in your Salesforce org and then opening the "Setup" sidebar. Click the "Edit \[Object] Page" option under "Customization" to open the Lightning App Builder.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FAgU4yFFmtpqY1Z3tp0zF%2FScreenshot%202025-04-10%20at%203.08.11%E2%80%AFPM.png?alt=media&#x26;token=a288c832-e0da-4557-be1d-f43411391bcb" alt=""><figcaption></figcaption></figure>

Within the Lightning App Builder, the record-page-compatible GRAX components will be available under the "Custom - Managed" category in the components list.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F2Lqret16AggVvR1JX7DN%2FScreenshot%202025-04-10%20at%203.12.46%E2%80%AFPM.png?alt=media&#x26;token=29bc31b9-4862-425b-aeeb-db0cb1baa2d4" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
It is recommended to place GRAX components on a separate tab that is not loaded by default when a user opens the record page. This improves the load time of the page in common use cases and minimizes unnecessary traffic to and from your GRAX application.
{% endhint %}

For purposes of initial testing, we'll use the Related Records component. To add a component to the page, create a new tab and drag the GRAX component onto it from the "components" menu. Initially, some components (like Related Records) may have invalid configurations because they need additional setup to behave properly.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FWuLc8Nptow4Um8uKR6JT%2FScreenshot%202025-04-10%20at%203.16.36%E2%80%AFPM.png?alt=media&#x26;token=ccc303a1-b0bc-47c4-9dd7-5ef034a79441" alt=""><figcaption></figcaption></figure>

Add the API name of any object directly related to the parent object (whatever object's record page you're modifying) to the component's input settings and save the layout.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FV6ACj2IHsIj9SNwzlAd8%2FScreenshot%202025-04-10%20at%203.24.02%E2%80%AFPM.png?alt=media&#x26;token=f4e37fc2-e00e-4ab9-91f4-276add5dc855" alt=""><figcaption></figcaption></figure>

The component should now render with data based on your backed up data. Depending on exactly which objects you chose, the exact format of the component may vary. A few examples of the Related Records component are shown below for reference.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F2t8CAfRc07Sf1058sSXZ%2FScreenshot%202025-04-10%20at%204.02.57%E2%80%AFPM.png?alt=media&#x26;token=c0a68bf9-de62-463e-920e-99bcf058cc32" alt=""><figcaption></figcaption></figure>

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FPnx7p8jnt1QwVs1BVWjs%2Fcase-comments.png?alt=media&#x26;token=b2016e26-48af-4c5d-a353-c208e10a48d7" alt=""><figcaption></figcaption></figure>

Initial setup and verification is now complete. For more information about the package, checkout our [feature](https://documentation.grax.com/reuse-data/managed-package/second-generation/features), [update](https://documentation.grax.com/reuse-data/managed-package/second-generation/update), and [uninstall](https://documentation.grax.com/reuse-data/managed-package/second-generation/uninstall) guides.
{% endstep %}

{% step %}

### Frequently Asked Questions&#x20;

#### Why am I seeing an unable to connect error on the LWC?&#x20;

If the integration user and power users or admin users are seeing this message then the required permission sets are not created.&#x20;

To resolve this, log out of both GRAX and Salesforce. Log into GRAX via the SSO option to self-authorize.&#x20;

Log back into Salesforce and the LWC will be able to be viewed.&#x20;

{% endstep %}
{% endstepper %}