GRAX Documentation

The GRAX Documentation Hub

Welcome to the GRAX Documentation hub. You'll find comprehensive guides and walkthroughs to help you start working with GRAX as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Salesforce Permissions

Let's take a look at what Salesforce permissions, profile settings, field-level and record visibility settings are recommended and necessary to accomplish various tasks within GRAX.

Introduction

Understanding Salesforce and GRAX permissions is critical to ensure data integrity and usability. This guide will review three main areas to consider:

  • Setting permissions related to GRAX managed package components upon initial install
  • Setting permissions for the GRAX Integration User and Apex User(s) that drive backup / archive / restore processes.
  • Setting permissions for end users to provide the sufficient access navigating the GRAX UI, tabs, and other GRAX features.

Initial Install

When installing the GRAX managed package into your Salesforce environment, you will be prompted to select which profiles should get access to all the GRAX-related components you are installing as part of the package. This is standard Salesforce behavior for all managed packages, as you must select profiles before installing. Please review the Salesforce Installation steps to understand how this works in more detail. This is the first stage of determining base level permissions for profiles, as it relates specifically and only to the GRAX components (objects, fields, apex etc) that come as part of the package.

👍

Recommendation

We recommend installing for all profiles that you think will need any sort of GRAX access, as it is much easier to assign permissions in bulk at this stage rather than post-install having to manually assign all permissions to various profiles.

Salesforce User Permissions

There are 2 key Salesforce users you will need to specify when setting up GRAX - what we'll refer to as the GRAX Integration User and the GRAX Apex User. GRAX leverages Salesforce APIs as well as Salesforce apex jobs to optimize performance, and thus you will need to be careful to ensure both users are equipped with the proper Salesforce permissions.

👍

Recommendation

The recommendation is that the GRAX Integration User and GRAX Apex user are the same user. This will ensure consistent permissions.

Integration User

The integration user is defined within the Configuration > Setup tab. The GRAX application will use this user to log in and query metadata and data for backup and archives. It is also the user that restores data.

For more general Salesforce best practices on creating integration users, see here.

👍

Recommendation

We recommend using a dedicated Salesforce user specifically for GRAX rather than sharing a user for GRAX and other integrations. This will optimize security, allow you to better audit issues, and also maximize concurrent API request limits that Salesforce imposes.

When initially setting up GRAX, the Setup subtab is where you would specify the Integration User, via OAuth.

Apex User

GRAX also leverages apex jobs, which are responsible for kicking off GRAX jobs (on a schedule or manually by a user) and also responsible for querying data along with the Integration user. You can specify the scheduled apex jobs by going to the Configuration > Miscellaneous tab. When you click the Activate Scheduled Jobs button here, YOUR user will become the user that is used by the apex scheduled jobs. Thus, we recommend logging in as the same Integration User and activating the scheduled jobs as the Integration User if possible, just to make things more consistent so you only have to manage one user's profile and permissions.

If you want to know which user is currently set as the apex user, navigate to this Miscellaneous tab, or you can go to Salesforce Setup --> Scheduled Jobs and look at the Submitted By column for the GRAX jobs.

❗️

Manually Executed Jobs

If a GRAX job kicks off on a schedule, the scheduled apex user's permissions will apply. If a GRAX job is executed manually on-demand using the Execute Now option, this running user's permissions will apply. In this case, you need to be extra careful that the running user also has the required permissions per the permission matrix you will find below.

It is worth reiterating that executing a job manually on-demand necessitates the running user have the same permissions as the apex scheduled user, otherwise all data may not be queried and this could lead to archive integrity issues. In this manual on-demand execution scenario, the apex jobs are created on-demand as the running user.

Plan ahead who will have access and the ability to kick off jobs manually!

Remember to set up the scheduled jobs user and set it to someone that has the required permissions as described in this guide.

Permission Table

Now that you understand the purpose of the Integration and Apex user, let's take a look at the minimum permissions required for these. Remember, when we say "Apex User", that represents the scheduled apex user or the running user in the event a job is executed manually. An "X" below means that this permission is required.

Integration User

Apex User

View All Data (or equivalent)

X

X

Modify All Data (or equivalent)

X
(this is for restores to ensure any object in the restore hierarchy can get successfully attempted for insert or update)

X
(this is for archives specifically as apex performs the record deletes)

View Encrypted Data

X

X

Query All Files

X

X

Read Access on all Objects and Fields Involved in Backups and Archives

X

X

API Enabled

X

Proper Licensing for Managed Packages (some packages require licensed users in order to access the relevant objects)

X

X

GRAX Admin Permission Set

X

X

📘

Other Permissions

The table above may not be exhaustive if there are other permissions that are needed to view all data/fields. Thus, we recommend the user has profile/permissions that have been assessed to provide access to all records and fields. Note that some permissions, such as View Encrypted Data and Query All Files may not be a default even for the standard System Admin profile. You will want to understand feature-specific permissions Salesforce may require as well, such as Knowledge objects.

Other Permission Notes

Let's take a look at other GRAX features and how permissions apply

Restoring Records

When restoring GRAX records, GRAX uses the integration user to restore records, so the integration user's permissions will dictate -- if they do not have access to edit a field, that will not get set. If they are subject to validation rules, these will fire etc. As stated above, you will want Modify All Data for this user, but that doesn't guarantee the restores will complete. You may also want to set inactive owners, audit fields, be exempt from validation rules etc. That should be determined based on your specific restore needs.

Object Selection List

When choosing objects to back up, either for a Backup or Archive within the hierarchy, you will only see a list of objects that the running user has access to via the standard Salesforce profile/permission model. So be sure the user that is setting up these jobs has relevant access to all objects.

Search and Display Data

When using the GRAX Search tab and creating views/selecting columns, field-level and object-level security of the user will impact the list of objects and fields that are available to select. Salesforce sharing rules and record-level sharing will not apply as the data is being retrieved directly from GRAX.

When using the GRAX Lightning Component the record-level security (I.e. sharing rules) will not apply so we recommend using SFDC out-of-box functionality to restrict lightning component based on that record's attributes within the lightning page builder. Click here for more.

GRAX Feature Permission Sets

The final layer of the GRAX-Salesforce permission architecture covers access around the actual functionality within the GRAX Salesforce application.

This is built around permission sets, which allow you to grant additional levels of access to specific users. Any user that will be interacting with GRAX, will need at least one permission set. These permission sets are the way to specify which parts of GRAX a user can interact with, and what level of activity they can conduct (for example: which tabs they can see, whether they can do backups vs archives, whether they can restore records etc).

Note that only difference in permission sets are apex class and visualforce pages, there aren't any standard Salesforce permissions being assigned. GRAX logic will check to see if a user has specific permission set, and then display/hide certain functionality based on which permission set user has.

Select your Base Permission Set

The first thing you should do is is set up the correct permissions for your users to access GRAX appropriately within Salesforce.

🚧

Assign Permission Sets First

Upon installing GRAX, nobody can interact with GRAX (not even a System Admin) until they grant themselves at least one relevant permission set.

Use Salesforce's permission set feature to find the relevant GRAX permission set and assign to appropriate users.

There are 4 base permission sets, in order of most to least permissions:

GRAX - Admin
GRAX - Limited Admin
GRAX - Advanced User
GRAX - User

You only need to assign each user one of these core permission sets depending on the permission level you want them to have.

Capability/Permission

User

Advanced User

Limited Admin

Admin

Search tab - search and view ability

Yes

Yes

Yes

Yes

Search tab - restore ability

No

Yes

Yes

Yes

Search tab - toggle data from other orgs

No

No

Yes

Yes

Scheduled Process tab - backup ability

No

No

Yes

Yes

Scheduled Process tab - archive ability

No

No

No

Yes

Configuration tab

No

No

Yes

Yes

Logs tab

No

No

Yes

Yes

Help tab

No

No

Yes

Yes

Time Machine - all actions including restore to previous versions

No

Yes

Yes

Yes

Time Machine - read only (unable to restore to previous versions)

Yes

Yes

Yes

Yes

See GRAX System fields and tables in Search views and filters

No

No

No

Yes

Datalake Delete tab

No

No

Yes

Yes

Audit Tab

Yes

Yes

Yes

Yes

GRAX - Community User

Starting from GRAX 3.30, the GRAX - Community User permission set is a unique permission set that will give community users a level of access to GRAX. The community user permissions are similar to the Advanced User in the above matrix, meaning that if you gave Community User permission set access to the GRAX tab, for example, they would have similar access levels as the Advanced User.

Typically we see customers having community users see the GRAX lightning component.

Depending on the community license type you have for the users, you may be unable to assign any of the other GRAX permission sets because Salesforce does not allow some community license types to have access to Salesforce apps, so typically your community users will have only the GRAX - Community User permission set.

Add-On Permission: GRAX - Data Admin

After selecting your base permission for each user, you can then add on some other permission sets to provide additional functionality. Note these add-on permission sets can be assigned in addition to the base permission set you choose from above.

There is a GRAX - Data Admin add-on permission that you can additionally assign to a user to provide them an extra ability around the Restore page.

📘

GRAX - Data Admin

A user assigned with this extra permission will be allowed to restore records on the "Restore" page that can be placed on an individual Salesforce parent record in order to view Data Lake child records related to this parent. Note that if you already have GRAX-Admin permission set, you don't need GRAX - Data Admin permission set.

Add-On Permission: GRAX - Archive Master

GRAX has an additional optional permission called GRAX - Archive Master. With this permission enabled, users have the ability to NOT backup child objects in a Hierarchy Backup. These objects will be skipped from the archive process, which will greatly increase the speed of the Scheduled Process, but this child object will not be backed up to the datalake. Many customers decide to go this route for certain child objects they know they are not using or don't care about deleting without backing up to the data lake.

❗️

Override Object Hierarchy

If you choose to override object hierarchy in favor of speed, be aware the children not selected will be deleted forever, and depending on the configuration of your lookup relationship fields, these could also be deleted or altered.

With this permission enabled, users will be able to see the following:

GRAX - Archive Master permission set allows the skipping of child objects in a hierarchy archive process

Add-On Permission: GRAX - Configuration Admin

Starting with GRAX 3.30, you will see a new permission set named GRAX - Configuration Admin. This is an add-on permission set that is REQUIRED to see the Configuration sub-tab within the GRAX Salesforce app. Again, remember this is an add-on permission set so you would still need the base GRAX - Admin permission set to complete configuration steps.

❗️

Security Note

Please only provide this permission set to Admins in your org that need to set up and maintain GRAX Configuration, as they will be able to see credentials for Salesforce, Elasticsearch, and Storage Provider(s).

Updated 3 months ago

Salesforce Permissions


Let's take a look at what Salesforce permissions, profile settings, field-level and record visibility settings are recommended and necessary to accomplish various tasks within GRAX.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.