action.skip

Enabling Data Sync With JustOn Connector

JustOn Connector is an add-on to JustOn Billing & Invoice Management 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:

  • JustOn Connector is installed in the source org.
  • In the source org, you set up a named credential for the authentication, then you configure a number of custom fields on the source object. For the actual data transfer, you set up a flow or a scheduled job.
  • In the target org, you add a custom field that is marked as External ID to the target object.
  • Once all is set up, the data is upserted using the Salesforce REST API.

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. Click to enter Setup, then 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 JustOn Support 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. Click to enter Setup, then 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. Click to enter Setup, then 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. Click to enter Setup, then 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 flow, one group per flow. 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 Flow

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

Configuring Flow

Note

Depending on your use cases, the flow setup and the objects to involve will vary.

  1. Click to enter Setup, then navigate to Process Automation > Flows.
  2. Click New Flow.
  3. Select Record-Triggered Flow and click Create.

  4. Configure the Start element.

    Option Description
    Object The object whose record modifications are to be transferred to the target org
    Trigger The type of record change that triggers the flow, must be A record is created or updated
    Conditions The use case-specific trigger conditions, one or more filter criteria for evaluating certain field values or a formula for evaluating records
    Make sure that the flow is not executed on every update to avoid an infinite loop of update calls.
    Optimize for Actions and Related Records

  5. Click and add the following Action element.

    Option Description
    Action The Apex class to call, must be RemoteSObjectUpserter
    Input Values Invocable variables for the Apex class
    The group of fields to be considered: specifies a group as defined in the custom setting Remote Fields, only fields of this group are considered by this process
    The named credential: specifies the name of the named credential in the source org
    Record Id: specifies the Salesforce ID of the record whose fields are to be transferred – usually, via reference to the object's ID field, like {!$Record.Id}
    API name of the object in the remote org: specifies the target object in the target org

    Specify a label and an API name as required.

  6. Click Save.

    Specify a label and an API name as required.

  7. Click Activate.

    When the defined conditions are met, JustOn triggers the flow. It transfers the relevant data from the source records in the source org to the target records in the target org.

    For help about creating flows, see Flows in the Salesforce Help.

Example use case: Monitor specific fields for changes

You can transfer, for example, accounts when the billing address has changed:

Flow Element Option Value
Start Object Account
Trigger A record is created or updated
Conditions All Conditions Are Met (AND)
BillingAddress__c Is changed {!$GlobalConstant.True}
Action Action RemoteSObjectUpserter
Input Values The group of fields to be considered: Address
The named credential: Connector_Target
Record ID: {!$Record.Id}
API name of the object in the remote org: Account
Example use case: Detect whether a custom checkbox field is selected

Your business may require to use a custom checkbox field on the account, for example, Force_Transfer__c, that controls whether to transfer an account record.

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

Flow Element Option Value
Start Object Account
Trigger A record is created or updated
Conditions All Conditions Are Met (AND)
1: Force_Transfer__c Is changed {!$GlobalConstant.True}
2: Force_Transfer__c Equals True
Action Action RemoteSObjectUpserter
Input Values The group of fields to be considered: Address
The named credential: Connector_Target
Record ID: {!$Record.Id}
API name of the object in the remote org: Account
Update Records Find Records Use the account record that triggered the flow
Conditions None--Always Update Record
Set Field Values Force_Transfer__c {!$GlobalConstant.True}

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. Click to enter Setup, then 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.

Creating Batch Upserter Configurations

According to your flow setup (see Configuring Flow), you must create specific batch upserter configurations.

  1. Click to enter Setup, then 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 expression (as used in an 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.

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. Click to enter Setup, then 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.

    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.

Scheduling Upsert Job

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

  1. Click to enter Setup, then 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. Click to enter Setup, then 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.