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.
License prerequisites
License: you are either on a Trial plan, consulting plan, or have purchased the Metadata Management license.
Scope: 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.
Read here on how you can use Elements to manage multiple Salesforce connections.
Supported Salesforce editions
Elements connects with Salesforce and analyzes metadata configuration through API calls. Therefore we need an Org that has API access enabled.
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
Required permissions
Elements permissions
User in Elements needs to have:
Space Administrator permission
Exception: in consulting spaces, the client who holds the viewer permission can also 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)
"Standard user" with additional permissions listed below
Minimum access profile with custom permissions (scroll down to learn how to set that up)
Detailed list of required Salesforce permissions
Detailed list of required Salesforce permissions
System permissions
API Enabled - required to use Salesforce APIs
Author Apex - required for syncing Apex Classes and Apex Triggers
Manage All Private Reports and Dashboards - required for syncing Private Reports and Dashboards
Manage Flow - required for syncing Flows and Flow tests
Modify Metadata Through Metadata API Functions - required for syncing Apex Classes and Apex Triggers
Run Reports - required for syncing Reports and Dashboards
View All Custom Settings - required for syncing Custom Settings
View Dashboards in Public Folders - required for syncing Reports and Dashboards and their respective dependencies
View Roles and Role Hierarchy - required for syncing Roles
View Setup and Configuration - required for syncing Apex Classes, Apex Triggers, Matching Rules, and Flows
View Event Log Files and View Real-Time Event Monitoring Data - required for viewing Adoption insights about the Org
User permissions
Manage Sharing - required for syncing Sharing Rules and Restriction Rules
View All Users - required for user provisioning
Assigning the ElementsAdmins permission set will allocate the permissions below:
The Batch Log object requires Read, Create, Edit and Delete permissions
Apex class permission
The following Apex classes have to be enabled if the Elements managed package is installed
Q9.ElementsREST
Q9.ElementsSettingsControllerBundle
Setting up a minimal access integration user
You can connect to Elements using System Administrator profile. However, our recommendation for connecting to Elements is to use an “Integration User” account in Salesforce for continued synchronization to Production orgs and Sandboxes.
Steps to create integration user
Steps to create 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 “System - Elements Sync”
Include a description
Within created permission set, select App Permissions, then enable the following permissions in the Flow and Flow Orchestration Section:
Manage Flow (required for syncing Flows)
Select System Permissions, Edit, then enable the following permissions in the
System Section: (Take care here - if you make a mistake, it is best to cancel and start again.)
API Enabled (use Salesforce APIs)
Author Apex (sync Apex Classes and Apex Triggers)
Manage All Private Reports and Dashboards (sync Private Reports and Dashboards)
Run Reports (sync Reports and Dashboards)
View All Custom Settings (sync Custom Settings)
View All Data (summarize record information, record counts - no data is transferred)
Scroll to the Users Section and enable:
Manage Sharing (sync Sharing Rules and Restriction Rules)
View All Users (user provisioning from Salesforce to Elements)
Save and confirm
Create a new user account following your naming practice.
Assign an administrator’s or a shared email account to receive messages.
Assign a Salesforce license and the new profile that you created, then Save.
Note: The “Salesforce Integration” license type cannot be used for Elements sync.
Select Permission Set Assignments, Edit Assignments, then enable the following:
System - Elements Sync (or your new permission set as created above.)
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 core CRM. An example would be Field Service Lightning.
Save
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
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 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 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
The reason is that Elements will automatically pick the most recent Salesforce login token. If you are logged in to multiple Orgs, you will not have ability to choose which one gets connected to.
Select the "Salesforce Orgs" menu item in the main application and click "Connect Org" button in the upper-right corner of the screen.
Select whether you want to connect a Production or a Sandbox Org. If it is a trial Space you will have an implementation already created, otherwise, you might need to create your first implementation.
Log in to the target Org with your Salesforce credentials.
That's it! 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.
Installing managed package for advanced analysis, SSO and user provisioning
At this point your Salesforce Org is already syncing and being analyzed.
However, for Production Orgs and Full Sandbox Orgs we recommend you also install the managed package as it is used to run object, record type, field and picklist population analysis, support user provisioning and set up auto-login flows between Elements and Salesforce.
Install the managed package
Click here to install the managed package in your Org.
Assign package's Elements Admin permission set
The Package contains the Elements Admin permission set.
Once the package has been installed, you should assign this to the user who's account authenticated the Elements/Salesforce connection.
Note:
This Permission Set allows us to read and analyse the metadata for your Org analytics, and it will not populate without this assigned to your user.
Authenticate package connection using Elements credentials
Select the Elements App within Salesforce
Select the Elements Connection details tab.
The Connection details tab is used to connect a Salesforce Org to an Elements Space.
Simply log in to the package using your Elements credentials (Elements username & Elements password). The package will then automatically connect to the already synced Salesforce metadata dictionary.
Additional step for customers on US instance only
Additional step for customers on US instance only
For US Instance, the Advance setting tab will be set up as seen in the image below
Domain: app.us.elements.cloud
API Domain: api.us.elements.cloud
API Port Number: Leave empty - if this is not allowed, use Port 443
Schedule apex jobs to calculate advanced insights
To prepare for this step, go to the Salesforce Orgs page in Elements, select your org, a find the Daily Sync Time in the right panel. Schedule the jobs as shown below one hour before this time. Note that it may be different for each org.
In the 'scheduled jobs' tab in the managed package, you can schedule and set the three jobs which are required to run the analysis of your Org.
The bottom pulldown allows you to remove scheduled jobs.
Once the jobs are scheduled and the sync has finished, set the "data population via managed package" option on the Elements org setting screen shown previously.
Here is more detail on the main jobs and their purpose.
Profile metadata batch job
Profile metadata batch job
One of Elements' strengths is our ability to expose which users have access to which metadata components in your Org and why (through which profiles, permission sets, or permission set groups). We can also run advanced comparisons across your profiles and permission sets to highlight overlap.
However, due to Salesforce Metadata API limitations, we cannot get this information directly from Salesforce. You need to schedule the apex job for our package to calculate and share that information directly with your metadata dictionary.
Record population information
Record population information
Without this scheduled job, Salesforce Orgs connected to Elements use an automatic, weekly sync for data population. This updates % filled data on Saturdays and may result in outdated or limited data due to the 10k record sample cap.
This method can be inefficient, especially for objects with large record counts. The apex job involves a daily scheduled fetch via a managed package, which updates data daily without record limits and supports % filled data for individual picklist values. This improvement eliminates the need for manual updates and is recommended for users with high record counts on their objects.
Setting target Salesforce URLs
Space Admins can define for each Salesforce Metadata Dictionary whether the URL links for each metadata component launch Salesforce setup in Classic or Lightning to edit the item.
This action cannot be done during active sync.
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.
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 "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.
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 metadata component in my Salesforce metadata dictionary
I cannot find 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.
First, consult this list of supported Salesforce metadata types.
Then, 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 success@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.