Skip to content

Enabling Data Sync With JustOn Connector

JustOn Connector is an add-on to JustOn that allows you to synchronize data between two Salesforce organizations - data from an object in the source org is to be synced with an object in the target org.

Info

JustOn Connector requires at least the Salesforce Enterprise Edition.

In broad strokes, this data synchronization works as follows:

Info

This document describes how to set up the source org and the target org in order to enable the data synchronization.

Target Org Setup

Creating External ID Field

In the target org, you need a custom field that is marked as External ID on the target object.

  1. Navigate to the fields list of the target object.
  2. Check whether there is a field marked as external ID.

    If there is no external ID field, create it as required.

    Data Types Description
    Text
    Number
    The unique record identifier used to determine the records to be transferred. The field must be marked as external ID and unique.

    For help about creating fields, see Managing Object Fields in the JustOn Documentation or Create Custom Fields in the Salesforce Help.

Creating Connected App

To enable the access to the source org, you create a connected app in the target org.

  1. In Setup, open the New Connected App page.

    In Salesforce Lightning, navigate to Apps > App Manager, then click New Connected App.

    In Salesforce Classic, navigate to Build > Create > Apps, then click New in the Connected Apps section.

  2. Specify the app name, API name and contact email.

  3. Select the Enable OAuth Settings checkbox.
  4. Select the OAuth scopes Access and manage your data (api) and Perform requests on your behalf at any time (refresh_token, offline_access).
  5. Provide a fake callback URL, like https://foo.bar.
  6. Click Save.
  7. Copy the generated consumer key and consumer secret.

Note

The generated consumer key and consumer secret are required for the authentication provider in the source org (see Creating Authentication Provider).

For more details, see Create a Connected App in the Salesforce Help.

Source Org Setup

Info

JustOn Connector requires at least the Salesforce Enterprise Edition.

Contact the JustOn support team to have the add-on installed in your source org.

Creating Authentication Provider

To allow the access to the target org, you need an authentication provider.

  1. In Setup, open Auth. Providers.

    In Salesforce Lightning, navigate to Identity > Auth. Providers.

    In Salesforce Classic, navigate to Security Controls > Auth. Providers.

  2. Click New.

  3. Select Salesforce as the provider type.
  4. Specify the consumer key and consumer secret.

    Use the values as generated for the connected app in the target org (see Creating Connected App).

  5. If the authorization endpoint is a Salesforce sandbox, specify the following endpoint URL values:

    • Authorize Endpoint URL: https://test.salesforce.com/services/oauth2/authorize
    • Token Endpoint URL: https://test.salesforce.com/services/oauth2/token
  6. Specify refresh_token api as the default scopes.

  7. Click Save.
  8. Copy the generated callback URL.
  9. Switch to the connected app in the target org (see Creating Connected App).
  10. Replace the fake callback URL with the one created for your authentication provider.

Note

Make sure that the consumer key and consumer secret are still correctly set in the authentication provider after modifying the connected app.

For more details, see Configure a Salesforce Authentication Provider in the Salesforce Help.

Creating Named Credential

To allow the access from the target org, you need a named credential.

  1. In Setup, open Named Credentials.

    In Salesforce Lightning, navigate to Security > Named Credentials.

    In Salesforce Classic, navigate to Security Controls > Named Credentials.

  2. Click New Named Credential.

  3. Specify an appropriate label and API name.
  4. Specify the instance URL of the target org, like https://eu5.salesforce.com.

    Do not specify your My Domain subdomain but the instance URL. Find the instance on the Company Information page in Setup.

  5. Select Named Principal as the identity type and OAuth 2.0 as the authentication protocol.

  6. Select the authentication provider created before (see Creating Authentication Provider).
  7. Select the checkbox Start Authentication Flow on Save.
  8. Click Save.

    You are redirected to the Salesforce login page.

  9. Log in as a target org user, then log out.

    You are redirected to the Salesforce login page.

  10. Log in as a source org user.

Info

Check the field Authentication Status for the value Authenticated as <user@target_org>.

For more details, see Define a Named Credential in the Salesforce Help.

Configuring Fields to Transfer

The fields that are to be transferred are configured using the custom setting Remote Fields.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Remote Fields.

  3. Click New.
  4. Specify the details as necessary, then click Save.
Field Description Possible Values
Name A unique name for the custom setting record. unique value
External ID The local field that contains an external ID. The remote field must be configured as external ID field.
Each group needs at least one field marked as external ID.
true
false
Group The group of fields to be passed to the process, one group per process. Must be unique. unique value
Local Name The field that contains the source value from the local object. local API name, like Name, Custom__c, PREFIX_Other__c
Remote Name The field to receive the source value, must be available on the target object in the remote org. remote API name, like Name, Custom__c, PREFIX_Other__c
Remote Relationship Can be used to link parent relationships by external ID values, only valid for lookup/master-detail fields.
If the remote relationship is set, the remote name is used as the name of the external ID field of the parent.
relationship name, like Account, Account__r

Note

If there are required fields on the target, they must be present and mapped on the source as well.

Adding Upsert Information Fields

To get information about the last upsert to the target, you can add two fields to the source object.

  1. Navigate to the fields list of the source object.
  2. Create the following new fields.

    API Name Data Type Description
    ON_LastUpsert Date/Time The timestamp of the latest upsert.
    ON_LastUpsertError Text (255) Shows the error message in case the upsert has failed. Is cleared on success.

    For help about creating fields, see Managing Object Fields in the JustOn Documentation or Create Custom Fields in the Salesforce Help.

Setting Up Upsert Process

If you want to transfer the data from the source object (in the source org) to the target object (in the target org) when one or more defined conditions are met, you configure a corresponding process.

Configuring Process

  1. In Setup, open Process Builder.

    In Salesforce Lightning, navigate to Process Automation > Process Builder.

    In Salesforce Classic, navigate to Create > Workflow & Approvals > Process Builder.

  2. Click New.

  3. Specify a name and an API name as required.
  4. Set the process to start when A record changes.
  5. Click Save.
  6. Select the object whose modifications are to be transferred to the target org.
  7. Set the process to start when a record is created or edited.
  8. Define process criteria as required.

    Make sure that the process is not executed on every update. Otherwise this creates an infinite loop of update calls.

    Example conditions:

    • Monitor specific fields for changes: Transfer the record if the billing address has changed, for example.
    • Detect whether a custom checkbox field is selected: Transfer the record if, for example, Force_Transfer__c, is changed and set true.

    In this case, the process must reset the checkbox to false after the upsert operation to avoid infinite update calls.

  9. Select Apex as immediate action, and specify the class RemoteSObjectUpserter.

  10. Set the following variables, then click Save.
Variable Description Example
The group of fields to be considered The group as defined in the custom setting Remote Fields. Only fields of this group are considered by this process.
The named credential The name of the named credential in the source org.
Record ID The Salesforce ID of the record whose fields are to be transferred. Type: Reference Value: [Account].Id
API name of the object in the remote org The object type in the target org. Account

Info

Make sure to click Activate in the process detail view to activate the process.

For more details, see Create a Process in the Salesforce Help.

Setting Up Batch Size

The records will be processed by a queueable asynchronous batch process in order to keep the governor limits under control. This also allows bulk operations.

  1. In Setup, open Custom Metadata Types.

    In Salesforce Lightning, navigate to Custom Code > Custom Metadata Types.

    In Salesforce Classic, navigate to Develop > Custom Metadata Types.

  2. Click Manage Records in the row of Scope.

  3. Click Edit in the row of RemoteSObjectUpserter.
  4. Adjust the scope setting as required.

    • The scope must be in the range between 1 and 100 and depends on the number of transferred fields and available system resources.
    • Limit exceptions are reported by email. If necessary, reduce the scope accordingly.
  5. Click Save.

Defining Error Email Recipient

JustOn sends an error email to the user who triggered the remote upsert. This email contains a link to the local object and the message of the remote system.

You can configure the recipient of these emails.

  1. In Setup, open Custom Metadata Types.

    In Salesforce Lightning, navigate to Custom Code > Custom Metadata Types.

    In Salesforce Classic, navigate to Develop > Custom Metadata Types.

  2. Click Manage Records in the row of Setting.

  3. Click Edit in the row of Default.
  4. Specify the error recipient as required.

    The following options are available.

    Error Recipient Description
    USER JustOn sends the error email to the user who triggered the remote upsert.
    user@example.com JustOn sends the error email to user@example.com, regardless of the original user.
    empty JustOn does not send error emails.
  5. Click Save.

Setting Up Upsert Job

If you want to transfer the data from the source object (in the source org) to the target object (in the target org) on a regular basis at a specific time, you set up an upsert job.

Creating Batch Query Condition Fields

For the upsert job to retrieve the intended records, you must add checkbox fields to the source object.

  1. Navigate to the fields list of the source object.
  2. Create the following new fields.

    For help about creating fields, see Managing Object Fields in the JustOn Documentation or Create Custom Fields in the Salesforce Help.

API Name Data Type Required Description Value
ON_Upsertable Checkbox If true, records are considered for a transfer by the batch job. Should be selected for all records that are ready to be transferred, like invoice records not in status Draft. true
false
ON_UpsertFailed Checkbox Set automatically: A process that transfers records first sets this true. On successful transfer, it is automatically set false. true
false
ON_LastModified DateTime () Holds the last modified date and time. Required if you use ON_UpsertForgotten because it can be indexed (unlike the system audit field LastModifiedDate).
Must be updated by a workflow rule with the current time (NOW()).
ON_UpsertForgotten Checkbox (Formula) Used to find records that were not transferred although they were changed, like in case the process was temporarily inactive. ON_LastModified__c - ON_LastUpsert__c > 0.04
ON_UpsertNew Checkbox (Formula) Specifies records that have not been transferred yet.
This formula is used to avoid a full table scan (check for null value) when running the query. This formula can be indexed.
ISBLANK(ON_LastUpsert__c)

If all fields are configured, the query condition for the job will be:

ON_Upsertable__c = true AND (ON_UpsertFailed__c = true OR ON_UpsertForgotten__c = true OR ON_UpsertNew__c = true)

Info

For these optional fields to actually speed up the batch query, they must be indexed. Open a case with Salesforce to create the database indexes.

Creating Batch Upserter Configurations

According to your process setup (see Setting Up Process), you must create specific batch upserter configurations.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Batch Upserter Configurations.

  3. Click New.
  4. Specify the details as necessary.
  5. Click Save.

A batch upserter configuration includes the following information:

Field Required Description
Name A unique name for the custom setting record.
Group Only fields from this group are considered by this batch process.
Named Credential The name of the named credential in the source org.
Source Object Name The object whose changes are to be transferred to the target org.
Target Object Name The object in the target org to receive the source value.
Sequence Determines the order of the batch upserter execution.
If you intend to define the execution order, you must set the corresponding sequence number in all batch upserter configurations.
Condition Specifies a condition (SOQL WHERE clause) to determine the records of the source object to be transferred, like Date__c <= 2013-12-11.
If left empty, matches all records.
Active (checkbox) Specifies whether the batch upserter uses this configuration or not. Defaults to true.

Once set up, the configurations are processed sequentially. For each configuration setting, a new batch process is started.

Scheduling Upsert Job

You can schedule the upsert job using the standard Salesforce Schedule Apex functionality.

  1. In Setup, open Apex Classes.

    In Salesforce Lightning, navigate to Custom Code > Apex Classes.

    In Salesforce Classic, navigate to Develop > Apex Classes.

  2. Click Schedule Apex on top of the list.

  3. Specify the details as required.

    • Job Name: ScheduledUpserterBatchChain
    • Apex Class: ScheduledUpserterBatchChain (namespace prefix ONBC1)
    • Frequency: Weekly or Monthly (with an according weekday or day of month setting)
    • Start
    • End
    • Preferred Start Time
  4. Click Save.

    This sets up the job to execute the ScheduledUpserterBatchChain at the specified time.

For more information about scheduling jobs, see Scheduling Jobs in the JustOn Documentation or Schedule Apex Job in the Salesforce Help.

As an alternative, you can schedule the job in the Salesforce Developer Console using, for example, this command:

ONBC1.ScheduledUpserterBatchChain.setupSchedule('0 00 15 * * ?');

For valid cron expressions, see Apex Scheduler.

Immediately Executing Upsert Job

You can execute the upsert job immediately.

  1. Open the Visualforce page RunUpserterBatches by appending /apex/ONBC1__RunUpserterBatches to your instance URL.
  2. Click Continue.

    This starts the job.

Info

Alternatively, you can configure a custom link to this page to start the job later.

Enabling Connector in Sandboxes

To test JustOn Connector in sandboxes, it must be explicitly enabled.

  1. In Setup, open Custom Settings.

    In Salesforce Lightning, navigate to Custom Code > Custom Settings.

    In Salesforce Classic, navigate to Develop > Custom Settings.

  2. Click Manage in the row of Setting.

  3. Click Edit in the row of Default.
  4. Select the checkbox Enable in Sandbox.
  5. Click Save.

Note

Use this setting with caution, because it can overwrite your production data if the sandbox is still linked to a target production org with the named credential.