Integration User

The integration user is defined within the Settings tab of your GRAX application. GRAX will utilize this user for reading metadata and records for backup, deleting records for archives, and writing new records for restores.

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.

For general Salesforce best practices on creating integration users, see the Permission Sets example here.

Required Permissions

These permissions are required for the complete and healthy operation of the GRAX application. They should be assigned via a Permission Set named GRAX_Integration_User.

PermissionComments
API EnabledRequired for login and general API access to read, write and delete data
View All DataEnsures access to read most objects, records and fields in the org for backup. See Field Level Security below to audit and grant access to all data.
Modify All DataEnsures access to delete most objects and records for archive, and to write most objects and records for restore
Query All FilesEnsures access to read all files for backup
Set Audit Fields Upon Record CreationEnsures original audit field values can be written for restore

NOTE: To grant the "Set Audit Fields upon Record Creation" permission, you must first enable it at the organization level under the "User Interface" menu within Setup. Look for the two-in-one option labeled "Enable 'Set Audit Fields upon Record Creation' and 'Update Records with Inactive Owners' User Permissions". See the Enable the 'Create Audit Fields' permission guide.

The following script can be used to create a GRAX_Integration_User Permission Set using the Salesforce Developer Console:

  1. Open the Salesforce Developer Console

  2. Click the Debug menu

  3. Click the Open Execute Anonymous Window menu option (or press CTRL + E)

  4. Paste the following script into the Enter Apex Code window:

    PermissionSet piu = new PermissionSet(
        Name = 'GRAX_Integration_User',
        Label = 'GRAX INTEGRATION USER Permission',
        Description='Permission set for the GRAX INTEGRATION USER',
        PermissionsViewAllData=true,
        PermissionsModifyAllData=true,
        PermissionsQueryAllFiles=true,
        PermissionsCreateAuditFields=true
    );
    
    DescribeSobjectResult permissionSetDescribe = Schema.PermissionSet.SObjectType.getDescribe();
    Map<String, SObjectField> fieldMap = permissionSetDescribe.fields.getMap();
    List<String> availablePermissions = new List<String>();
    
    for (String fieldName : fieldMap.keySet()) {
        if (!fieldName.startsWithIgnoreCase('Permissions')) {
            continue;
        }
        if (fieldName == 'PermissionsViewAllData' ||
            fieldName == 'PermissionsModifyAllData' ||
            fieldName == 'PermissionsQueryAllFiles' ||
            fieldName == 'PermissionsCreateAuditFields') {
                continue;
        }
        DescribeFieldResult fd = fieldMap.get(fieldName).getDescribe();
        if (fd.isCreateable() && fd.isUpdateable()) {
            availablePermissions.add(fieldName);
        }
    }
    Integer count = 1;
    
    while (count < 11) {
        try {
            insert piu;
            count = 100;
        }  catch(DmlException e) {
            count++;
            List<String> splitError = e.getMessage().split(' ');
    
            for (String str : splitError){
                string check = str.removeEnd(',');
                check = check.removeEnd(':');
                for (String fieldName : availablePermissions){
                    if (fieldName == 'Permissions' + check){
                        piu.put(fieldName, true);
                    }
                }
            }
        }
    }
    
  5. Click Execute

Then assign this new permission set to the GRAX integration user.

Required User Settings

These settings modify the Salesforce features that users are allowed to access. Without these, GRAX may not be able to read certain portions of Salesforce data. They can be assigned from the "User" page within Salesforce Setup.

PermissionComments
Salesforce CRM Content UserEnsures access to read and write all Content Documents and related binary data.
Marketing UserEnsures access to read Campaign and related objects.

Recommended Permissions

These permissions are recommended to ensure that GRAX can read additional objects and fields in your organization, even if encrypted or from a licensed application. Permissions are assigned to the Permission Set, and licenses are appled applied from the "User" page within Salesforce Setup.

PermissionComments
View Encrypted DataEnsures encrypted values can be backed up
Proper Licensing for Managed PackagesSome packages requires licenses for object access

Field Level Security

Given how SFDC permission sets work, even when "View All Data" is given it is possible that the integration user is missing access to read fields on objects, in a way that is transparent to the integration user. To help detect and correct this, GRAX offers a web tool to check for missing field level security permissions on the integration user.

  • Browse to /web/tools in the GRAX web app and click "Missing Field Permissions"
  • Click "Start Scan"
  • If some fields are missing, click the object name to jump into the SFDC object settings for the "GRAX INTEGRATION USER Permission"
  • Click "Edit", check "Read Access" for missing fields, then "Save"
  • Back in the GRAX "Missing Field Permissions" tool, scan the object again to confirm

See the Salesforce Security Field Permissions guide for more details.

FAQ

Are these hard requirements? What if I need exceptions?

To provide the best Recovery Point Objective (RPO) possible and to avoid common data read and write pitfalls, GRAX automatically enforces many permission checks before you can start auto backup or auto archive. Furthermore GRAX automatically monitors permissions to detect changes over time.

If you can not satisfy the required permissions, please contact GRAX support to discuss using GRAX with reduced or disabled backup, archive and restore capabilities.

Can I use the System Administrator Profile? Can I use another Profile instead of the GRAX Permission Set?

A common pitfall is to assign the standard System Administrator profile to GRAX and assume that gives it access to everything.

Note that the standard System Administrator profile doesn't guarantee anything. Some permissions, such as View Encrypted Data and Query All Files may not be a default. Field Level Security may still apply to the profile.

Another common pitfall is to share a custom profile between GRAX and other SFDC end users.

While the System Administrator profile or custom profile can be modified to include all of the permissions, none of the field level security, etc., its common for a Salesforce administrator to periodically modify these profiles for other business and security objectives and to "break" GRAX's permissions for backup, archive and restore.

Therefore we recommend using an isolated Permission Set for GRAX to manage the unique needs for the automated backup, archive and restore system.

Finally, creating a Permission Set with the name GRAX_Integration_User allows the GRAX system to offer advanced monitoring, alerting and tooling to avoid common permission problems over time.

What if I can't grant View All Data or Modify All Data or remove Field Level Restrictions?

GRAX goal is to provide the best Recovery Point Objective (RPO) possible. To support data recovery, GRAX must:

  • Read all records and their relationships frequently for backup
  • Write any record and its relationships at any time from backup data for restore

If GRAX can not read some objects or records entirely, or some records partially due to field restrictions, it's backup data set is incomplete. If GRAX can not write some objects or records entirely, it's ability to restore data is incomplete. Therefore, any permissions that deny access to read or write any object, record or field can lead to a total inability to recover data.

The Create a secure Salesforce API user guide specifically calls out "Modify All Data", which implicitly includes "View All Data", as critical for an integration:

Modify All Data - Specifies that the user can view any data stored in the database and edit any field with the editable flag... This permission is also required for any user who wants to upsert non-unique external IDs through the API. When this permission is not enabled and if the user tries an upsert using non-unique external ID the error seen is as follows : INSUFFICIENT_ACCESS: Upsert requires view all data on a non-unique custom index

What if I can't grant Query All Files

A common pitfall is to skip "Query All Files" permission, see many files backed up, and assume that covers everything in your org. Without "Query All Files", GRAX likely has access to some files, but many other files in non-member libraries and unlisted groups are invisible and will be silently skipped in backups.

What if my permissions were incomplete during auto backup?

To avoid having to redo work due to incomplete permissions, GRAX automatically checks and enforces permissions before you can start auto backup. However if a permission problem did affect backup data you can:

  • Pause Auto Backup
  • Fix the permission problem, e.g. grant missing Field Level Security
  • Browse to an Auto Backup Object details page and add the admin-only "dangerous" flag:
    • e.g. https://qa.mygrax.com/web/backup/Case?dangerous=true
  • Select "Reset" to reset the object as if it has never been backed up with GRAX
  • Re-start Auto Backup

This is non-destructive, and will redo the object backfill with the correct permissions, "fixing" your backup data set.

Reference Docs