This is a complete guide on how to connect and sync your Salesforce Org to Elements. This covers permissions, IP ranges, installation steps, and troubleshooting.
You can connect a Production Org and all associated Sandboxes. If you want to connect a different Production Org or Sandboxes from a different Org, you need to have multiple Salesforce connections purchased.
Supported Salesforce Editions
Enterprise Edition
Unlimited Edition
Developer Edition
Performance Edition
Professional Edition - only if API access has been purchased as an add-on
Unsupported Salesforce Editions
Group Edition
Essentials Edition
Supported Salesforce clouds and metadata types
Elements supports most metadata types for Salesforce Orgs and standard objects for most Salesforce Clouds. However, not all objects and metadata types are available on every license.
You can check the list of supported Clouds and metadata types here.
Required permissions
Elements permissions
User in the Elements.cloud workspace needs to have a Space Administrator permission.
Exception: In consulting spaces only, a client user with viewer permission can connect an Org to the space.
Salesforce permissions
The user account that is used to authenticate the connection to Elements needs to have either:
System Administrator profile (as all required permissions are part of that profile);
Minimum Access – Salesforce profile with additional system permissions.
Elements.cloud application does not require the View All Data system permission to perform metadata analysis.
System Permission | Purpose |
Approve Uninstalled Connected Apps | Required for the Org Connection process between Elements and Salesforce. |
API Enabled | Required to use Salesforce APIs for metadata retrieval |
Author Apex | Allows reading Apex Classes and Triggers. |
Manage Flow (App Permissions section) | Required to access and sync Flow metadata. |
Modify Metadata Through Metadata API Functions | Allows Elements to sync metadata via the Metadata API |
Manage All Private Reports and Dashboards | Enables syncing users’ private reports and dashboards. |
Manage Sharing | Allows syncing Sharing Rules and Restriction Rules. |
Run Reports | Get reports' attributes. |
View Roles and Role Hierarchy | Used to analyze sharing and access dependencies. |
View Setup and Configuration | Required to fetch setup data and metadata structure. |
View All Custom Settings | Enables syncing custom settings. |
View All Users | Allows getting created by and modified by attributes. |
View Dashboards in Public Folders | Allows reading dashboards in public folders. |
View Reports in Public Folders | Allows reading reports in public folders. |
Prompt Template Manager Permission Set | Allows syncing Agentforce metadata. |
Setting up a Minimum Access Integration User
If you want to use a non-admin “Integration User” account in Salesforce for authentication of the Org connection to Elements, then you need to create an integration user.
Steps to create an integration user
Steps to create an integration user
Clone the Minimum Access - Salesforce built-in profile
Use a name that follows your naming practice, for example, “Integration-Elements”.
Create a new Permission Set for Elements sync.
Follow your naming practice, for example, “Elements Sync Permissions”
Include a description
Within the created Permission Set, select App Permissions, then enable the following permissions in the Flow and Flow Orchestration Section:
Manage Flow (required)
Navigate to the System Permissions, then enable the following permissions:
Approve Uninstalled Connected Apps (required)
API Enabled (required)
Author Apex
Modify Metadata Through Metadata API Functions (required)
Manage All Private Reports and Dashboards
Run Reports
View All Custom Settings
View Dashboards in Public Folders
View Reports in Public Folders
View Roles and Role Hierarchy (required)
View Setup and Configuration (required)
Scroll to the Users Section and enable:
Manage Sharing
View All Users
Save the permission set and confirm enabled permissions.
Create a new user account following your naming practice and save the record:
Use an administrator or a shared email to receive messages there
Assign a Salesforce license
Assign the profile you've created: Integration-Elements
Navigate to the Permission Set Assignments, Edit Assignments, then assign and save the created permission set Elements Sync Permissions.
NOTE: If your Salesforce org has features governed by Permission Set Licenses (PSL), you may get a message that one or more PSLs for an object must be assigned to your Integration User. Review the PSL Assignment screen details and assign PSLs that cover objects not part of the core CRM. An example would be Field Service Lightning.
Once the Integration User is set up in Salesforce, you can connect a Salesforce Org using the user's credentials.
Log out of all Salesforce sessions.
Log in to Salesforce with the integration user account again and ensure that no login dialogs pop up. If a dialog appears, complete it, logout, then login again.
Log in to Elements.cloud as a Space Admin.
Navigate to Metadata and click Connect Salesforce Org button.
Follow the process.
If your Salesforce Org is already connected using another user's credentials, you can change it without disconnecting and reconnecting the org again.
In the Elements.cloud application, navigate to Metadata, select the record of the connected Salesforce org. In the right-side bar, you should see the org details, click on the Settings tab, and in the Connection section, click on the Refresh button below the Authentication username.
Required session settings and IP ranges
This section only applies if your Salesforce Org enforces login IP ranges and session settings.
If Login IP ranges are set up for the profile of the Salesforce user who is authenticated, then 3 additional IPs have to be added to the IP range. The reason for this is that Elements is logging in as the user from the Elements Servers.
IP ranges for EU instance
IP ranges for EU instance
If you are using our EU-based instance (app.q9elements.com), the IPs are:
54.74.113.50
54.228.164.25
63.33.178.248
IP ranges for US instance
IP ranges for US instance
If you are using our US-based instance (app.us.elements.cloud), the IPs are:
3.132.234.30
3.141.148.147
18.216.198.209
IP ranges for Japanese instance
IP ranges for Japanese instance
If you are using our Japan-based instance (app.ja1.elements.cloud), the IPs are:
52.193.159.23
52.196.233.190
57.181.54.88
Session settings
Session settings
In the Session Settings (in the Org Setup) there is an option called "Enforce login IP ranges on every request". If this is checked on, then as the name implies the IP is checked on every request, not just at login.
Because the Elements package makes REST API calls from Salesforce, but executing under the user account that the sync runs under, the IP address is not the Elements one that the Salesforce server is running under. The Salesforce IP addresses need to be added to the Login IP range for the profile. The IP addresses can be found in this Salesforce article: https://help.salesforce.com/articleView?id=000003652&type=1
Connect and sync the Salesforce Org
Before you connect
Before you attempt to connect an Org, we recommend that you either:
Log in to Elements in incognito mode of your browser
Log out of all your Orgs, Trailhead, and related Salesforce sites
Log out and then log back in to your target Salesforce Org
Elements.cloud will automatically pick the most recent Salesforce login token. If you are logged in to multiple Orgs, you will not have the ability to choose which one gets connected to.
Make sure you are logged in with the Salesforce account that will be used to authenticate the connection. Ensure the user has all the required permissions in Salesforce.
Org connection
Select the "Metadata" menu item in the main application and click the "Connect Salesforce Org" button in the upper-right corner of the screen.
You will first see a pop-up explaining the required permissions. If you meet these permissions, click "Next."
Select whether you want to connect to a Production or a Sandbox Org.
Log in to the target Org with your Salesforce credentials.
The sync has started, and you will be notified when the Salesforce Metadata Dictionary has been built and analysed.
The sync is also scheduled automatically at a random time between 9 PM and 6 AM in your time-zone. You can change the schedule in the Org settings.
Complete your Setup
A new Setup Checklist appears in the Connected Org right sidebar, highlighting three highly recommended tools:
Elements Connected App
Elements Managed Package
Browser Extension (Chrome & Firefox)
Each item includes direct action links for installation. Once the user checked all three items, the checklist is no longer visible for the connected org model.
Why do I need to install the Elements Connected App?
Installing the Elements Connected App converts it from “in-use but uninstalled” into a fully trusted app in your Org, so your users will not be affected by Salesforce Connected App Usage Restrictions.
In Salesforce Setup, go to Connected Apps OAuth Usage.
Locate Elements in the list.
Click Install (this option only appears if the app is currently uninstalled but in use).
Confirm the installation in the new window.
(Optional) If the integration user of the connected org is not a System Administrator, go to the created permission set (for example, Elements Sync Permissions) and remove the Approve Uninstalled Connected Apps permission.
Sync configuration records and dependencies between them
Some Salesforce Clouds utilize 'configuration records', records of data, stored on specific objects, that drive configuration and processing logic for specific Salesforce capabilities.
The most notable example of that is Salesforce Revenue Cloud, where objects like 'Price Rule' or 'Product Rule' allow admins to define configuration of their pricing logic using data.
For specific Salesforce Clouds (check the list here), we allow our customers to sync configuration records for chosen objects.
Before you can sync configuration records for given objects, you need to first allow the first sync to complete.
That is because a pre-requisite for Elements to sync configuration records is to first get hold of the target objects.
Once your Org has synced successfully, and provided you have one of our Add-On products enabled on your Org, follow these steps:
Select your 'implementation'
Click on 'Industry settings' tab
Click on "Update configuration object sync"
In the configuration window, find and choose the objects holding configuration data for which you would like to sync the records.
Re-start the sync manually (or wait for the automatic sync to start)
We do not allow users to sync records for any objects they wish. Instead, we curate a list of proven, standard objects that hold configuration data and are not used in customer / transaction operations.
Troubleshooting / FAQ
Sometimes, Salesforce Org sync fails or ends up with missing metadata in the metadata dictionary. This does not happen often, but in a rare instance that it does, here are the usual suspects:
Sync fails almost instantly after starting the connection
Sync fails almost instantly after starting the connection
This normally means that the "Remote Site Setting" is incorrect, so Salesforce won't let Elements sync. This could be for the following reasons:
One of the two Remote Site Settings is missing or incorrect. There should be https://api.q9elements.com and then EITHER https://na99.salesforce.com where na99 is your server OR https://AAA.my.salesforce.com where AAA is your MyDomain.
Your Org has been moved to a new pod, i.e. na53 to na57. So, you need to update the Remote Site Setting, e.g. https://na53.salesforce.com changes to https://na57.salesforce.com.
You have implemented MyDomain which means you need to ADD a new Remote Site Setting, e.g. https://AAA.my.salesforce.com where AAA is your MyDomain.
The Org has 'Lock Sessions to the IP address from which they originated' in Security/Session Settings enabled. This stops Salesforce from being able to make REST API calls to itself, which the Elements Sync requires. This setting will also stop the Salesforce Workbench from being able to make REST API calls.
Session Settings lock sessions to the IP address from which they originated.
There is another setting that effects the sync from Salesforce to Elements. If the setting "Lock sessions to the IP address from which they originated" is checked the sync will fail. With this item checked, it is not possible to run the sync.
I get 'OAuth Error' with message 'OAuth_approval_error_generic" when trying to connect an Org
I get 'OAuth Error' with message 'OAuth_approval_error_generic" when trying to connect an Org
This error shows up because you have tried to connect an Org without the 'Approve Uninstalled Connected Apps' system permission in Salesforce.
To rectify this:
make sure your account which will be used to authenticate the connection has all of the listed permissions
click to connect an Org again
Once the connection is established and an Org is syncing, go to your connected apps in Salesforce and approve/install the Elements connected app.
Sync returns a "Salesforce token not found" error
Sync returns a "Salesforce token not found" error
This means that either:
in Elements app, the connection has not been authenticated; or
in Elements app, the Salesforce user that was authenticated does not belong to this Org or does not have the right to access the API.
You can refresh (and reset) the user token in the settings tab against the Org connection. It is also worth re-checking if the account used for the connection has all the right permissions.
Org failed to sync due to expired or revoked token
Org failed to sync due to expired or revoked token
The Org sync will fail if the Salesforce refresh token has expired or been revoked.
First, ensure that the authenticating users have access to the elements permission set. If not, add them to the permission set again.
Select the Salesforce metadata dictionary that failed to sync from the list. You can either click on the hyperlinked action text in the list or select the Org settings tab in the right panel and choose the "Settings"* option.
*Depending on the context, the action button may display "Authenticate", "Refresh" or "Reconnect". In all cases, the result will be the same.
You will be taken to the Salesforce login screen. Log in with your credentials to the appropriate Org. After you click "Log in" you will be directed back to the Elements app and the connection will be reauthenticated.
Org failed to sync after we refreshed the Sandbox
Org failed to sync after we refreshed the Sandbox
The Org sync will fail after you refresh the Sandbox. This is because after the refresh all Salesforce IDs are changed.
Select the Salesforce metadata dictionary that failed to sync from the list. You can either click on the hyperlinked action text in the list or select the Org settings tab in the right panel and choose the "Authenticate"* option.
*Depending on the context, the action button may display "Authenticate", "Refresh" or "Reconnect". In all cases, the result will be the same.
You will be taken to the Salesforce login screen. Log in with your credentials to the appropriate Org. After you click "Log in" you will be directed back to the Elements app and the connection will be reauthenticated.
I cannot find the metadata component in my Salesforce metadata dictionary
I cannot find the metadata component in my Salesforce metadata dictionary
We do not sync ALL Salesforce metadata components.
Most customers do not use a lot of Salesforce metadata types, and by supporting all metadata of all types we would make the sync much longer and end up utilizing way more of your Salesforce APIs.
Consult this list of supported Salesforce Clouds (Products).
If we support the metadata type that is missing, contact us via the chat icon in the application and raise a case with our support team.
If we don't support the metadata type that you need, contact us via the chat icon to describe your use-case and raise a feature request with our support team.
Org was syncing fine for a while and then it failed
Org was syncing fine for a while and then it failed
Elements monitors ALL syncs happening in the system. Whenever there is a sync failure, we automatically raise a case to be investigated by the technical team which includes the specific error code. Our support team usually contacts the affected customers with recommended steps on how to resolve the issue.
More than half of all Orgs fail to sync due to Salesforce time-out issues. That is, Elements was waiting for Salesforce to come back to us with information but Salesforce's APIs never returned the required information.
Simply manually re-triggering the sync tends to fix this issue. 90% of all sync failures due to polling timeouts resolve themselves with the subsequent scheduled sync.
We only see field population being calculated for the last 10,000 records
We only see field population being calculated for the last 10,000 records
You need to schedule an apex job in our managed package to get the full, advanced insights into data population of objects, record types, fields, and picklist values across the entire data.
We can't see field population insights for some fields
We can't see field population insights for some fields
There are currently some limitations to the data we pull in.
We are unable to generate % filled information for multi-picklist selection fields.
We cannot show the record type information if you have got 50 or more record types on a particular object. It will instead show only the "Master record" type based on the last 5k records.
Although we sync hidden fields in Salesforce we can't get any % filled data for them.
The following fields are limited to the last 5000 records due to Salesforce data storage limitations:
Is Deleted
Billing Address
Shipping Address
Description
Is Excluded From Realign
Is Partner
Is Customer Portal
Activity Date
Vote Score
Best Time to Contract End Time
Out of Office Message
Start Time
Vote Total
Creator Full Photo URL
Creator Small Photo URL
Creator Name
And the following field types are limited to last 5000 records:
Boolean
Text Area
Location
Address
Base 64
Encrypted String
Time
If you want to discuss any of these limitations with us, or you have a particular use case we do not support, please reach out to us at support@elements.cloud where we can help!
We use namespace in our Org, how does it affect the sync?
We use namespace in our Org, how does it affect the sync?
It is possible to define a namespace for your Org. Whilst namespaces are normally associated with managed packages, it is possible to define a namespace for any Org. This has the effect of prefixing any custom component in your Org with the namespace that you have provided (which must be unique in the whole Salesforce ecosystem) and the underscore nomenclature '__'.
When the Org is synced to the Org Model in Elements all the custom items will appear in the managed package part of the tree under the name given to the namespace, even though it is not a managed package.
If you add a namespace to an existing Org that has already been sync'd to Elements it will consider all the custom components as new components, since they now have a new unique API name. The existing items which are in the main body of the tree will be marked as deleted.
We can't uninstall the Managed Package due to an active dependency
We can't uninstall the Managed Package due to an active dependency
If you are having issues with uninstalling the Managed Package, you can change the email recipient of the "IsWorkflowRuleFired" Email Alert to an Admin user in your Org. This should then remove the dependency which prevents uninstalling of the Elements Managed Package.