Install

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.

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.

Start the Installation

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

Production Orgs

Sandbox 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).

https://getgrax.co/prod-gen2getgrax.co

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:

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.

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.

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

Permissions Model

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

• In Salesforce, go to Settings - Search for Installed Packages

• Locate the GRAX Lightning Web Components installed package

• Click View Components

• 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

• Scroll down to locate Profiles and click Manage Profiles

• Select the profiles you desire to have access to the GRAX LWC

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.

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

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

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

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.

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

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.

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.

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.

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

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.

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.

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.

Initial setup and verification is now complete. For more information about the package, checkout our feature, update, and uninstall guides.

Frequently Asked Questions

Why am I seeing an unable to connect error on the LWC?

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

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

Log back into Salesforce and the LWC will be able to be viewed.