This instruction guide applies to GRAX 3.30 and beyond.
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.
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.
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.
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 Adminpermission 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.
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
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.
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.
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.
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.
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 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.
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
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!
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.
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.
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.
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.
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.
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.
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.
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.
Updated 5 months ago