Login

Embedded

Accessing GRAX from within Salesforce, without installing a managed package

Overview

The GRAX Embedded App allows you to access the GRAX user interface from within Salesforce, opening each page in a new browser tab. This allows for accessing the webapp user interface pages without having to bookmark the pages or remember the URLs. This is sample code and should be reviewed and revised as needed prior to being deployed to your Salesforce environment.

The GRAX Embedded App can be found via the App Launcher in the top left of the Salesforce page, just under the main icon. Click the App Launcher, enter grax, then click GRAX Embedded under the Apps header.

Salesforce App Launcher

Tabs

The default GRAX Embedded app includes tabs for GRAX Setup, Accounts, Contacts, Opportunities, Cases, Reports, and GRAX Documentation. This set of tabs can be changed by your software development team.

Salesforce app home page for GRAX Embedded

Buttons

The default home page includes six buttons:

Menu section from GRAX Embedded App home page showing the various default buttons

  • Auto Backup Opens the Auto Backup page from the GRAX User Interface in a new browser tab.
  • GRAX Executions Opens the Executions page from the GRAX User Interface in a new browser tab.
  • GRAX Search Opens the Search page from the GRAX User Interface in a new browser tab.
  • GRAX Restore Opens the Restore page from the GRAX User Interface in a new browser tab.
  • GRAX Settings Opens the Settings page from the GRAX User Interface in a new browser tab.
  • Salesforce Settings Opens the GRAX Embedded Custom Settings page from Salesforce Setup in a new browser tab.

How to Use the Embedded UI

This functionality can be used by customers that have specific needs that require only certain views be displayed. The following documents the embedded UI.

GRAX URL Parameters

A GRAX embedded UI screen is powered by URL endpoints and query parameters. The following types of screens that can be opened are documented below:

  • Object View
    • Single Object
    • Child Objects
  • Search View

There are a few options to set that are common to all operations.

Common Fields

Field NameDescription
BASE_URLThis is the full URL to your GRAX installation
QUERY_PARAMETERSQuery parameters that can be passed - these are dependant on the operation and are documented further below in their appropriate section

Common Query Parameters

Query ParameterOptionsDescription
embeddedtrue, falseWhen set to true the GRAX user interface goes into embedded mode. This prevents the top and sidebar navigation from being rendered
autologintrue, falseWhether or not to try to automatically login with credentials. This should be set to true for most cases

Object Retrieval

The GRAX embedded UI has the ability to display single items or their children depending on the options set within the URL. And example of the type of URL you can use is below:

https://{BASE_URL}/web/objects/{OBJECT_NAME}/records/{OBJECT_ID}/{PAGE}?{QUERY_PARAMETERS}

Object Fields

Field NameDescription
BASE_URLThis is the full URL to your GRAX installation
OBJECT_NAMEThis is the name of the Salesforce object
OBJECT_IDThis is the Salesforce Object ID
PAGEThe type of page to display further information below
QUERY_PARAMETERSQuery parameters that can be passed - these are dependent on the page and are documented further below

Object Page Types

Page NameDescription
latestDisplays a single object view of the object indicated within the URL fields
childrenDisplays a table with the children objects. This needs query parameters to work correctly

Object Query Parameters

Query ParameterOptionsDescription
embeddedtrue, falseWhen set to true the GRAX user interface goes into embedded mode. This prevents the top and sidebar navigation from being rendered
autologintrue, falseWhether or not to try to automatically login with credentials. This should be set to true for most cases
includeFieldstrueThis should be set to true
fieldsURI encoded list of fieldsThis is an encoded CSV list of fields present on the child object that is being displayed.
deleteSourcesalesforce, grax, anyDisplay deleted records by how they have been deleted: salesforce - deleted by Salesforce user or process, grax - archived by GRAX, any - any record that is no longer in Salesforce
levela positive integer, defaults to one (1)Depth of child records to display
perPagea positive integer, defaults to five (5)How many child records appear on a page at one time. As the user selects Next or Previous, this is the number of records that will be retrieved

📘

What is an encoded list?

Commas are not valid characters within the query string. The commas need to be converted to the value of %2C .

As an example the list Id,Subject,CreatedDate should be converted to: Id%2CSubject%2CCreatedDate

Example

Q: I want to display an embedded view of case records for a company that has the Salesforce ID 0018V00002bWhauQAB. I want the ID and Subject fields as the only two columns in the table and I want to display 10 rows per view. My Base URL is fun-example-11

A: You will want to construct the following URL:

https://fun-example-11.secure.grax.io/web/objects/Account/records/0018V00002bWhauQAB/children?embedded=true&autologin=true&childObject=Case&includeFields=false&fields=Id%2CSubject&level=1&perPage=10

Searching

Below is an example URL to open a search window. The search must be performed in the window (it can't be passed into the URL).

https://{BASE_URL}/web/search?{QUERY_PARAMETERS}

A Sample of How to Embed the GRAX UI within SFDC

  1. Ensure you have enabled GRAX as a Trusted URL

  2. Login to the GRAX platform

  3. Navigate to page you plan to embed, in this example we are using the Global Search Tab, and configure a search criteria you would like the embedded tab to default to when accessed within your Salesforce org.

    Image showing a pre-configured Search page

  4. Copy the URL containing the pre-configured search parameters and add &autologin=true&embedded=true

  5. Go back to your Salesforce org and create a custom Web Tab.

    Go to Setup --> Search for Tabs --> Create New Web Tab --> Choose the page layout of the web tab you wish to create --> Define Content and Display Properties.

  6. Enter the URL Details and paste the pre-configured URL from the previous steps into the Salesforce Button or Link URL section. Complete the standard Salesforce Tab assignments and save.

See Salesforce Help and Training for additional information on how to create Salesforce Custom Tabs.

Once the custom Web tab is created and assigned to user apps in Salesforce, the selected GRAX functionality is available.

Image showing GRAX Search in Web Tab