First we need to understand the naming conventions and the differences between Salesforce and Elements because the username structures are slightly different. We wanted to make it easier to manage multiple Spaces and Orgs - from a single user login - so we didn't copy the Salesforce approach.
Salesforce user name
- A username is linked to an individual Org - a Dev, Production or a Sandbox Org. You cannot have the same username to log into multiple Orgs.
- It is a random name but it needs to be in an email format e.g. firstname.lastname@example.org
- Pick a naming convention that is easy to remember quick to type. The shortest you are allowed is email@example.com
- Every username has an email address associated with it. Multiple usernames can have the same email address.
- Username needs to be unique across ALL Salesforce users
username email Org
firstname.lastname@example.org email@example.com Production
firstname.lastname@example.org email@example.com Sandbox-CPQ
firstname.lastname@example.org email@example.com Sandbox-int
firstname.lastname@example.org email@example.com Sandbox-cons
firstname.lastname@example.org email@example.com Dev123
Note: Sandbox email addressesWhen a Sandbox is created all of the users' email addresses, except for the user who created the sandbox are modified. Historically, the domain example.com was added to the users email address, with the original '@' being changed to an '='. In the recent release Salesforce have changed this to add '.invalid' to the users' email address.
Do not use the QuickStart process described below if your email address in the sandbox is not your valid email address. it will create an account in Elements with this email and you will not be able to use the account correctly.
Elements user names
- Your email address. A real email address. firstname.lastname@example.org
- You log into Elements - there is only one instance
- An Elements user can access multiple Elements Spaces
A quick recap on the principles of Spaces
- A Space is secure, ring-fenced work area. Think of it as an "implementation of Elements"
- DO NOT think of Spaces as folders. A corporate will probably only have ONE Space. A consulting firm will have one Space for internal operations and a separate one for every client.
- You can invite users to Spaces. They can then only see what is in that Space - provided they have been given view or edit rights. Every user in a Space can see the other users.
- An Elements user can be a member of multiple Spaces. One login - multiple Spaces.
- Whoever sets up the Space is the Admin. But you can assign admin rights to multiple people and Admin rights can be transferred by assigning admin rights to another, who then removes yours. A Space could be set up by a consultant and then transferred to the client at the end of the project.
- Finally, a user needs a separate license for each Space they are an Editor in.
- A Space can be FREE, PRO, PRO-TRIAL, ENTERPRISE or UNLIMITED.
Here is the important part.....
Each Salesforce Org is sync'd to its Elements Org Model
A Space can be connected to multiple Salesforce Orgs (Production & Sandbox). We organise those Salesforce Orgs into "Implementations" of Salesforce (i.e. Production and derivative sandboxes. So a Space will have multiple Org Models
Space limits for Orgs:
- FREE: zero Orgs.
- PRO: 1 Prod + 3 Sandboxes (1 implementation of Salesforce)
- ENTERPRISE: 4 Prod + 4 Sandboxes each (4 implementations)
- UNLIMITED: ....well, unlimited implementations
A picture... This shows how multiple Salesforce Orgs can be sync'd to Elements Spaces.
Setting up the sync: 1st Org
Every Org needs the free Elements managed package installed from the AppExchange. This is the small purple box in the Salesforce Org in the image above.
If you are existing Catalyst user and have an existing Team Space you want to sync with a Salesforce Implementation, you must use Manual setup. Do not use the Quickstart.
If you are a new user - or do not want to use an existing Team Space, the first install can be using our QuickStart setup. That is because Quick Start creates a new Elements Space called Salesforce Documentation and sets up the connections. QuickStart can be used to connect a Dev, Production or Sandbox. You can change the Space name.
Important: When you log into Salesforce Org to use QuickStart you MUST use a username that is associated with the email that is the same as the Elements login. In the example below the email is email@example.com If you don't then Quick Start will create a new Elements username which is the email address associated with the Salesforce username.
The video is 5 mins long, but once the managed package is installed the set up takes 26 seconds - yes, I timed it.
Setting up the sync: 2nd.3rd... Orgs
To connect a second and further Orgs to the same Space, you must use Manual Setup. This is because you want to connect to the same Space and if you use Quick Start it will create another new Space.
Again - when you log into Salesforce Org to use Manual Setup you MUST use a username that is associated with the email that is the same as the Elements login. In the example below the email is firstname.lastname@example.org
You will need to use Manual setup, but it is only slightly longer than using QuickStart.
Step1. Install the Elements Managed Package into the Org you want to sync
Step 2. Connect the Org to Elements
- Select the Elements App within Salesforce
- Select the Elements Settings tab.
The Welcome to Elements Documentation Hub for Salesforce page will be displayed. Click on the Manual Setup button. The Elements account tab will be shown.
The Elements Accounts tab is used to connect a Salesforce Org to an Elements Space. An Org can only be connected to one Space.
This Space should exist already in Elements (but cannot be a Personal Space) and the user must be an Admin for the Space. This can be a different user and account than the user who is logged into Salesforce.
Note: when connected to a Sandbox only the ‘Elements Account’ and ‘Org Model Setup’ tabs will be shown.
Connect to an Existing Elements space
A list of Spaces for the logged in Admin user is an Admin. Only Spaces which can be connected to will be available to select.
If the Org is a Production/Developer Org then for the Space to be available there must be an implementation that does not have a Production Org connected to it. By default one Implementation, called Default exists. To add more than one Production/Developer Org to a Space then has to be on the Enterprise, NOT Pro plan.
Select the Space and then select the implementation that you want to connect to. Click the ‘Connect Selected Space’ button.
Once the Space has been connected to an Org no other Space can be connected to the Org. You can disconnect the Space from the Org if required.
Step 3: Connect Elements to the Org
In Elements go to the Space Management App for the connected Space. This is accessible through the “Manage Space” button in the right panel
Select the Connections from the left menu and the Salesforce tab at the top. The page will show the ID of the connected Salesforce Org.
The image below shows a production Org connected. If a Sandbox is connected then there will be a panel for the Sandbox
Enable the Org Model by using the switch.
Step 4. Connecting Elements to Salesforce
Elements is a Salesforce Connected App and in order for Elements to communicate with Salesforce it has to connect to Salesforce. The account used to connect to Salesforce needs Administrator rights.
Click on the “Authenticate” link. This will take you to the Salesforce login screen if you are not already logged into Salesforce.
CARE: If you have multiple Salesforce accounts ensure that you select the correct account.
If you are using a custom domain, click on the “Use Custom Domain” on bottom of the login panel.
It will ask you to allow Elements to have access to the following items within Salesforce.
Elements will be configured as a Connected App with the following OAuth scopes.
Add required Remote Site Setting to Salesforce
Once the authentication has completed a dialog will be shown that allows a Remote Site Setting to be added into Salesforce
This opens up Salesforce on the New Remote Site Settings page with the required fields completed. Select ‘Save’.
Step 5. Schedule the Sync (optional)
Once the connection it is possible to configure that the Salesforce configuration data will be synchronized once a day. To enable this toggle the schedule switch. This will request the time at which the synchronization should start.
The time is the local time on the device of the user. Other users will see the time displayed in their local timezone.
Step 6. Run initial Sync
Use the button in the bottom right of the connection panel to run the sync
To add package data see the following section.
Selecting Managed Packages to include in the sync
By default the meta data retrieved includes all the information from any of the installed managed packages. To remove or change the packages you need to select which namespaces to include.
Click on the Button ‘Managed Packages’. This load the list of namespaces included in the Org. From this select the namespaces to include.