An Introduction to Salesforce to Salesforce

Abstract is a multitenant platform, and as such multiple customers have their own environments (orgs) in a shared platform. Each environment contains data that the customers wants to store. Sometimes, however, customers may want to share data between themselves. For example, two trading partners may want to share relevant data records.

Salesforce to Salesforce can be used to create this data sharing relationship. Salesforce to Salesforce is a natively supported feature of the platform, and easily enables two trading partners to share relevant data records in real time.

This tutorial introduces Salesforce to Salesforce, shows how you can enable it, how to create a connections between two different environments, and how to use the connection to share data.

Enabling Salesforce to Salesforce

Before you can use Salesforce to Salesforce (S2S), you have to enable it. This has to be done by both parties - on your org, as well as on the org with which you are going to share data. Administrators can enable Salesforce to Salesforce by accessing it in the setup menu. Note that once the preference is enabled, it cannot be disabled.

To enable, navigate to Setup -> App setup -> Customize -> Salesforce to Salesforce -> Settings. Hit Edit, select Enable, and then select Save.

Enabling Salesforce to Salesforce

Once Salesforce to Salesforce is enabled in your org, you can establish data sharing relationship with another org by sending an invitation (we will cover sending invitations in a later section). You can customize the invitation by modifying the from email address, display name and email templates used for sending the invitation emails.

Salesforce to Salesforce Setup

As a final step in this initial setup, you need to ensure that the user(s) managing the S2S connections have the appropriate permission to do so. In particular, enable the “Manage Connections” permission on the profile of the users. System administrator can create a new profile, for example "S2S Admin", and assign it to users who will be managing the connection. In smaller organizations the system administrator himself will probably be the person managing connections, in which case you may not need to create a separate profile.

Setting up a Connection

Let's assume that your company, as well as another company, have enabled Salesforce to Salesforce. Even though both orgs have S2S enabled, you have to establish a formal relationship between the orgs before sharing can take place. This is done by setting up a connection.

For the sake of a running example let's use two companies

  1. Acme Corp - this wil be the connection initiating company.
  2. Appirio - this will be the connection receiving company.

As a best practice, in Acme Corp, create an account representing the company that will receive the connection (Appirio), and also create a contact with email address under that account. This contact will typically be used when sending the S2S connection invitation.

To begin using Salesforce to Salesforce, you need to use the Connections tab. If you don't have it in an application, add it by navigating to Setup -> My Personal Information-> Change my Display -> Customize My Tabs.

On the Connections tab, click New to create a new connection with another org.

S2s newconnection.png

Select a contact under an account representing the other organization you want to share records with via S2S, and click "Save & Send Invite". The invitation email will be sent to the email address under the selected contact.

A connection owner also needs to be defined. The connection owner will receive all email notifications including system notifications in case there is a functional error when the connection is inserting/updating a record. Additionally, the connection owner will be assigned as the default owner of any new records, though this may be overridden by any assignment or other rules that determine record ownership.

S2s newinvite.png

When you click "Save & Send Invite" in this example, the Appirio system administrator (Joe Partner) will receive an email. Joe Partner will need to paste the URL in the browser address bar and login to initiate Salesforce to Salesforce connection. Here's an example invite:

S2s sampleinvite.png

Once logged in the Appirio org, the system administrator needs to hit Accept for the connection to start sharing records with Acme Corp.

S2s accept.png

Once the invitation is accepted, the connection to Acme Corp is established, no objects (standard or custom) are shared yet. Only data you choose to share will be shared - and that's that subject of the next section.

Publishing Objects

Once the connection is established, the next step is to publish and subscribe to objects. Both Acme and Appirio can publish and subscribe to each other's objects and fields.

To continue the tutorial, let's publish objects from Appirio. Do this by clicking on Publish in the Connection tab, and selecting the object that you wish to publish. You can publish most standard objects and all custom objects. We've selected Account, Attachment, Case, Case Comment, Contact and Lead.

S2s addremove.png

Select Edit on an object to choose the fields that you wish to publish to the other environment.

S2s editobject.png

As the following diagram indicates, we've chosen only to publish a handful of the fields related to an Account.

S2s fields.png

Modify each object to select the fields that you want to publish. This completes the publishing setup on the Appirio org. Let's now turn to the other environment and subscribe to these objects.

Subscribing to Published Objects

The receiving environment (Acme Org in our case) doesn't automatically have access to the data published from the Appirio environment. Rather, the org must first subscribe to the objects.

Login to Acme Corp and subscribe to these two objects and map the fields. This is done by navigating to the Connections tab, selecting the Appirio connection, and hitting "Subscribe". You'll now be presented with a list of the published objects to which you can subscribe:

S2s addsubscribe.png

The table essentially declares the mapping between the objects from the incoming org, and the objects to which they'll map in the receiving org.

An additional flag is sometimes displayed - Auto-Accept. If this option is selected, then records from the publishing org will be automatically accepted - the process will be entirely automatic. If you don't select the checkbox, then an administrator will first have to review incoming records before they are accepted. The checkbox is not always displayed. In particular, child objects are automatically accepted if parent objects are accepted, and the option is not available for junction objects either.

Now click Save. This completes the object level mapping. That is, we've defined which object from the Appirio environment maps to which object in the Acme environment.

Now you need to map the fields. Do this by clicking on Edit next to each object. Here we do so for the Account object.

S2s map.png

Now map the published Account fields from the incoming environment to the the Account fields in your environment:

S2s editformap.png

As the above diagram shows, we've mapped each field to the same field in the object in the receiving environment.

Field Mappings considerations

You may have come across situations where certain fields are not available for publishing, or where you are not able to subscribe to map some fields onto other fields. Here's a little more about this field mapping and how to resolve these.

  • Data Type matching - Only matching data type fields can be mapped. In other words, the mapping enforces field type, dimension and precision. So for example, you can map a text field to any other text field of equal or greater size. Lookup or reference fields can be mapped to text fields (of size 80 or greater), and auto-number fields can also be mapped to text fields (of size 30 or greater).
  • Field visibility - Lookup IDs are not available for publishing. You can enable S2S for those fields by creating a formula field and then publishing the formula field. In advanced section of formula field, select treat blank as blank.

The Salesforce to Salesforce setup is complete for Account and Contact objects sent from Appirio to Acme Corp. A similar setup can ensure that Account and Contact objects be shared from Acme Corp to Appirio.

Using the Shared Connection

Now that you've got both environments set up on Salesforce to Salesforce, let's look at how the configuration can be used.

A one-way share between two environments is achieved by having the source environment publish, and the target environment subscribe. Here the source environment acts as a master environment and would overwrite shared records in the target environment whenever there is a change to the record in the source environment. Any changes made to the shared record in the target environment are lost when the source environment record changes in this scenario.

A two-way share between environments is achieved by having both environments publish and subscribe to each others objects. Now shared records between the two environment synchronize whenever there is a change on either side.

In both cases, the Salesforce to Salesforce mapping determines which fields would flow from one org to the other.

Records can be shared in two ways , either manually or programatically.

Manual Sharing Records

Account, Contacts and most standard and all custom objects can be shared externally using S2S, Go to List view for the object and Select the records and click on "Forward to connection".

S2s forward.png

Select the connection and related objects if there are any, and save.

Note that only users with the Manage Connections profile permission will see the "Forward to connection" option. Additionally, users can only forward records they own or those owned by their subordinates (role hierarchy). System admins can share any record.

S2s select connection.png

When records are forwarded, records will be automatically created in the target environment if auto-accept for the object is enabled. If it's not enabled, the records sent will need to be explicitly accepted in the target environment as shown in screenshots below. In particular, in the target environment select the object (Account in this example) tab, click on the Go button in "Accounts from connections":

S2s accountsfromcon.png

Then click on "Accept" to accept the record in the target org.

S2s acc.png

Programmatic sharing records via Apex

Records can be shared for supported objects programmatically (via triggers, batch process, etc.). Programmatic sharing gives a higher level of control over how you share records and also makes it possible to carry over hierarchy/relationship to the target.

Here is basic code snippet to share a contact record via S2S programmatically.

 PartnerNetworkRecordConnection newConnection =
                     new PartnerNetworkRecordConnection(
                         ConnectionId = networkId,
                         LocalRecordId = newContact.Id,
                         SendClosedTasks = false,
                         SendOpenTasks = false,
                         SendEmails = false,
                         ParentRecordId = newContact.AccountId);
 insert newConnection;

Of course, this code can be improved for sharing multiple records and for complex scenarios involving lookup and parent child relationship. See the PartnerNetworkRecordConnection object for more information.

Side Note: Changing Page Layout

It is a best practice to add the "External Sharing" related list to the page layout to see the status of external sharing.

Go to details page for the record and click on "Edit layout"

S2s editlayout.png

Select "related list" from left side panel and drag and drop "external sharing" related list on the page, click save.

S2s rellist.png


If two different customers wish to share data between their orgs, then they can use Salesforce to Salesforce to provide the data exchange. Salesforce to Salesforce provides a mechanism to set up a formal connection between two environments, determine which objects will be shared as well as which fields within those objects. The records can then be manually shared, or programmatically.


About the Author

Nitin Jain is a Senior Technical Consultant at Appirio, where he designs and develops business applications in Sales and Service cloud and custom application development on the cloud.