# Connecting Salesforce

## Pre-Connection Considerations

Prior to connecting GRAX to Salesforce, let's review some important components of the connection process.

### GRAX Integration User

We require that you use dedicated Salesforce user and Permission Set for GRAX, rather than sharing a user and/or profile for GRAX and other integrations. This simplifies security, allows GRAX to automatically enforce and monitor permission problems, allows you to better audit issues, and maximizes concurrent API request limits that Salesforce imposes. GRAX uses this user for reading metadata and records for backup, deleting records for archives, and writing new records for restores. We refer to this user as the GRAX [Integration User](https://documentation.grax.com/other/permissions-and-access/integration-user).

### GRAX Auto Config

GRAX [Auto Config](https://documentation.grax.com/permissions-and-access/integration-user#auto-config) creates the `GRAX Integration user` permission set with the recommended configuration in Salesforce and assigns the permission set to the GRAX Integration User (the user you use to first connect the GRAX Application to your Salesforce org). This user is then used by GRAX to interact with Salesforce.

## Connecting a New GRAX Application to Salesforce

If you've just finished installing GRAX and it's reachable at `[your-grax-domain-and-port]/web`, you're all set to connect to Salesforce. You'll be greeted by this page:

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FRvbejDXgpvCeIO8pG1kE%2Fpre-auto-config.png?alt=media&#x26;token=a53783ef-20c0-43a0-b03f-169ab2a3c8a0" alt="" width="563"><figcaption><p>Initial Auto Config Page</p></figcaption></figure>

* From the dropdown menu, select `Production` or `Sandbox` based on the type of org you are trying to connect.

{% hint style="warning" %}
Some Developer/Einstein orgs are considered production orgs by Salesforce.
{% endhint %}

* Click the `Connect with Auto Config` button
* You'll be directed to Salesforce and prompted to sign-in. **Be sure to sign-in as the `GRAX Integration User`**
* Follow the Salesforce OAuth login flow as normal, remembering to use your org's custom domain if applicable

{% hint style="info" %}
Once connected, the integration user may be reviewed or updated within the `Settings` tab of your GRAX Application.
{% endhint %}

A successful connection attempt lands you back on `[your-grax-domain-and-port]/login`, which looks slightly different now. Log in with your **individual Salesforce user** to enter the GRAX Application via SSO.

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2Fctb7NHrEGhTyKBT6vt3m%2Fpost-auto-config.png?alt=media&#x26;token=c422d19f-9024-4319-b639-138b3ef06822" alt="" width="563"><figcaption><p>SSO Page for a Connected GRAX App</p></figcaption></figure>

## Changing or Moving Connections

If you've been using GRAX with a Salesforce org and would like to change the connected user or org, take the following steps:

* Click on the `Settings` tab
* Click on the `Salesforce` subtab
* Click `Update`

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2FrfYYPRMFy1Z8LMgusCaQ%2Fupdate-connection.png?alt=media&#x26;token=4d1b3de4-ad22-47da-a85b-00fcc94e757e" alt="" width="454"><figcaption><p>Replace the Current Salesforce Connection</p></figcaption></figure>

* Click the `Connect with Auto Config` button
* You'll be directed to Salesforce and prompted to sign-in. **Be sure to sign-in as the `GRAX Integration User`**
* Follow the Salesforce OAuth login flow as normal, remembering to use your org's custom domain if applicable

#### Resetting GRAX

Resetting GRAX completely disconnects the GRAX App from Salesforce. In this state:

* Data backup and job history are not available
* Users will be unable to access GRAX with Salesforce credentials until a Salesforce connection is restablished
  * Set up [local users](https://documentation.grax.com/other/settings/..#user-management) before resetting GRAX if access is needed

Resetting GRAX is usually done as part of a [Sandbox Refresh](https://documentation.grax.com/other/settings/sandbox-refresh). To reset the GRAX App:

1. Navigate to `Settings`
2. Expand the `Salesforce` panel
3. Click `Reset GRAX`

<figure><img src="https://4150568565-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwHKnqFEg4DROpG3KCq3D%2Fuploads%2F54ngAXgSy2iSmO7lcSNc%2Fdisconnect-salesforce-sandbox.png?alt=media&#x26;token=add45a96-d585-4c7d-b6f5-9a38dd5d1d72" alt="" width="454"><figcaption><p>Destroy the Current Salesforce Connection</p></figcaption></figure>

{% hint style="info" %}
Salesforce data backed up by GRAX is retained on the connected storage service after resetting GRAX. However, the data is not visible in GRAX without a connection to the source Salesforce org.
{% endhint %}

## What's Next?

If you're in the process of installing GRAX for the first time or need to otherwise (re)connect your longterm storage, see our [related documentation](https://documentation.grax.com/other/settings/connecting-storage).

## Frequently Asked Questions

#### Why is there an option to "Skip Auto Config"?

While GRAX Auto Config makes connecting to Salesforce more convenient by creating the `GRAX Integration user` permission set with the recommended configuration in Salesforce and assigning the permission set to the GRAX Integration User (the user you use to first connect the GRAX Application to your Salesforce org), some organizations may prefer to complete this setup manually. If your organization does not want to use the GRAX Auto Config functionality, choose `Skip Auto Config` when (re)connecting a new Salesforce org.


---

# 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/other/settings/connecting-salesforce.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.