Skip to main content

Connect and sync a Salesforce Org, and Managed Package setup

Installation guide; How to connect Salesforce metadata dictionary? Connecting Salesforce Orgs, Org Connection settings; Managed Package

Updated this week

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

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 Elements needs to have:

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)

  • "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

System permissions

  1. API Enabled - required to use Salesforce APIs

  2. Author Apex - required for syncing Apex Classes and Apex Triggers

  3. Manage All Private Reports and Dashboards - required for syncing Private Reports and Dashboards

  4. Manage Flow - required for syncing Flows and Flow tests

  5. Modify Metadata Through Metadata API Functions - required for syncing Apex Classes and Apex Triggers

  6. Run Reports - required for syncing Reports and Dashboards

  7. View All Custom Settings - required for syncing Custom Settings

  8. View Dashboards in Public Folders - required for syncing Reports and Dashboards and their respective dependencies

  9. View Roles and Role Hierarchy - required for syncing Roles

  10. View Setup and Configuration - required for syncing Apex Classes, Apex Triggers, Matching Rules, and Flows

  11. View Event Log Files and View Real-Time Event Monitoring Data - required for viewing Adoption insights about the Org

User permissions

  1. Manage Sharing - required for syncing Sharing Rules and Restriction Rules

  2. 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 minimum access integration user

You first connected to Elements using System Administrator profile. After the connections are created and verified, our recommendation is to use an “Integration User” account in Salesforce for Production and key Sandbox org connections.

Steps to create integration user

  1. Clone the Minimum Access - Salesforce built-in profile

    • Use a name that follows your naming practice, for example “Integration-Elements”.
      ​

  2. Create a new permission set for Elements sync.

    • Follow your naming practice, for example “System - Elements Sync”

    • Include a description
      ​

  3. 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)
      ​

  4. 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)
      ​

  5. Scroll to the Users Section and enable:

    • Manage Sharing (sync Sharing Rules and Restriction Rules)

    • View All Users (user provisioning from Salesforce to Elements)

  6. Save and confirm
    ​

  7. Create a new user account following your naming practice.
    ​

  8. Assign an administrator’s or a shared email account to receive messages.
    ​

  9. 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.
    ​

  10. Select Permission Set Assignments, Edit Assignments, then enable the following:

    1. 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.

    2. Elements Admins permission set

  11. Save

  12. Once the Integration User is set up in Salesforce, the Elements connection must be updated to use these new credentials.

    • Logout of all Salesforce sessions.

    • Login 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.

    • Login to Elements.cloud as a Space Admin.

    • Select Salesforce Orgs, then highlight the org to be updated.

    • In the right panel, select the “gear” icon, then click Refresh next to the Authentication Id.

    • The Authentication Id will change to your integration user id.

    • Elements will now sync to Salesforce with the Integration User credentials.

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

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

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

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

  1. Select the Elements App within Salesforce

  2. 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

  1. 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

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

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.

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:

  1. Select your 'implementation'

  2. Click on 'Industry settings' tab

  3. Click on "Update configuration object sync"

  4. In the configuration window, find and choose the objects holding configuration data for which you would like to sync the records.

  5. 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.

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

This normally means that the "Remote Site Setting" is incorrect, so Salesforce won't let Elements sync. This could be for the following reasons:

  • 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

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


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


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

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


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


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

There are currently some limitations to the data we pull in.

  1. We are unable to generate % filled information for multi-picklist selection fields.

  2. 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.

  3. Although we sync hidden fields in Salesforce we can't get any % filled data for them.

  4. 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
      ​

  5. 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?


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.

Related Articles
What is an Org Model?
Navigating metadata dictionary
Indexing your Org's metadata for AI
Adding Metadata Descriptions in Elements
How to Monitor and Act on Salesforce Metadata Changes to Maintain Org Stability and Security
Did this answer your question?