Configuration

Let's take a look at the steps to get GRAX set up and running.

❗️

This instruction guide applies to GRAX 3.30 and beyond.

Introduction

This guide will take you through a GRAX install and setup, which can be done entirely from your Salesforce UI, with simple clicks. It will provide instructions for getting your heroku app provisioned, connecting to Salesforce, and entering the key credentials for your storage environment(s).

We will also take a look at customers who are upgrading to 3.30 and beyond, and how you can ensure a smooth transition to the new GRAX configuration interface that Admins will find within Salesforce.

1-to-1 Salesforce-GRAX Connection

GRAX currently supports only a 1-to-1 connection between the GRAX app and SFDC org. You cannot link multiple SFDC orgs to a single GRAX app, as each GRAX app's configuration can only house a single SFDC 'source' org. This 1-to-1 SFDC org to GRAX app structure will keep things segregated and simpler to set up, upgrade, and maintain as each Salesforce environment can be managed separately based on its requirements.

There are also validations within the new configuration interface that will strictly enforce this 1-to-1 connection. For instance:

  • The SFDC Org that you are navigated and going through these configuration steps within must be the same SFDC Org that you use when entering relevant credential information during Setup.
  • If you install the GRAX SFDC package in a SFDC environment and connect it to an existing Heroku app that already was tied to a different SFDC org, you will see validation errors. If you want to set up GRAX in a new SFDC environment, always use a new GRAX app.

Step 1: Install GRAX Salesforce Package

Get started by installing the GRAX Salesforce managed package. You can reach out to GRAX Support in order to obtain the proper installation link. Please refer to Salesforce Installation for details.

Step 2: Assign Salesforce Permission Set

The first step is to ensure the Salesforce user that will be conducting the setup (managing sensitive credentials etc) has the proper permission set. We recommend assigning this person all GRAX permission sets, but at the very least the base GRAX - Admin permission set along with the add-on GRAX - Configuration Admin permission set is required to see the Configuration tab in the GRAX Salesforce app and go through the setup steps.

🚧

API Access Required

The Salesforce user who has the GRAX - Configuration Admin permission set will also need Salesforce API access. You can assign this per your company's standard Salesforce profile and permission set model, as Salesforce API access is NOT included as part of the GRAX permission sets.

Step 3: Connect

Once you now have the permission set, you can click on the GRAX tab. You will see now be able to complete these basic items on the Connect subtab:

Once you have the proper permissions, let's get started!

There are two options available to you here, one will still support customers who are running with GRAX deployed onto the Heroku platform and another that is for customers who have GRAX running on AWS. This could be either GRAX Managed or the GRAX Virtual Appliance.

Heroku Setup

🚧

Legacy Setup!

GRAX on Heroku is a legacy setup. This is still supported but if you are a new customer you are probably going to be need to setup using the AWS flow.

Click the Authorize button in order to authorize against your Heroku account. If you are already logged into your Heroku account in your browser you should not need to sign in; otherwise you will be prompted to sign into Heroku. Once you have authorized you can now move on to create a new GRAX Heroku app within this account.

We've authorized against our desired Heroku Account, and can now proceed to the next step.

Create New GRAX App

Click the Create New GRAX App button, which will redirect you to Heroku in order to create your GRAX Heroku application. Fill out the required fields and click Deploy app. Once your Heroku App is deployed, you can navigate back to Salesforce.

🚧

Private Space

Ensure you have your Heroku Private Space created BEFORE you create this app, as you will need to choose which Private Space the app belongs in during this step. Be sure to set up your trusted connection in the private space as well, if you haven't already.

Once you fill out the details of your Heroku app and click Deploy app, you can go back into Salesforce.

Connect To Selected Heroku App

Once you have created your Heroku app in the prior step, you can go back to Salesforce (refresh if needed), and select the relevant Heroku App in the dropdown on the Connect tab. Select the Heroku App you just created in order to bind this Salesforce environment to the Heroku application, and then click Save to proceed.

We've connected Salesforce to the newly created Heroku app. Click Save and continue.

You'll notice the prompt to create a remote site setting.

AWS Setup

When you first open GRAX you will see the Configuration tab. Go ahead and type (or select) "AWS" into the "Cloud Platform Server" search box. The values here for tokens and App URL you should have either from your GRAX Support Engineer or from the setup of your own Virtual Appliance Setup

Create Remote Site Setting

After saving, you will now be prompted to create a remote site setting. You can use the button provided, which will open a new tab, that has the remote site setting details prepopulated. Just save the remote site setting.

Go back to your Salesforce Configuration tab refresh, once you have created the remote site setting. This should now reveal the Setup subtab, and show a banner directing you to complete the Setup tab. Let's proceed!

Step 4: Setup

You've completed the Connect steps, and that will open up the Setup subtab for final setup of credentials.

Get Started

When you click on the Setup subtab for the first time, you'll be instructed to get started. All you need to do is fill out the credentials for Salesforce, then you're ready to go. If you are bringing your own Object Storage (S3, GCP or Azure) then have these credentials with you as well.
If you are using the Object Store created with the deployment of the GRAX Virtual Appliance, then you just simply need your GRAX Integration User credentials.

🚧

This isn't YOUR Salesforce Credentials

You probably want to have a dedicated user in Salesforce for GRAX to use, so these are the credentials you will want to enter here in the Setup.

Update Credentials

This page will walk you through entering proper credentials and information for each layer. You will not be able to save the page unless GRAX can validate the connection to each provider (Salesforce, Elastic, and Storage) upon save. You can also use the Validate buttons in each section to manually validate individual connections before saving.

Enter all the information, and feel free to Validate each connection manually. The connections will all be validated upon Save as well.

❗️

Click Link to Validate and Start Using GRAX

Once you save your initial configuration, click the link in the red alert banner to verify and reload the page, which will expose the rest of the GRAX tabs, in order for you to start your first backup and begin your journey with GRAX!

📘

How GRAX Validates the Connections

For Salesforce, non-Bonsai Elasticsearch providers, and Storage, GRAX will essentially attempt to sign in as the user.

For Bonsai, GRAX uses a simple ping to validate whether a request to the provided URL hits a server.

Setup Summary Page

Once you save and have a valid configuration, now when you visit the Setup subtab you will see a summary of your required configuration as well as the option to edit advanced configuration.

This is how your Setup subtab will look going forward, now that you have a valid configuration.

Advanced Configuration

While the Required Configuration you already filled out is all you need to get started, you may want to use Advanced Configuration to explore some other GRAX features, such as Metadata Backup.

The Advanced Configuration simply allows you to specify credentials and settings for these features; to actually execute relevant processes, please see the detailed guides.

❗️

Recommended Fields

You'll notice a red star next to certain fields. GRAX will not prevent saving the advanced page, but we have provided red stars to indicate the recommended fields to populate, depending on which feature you would like to enable.

Step 5: Finish

The final step will be to activate scheduled jobs. The yellow alert will indicate that you need to go to the Miscellaneous subtab and activate scheduled jobs. This creates Salesforce scheduled jobs behind the scenes using the running user.

Be sure to activate the scheduled jobs as the proper user, based on permissions.

Upgrading to New Configuration Interface

As an existing customer, you may want to take advantage of this new configuration interface and the ease it provides for managing and updating your GRAX settings.

If you would like to upgrade to GRAX 3.30 or later, and use the new configuration interface as outlined in this guide, please reach out to GRAX Support.

Video Walkthrough