Integration 

Scope 

Context	Support status
Sync standard salesforce entities such as Contacts, Leads, Accounts, Opportunities, etc to MoEngage as users or events	Supported
Sync custom salesforce objects to MoEngage as users or events	Supported
Support for all standard salesforce fields- String, DateTime, Numeric, Formula fields, Object types (such as Salesforce standard geo location field object)	Supported
Send historical data sync to MoEngage	Supported
Real time data sync on new record creation or record updates	Supported
Create new attributes on MoEngage while setting up the data sync	Supported
Sync linked entities (relationships between entities) to MoEngage	Not supported In the current scope, we sync only the IDs of the linked fields. The whole linked object is not synced.

Steps 

The integration is divided into two major steps 

1. Connections - Connections is the authorisation to your MoEngage workspace. You can connect multiple MoEngage workspace to a single Salesforce instance. 
2. Syncs - Sync is a job that runs in real time to send the specific data between the two systems. It includes your sync type (MoEngage to Salesforce or Salesforce to MoEngage), entities to be synced, and data mapping. 

Other minor sections include Error logs and Exceptions - this is particularly important to debug in case the data sync is not working. 

Launch MoEngage App

Click on “App launcher”, enter “MoEngage”, and then select “MoEngage App”. 

Step 1: Set up a connection 

1. Click Connections >> Add New Connection
2. Enter your MoEngage workspace details 
   

Field name	Value
Connection Name	You can give any name to your connection - eg. "MoEngage Prod" or MoEngage Workspace
Workspace ID	The Workspace ID of your MoEngage account is available in Settings -> App Settings -> APIs >> Workspace ID
Data Key	The Data ID of your MoEngage account is available in Settings -> App Settings -> APIs >> Data key
MoEngage Data center	This is your MoEngage data center. Read more

     

          3. Click Save.

Step 2: Setup a sync

For this document, we will focus on this example - Sync Salesforce Contacts to MoEngage as Users. You can follow the similar process for event sync. 

Sync Salesforce Contacts to MoEngage as Users 

1. Click Map Fields.
   
2.  Click Add new sync 
   
3. Enter basic sync details   
   
4. Click Next 
5. Configure data mapping between the two systems 
   1. Define the identifier between the two systems. For MoEngage, the identifier name is Customer ID. But it can be mapped to any field from the Contact object. 
      
   2. Setup mappings for other fields. Enter the MoEngage attribute (these will show up as user attributes on MoEngage) and select a Salesforce Field that the MoEngage attribute needs to be mapped to. 
      
   3. Click Save.

Any new contacts created or existing contacts updated will start showing up on your MoEngage dashboard. 

Note-
If you are setting up a sync of your Salesforce Object for the first time, the system will ask you to deploy the trigger on Salesforce. Click Deploy to continue. 

Error in deploying triggers

If your initial trigger deployment fails, it's often due to custom validation rules you've set up on the Salesforce Object you're syncing (e.g., rules on the Contact or Lead object). To deploy successfully, the system needs to create a test record, and that test record must pass your organization's specific validation rules.

When the deployment fails, a modal will appear asking you to provide test data:

1. Analyze the Snippet: The system will pre-populate a code snippet with the minimum required fields for that Salesforce Object.

2. Add Your Custom Fields: You must modify this snippet to add any other fields and corresponding sample values that are required by your validation rules.

Consider the following example:

Contact testRecord = new Contact(LastName='')

If your Salesforce has a few validation triggers on the Contact object that check for a value of Last Name and the correct format of Email, you should modify the sample line to:

Contact testRecord = new Contact(LastName='John Doe', Email='john.doe@example.com')

Providing this complete test data ensures the deployment's test class can pass all your custom logic. Once you have modified the snippet to satisfy all your validation rules, click Update and then redeploy the Sync Trigger.

Formula Fields

• Salesforce does not detect underlying data changes for mapped formula fields.
• A change only in the formula’s calculated output will not trigger a sync.
• Recommendation: Map the source fields used in the formula instead.

Compound Fields

• Do not map compound address/location fields (e.g., MailingAddress) directly.
• Instead, map their individual components:
  • MailingStreet
  • MailingCity
  • MailingState
  • MailingPostalCode
  • MailingCountry
• This ensures accurate syncing with the corresponding MoEngage attributes.

Step 3: View profiles on MoEngage

1. Navigate to Segment >> Create segment
2. Search for the user via email id or any other identifier. And you will see the data flowing into MoEngage. 

Sync real-time updates

By default, new sync configurations are automatically enabled for real-time updates. This means any modification to a mapped field of an existing record within the synced Salesforce object will trigger an update to MoEngage.

To deactivate real-time syncs, just click on the Deactivate button next to the Sync.

Field Change Detection

• Real-Time Sync is triggered when a mapped object record is created or when an existing record has at least one mapped field changed.
• Updates to unmapped fields alone do not trigger a sync to MoEngage.

Sync historical data

You can trigger a historic sync of your existing data at any point. This is useful in case you want to backfill data in MoEngage.

Performing a historic sync

1. Click on the "Sync" button against your sync row. 
   
   
   
   
2. [Optional] You can change the batch size depending on your Salesforce settings. :
   
   An optimal Batch Size depends on the number of fields you are syncing per record to MoEngage and the overall volume of your syncs.
   
   
3. Click "Sync Historical Data".

Monitoring the Historic Sync

After starting a historic sync, you can track its progress by observing the status displayed next to the sync configuration:

Here’s what each status means:

Status	Description
Sync	This status indicates that a historic sync has not yet been performed for this specific object. It is the default state before the first sync is initiated.
Sync Scheduled	You've started the sync, and it's in the queue waiting to be processed by Salesforce.
Sync Processing	The sync has started, and data is actively being sent to MoEngage.
Sync Successful	The process is complete, and all records were successfully sent from Salesforce. MoEngage will now process this data.
Sync Partial Success	The process is complete, but some records failed to send due to errors. You should check the error logs to investigate.
Sync Failed	The process is complete, but no records were sent to MoEngage due to a critical error.

 

To see the latest progress of your Historic Sync, you can click on the "Sync Processing" button. This will take you to the corresponding Sync Queue record, for which you can see the detailed progress and exceptions (if any).

Each Historic Sync record (Syncs -> All Syncs -> Select your Sync Name) also contains some metadata at your disposal:

Field Name	Description
Last Sync Date Time	The time at which the last Historic Sync was added.
Last Historic Sync Apex Batch Job ID	The Batch Job ID of the Salesforce Apex Job. Using this ID, you can view the real-time progress of how many batches are processed within the last Historic Sync.
Last Historic Sync Batch Raw Job ID	The full Job ID of the Salesforce Apex Job generated internally.
Last Historic Sync Queue ID	The Sync Queue ID of this Historic Sync. Using this ID
Last Historic Sync Queue Record	Use this link to view details of the Sync Queue Record for the last Historic Sync. You can then view the related exceptions and failed records for this sync and monitor the overall progress of this sync in detail.
Last Historic Sync Status	The status of the most recent sync attempt for this configuration. (transitions as: Scheduled → Processing → Successful / Failed / Partial Success)

 

You can also monitor the current progress of your Historic Sync by following these steps:

1. Check your Salesforce Apex Flex Queue to ensure the historic sync is not in the Holding state. Search for the Apex Class HistoricalSyncBatch. If you find it in this state, you can reorder the batch to prioritize MoEngage.
2. If your Flex Queue is empty or has no records from the HistoricalSyncBatch Apex Class, the Batch has started processing.
3. Head to the Apex Jobs Queue and see a record submitted by the HistoricalSyncBatch Apex Class (you can also search with "Last Historic Sync Apex Batch Job ID" of the related Sync):

Check the following columns:

Column Name	Description
Status	Status of the Historic Sync. If this is Processing, the data sync is in progress. When this is Completed it means that all the records have been sent to MoEngage for processing. This does not ensure the full delivery. MoEngage can still reject your records based on various factors.
Batches Processed	The number of batches sent to MoEngage. If this is less than the Total Batches, the sync is in progress.
Failures	This states the number of batches that have failed to be sent to MoEngage.
Apex Class	Ensure that this is HistoricalSyncBatch

 

Important Points to Remember

• One Sync Per Entity Type: You can only run one historic sync at a time per MoEngage entity type (one for Users and one for Events).

  • Example: Imagine Salesforce Contacts and Leads are both mapped to MoEngage Users, while Salesforce Opportunities and Deals are mapped to MoEngage Events.

  • If you start a sync for Contacts (a User sync), you cannot start another sync for Leads until the first one completes.

  • However, while the Contacts sync is running, you can still start a sync for Opportunities or Deals, because it is mapped to a different entity (Events).

• Manual Refresh Required: The sync status does not update automatically. You must click the "Refresh" icon or manually refresh the page to see the latest status.

• Status of Last Sync: The status shown always reflects the outcome of the most recent sync attempt for that specific configuration.

• New Sync Start: You can start a new Historic Sync only when the status of the most recent sync for that specific configuration is not "Sync Scheduled" or "Sync Processing".

Sync Queues

To ensure your data syncs reliably and efficiently, the MoEngage App processes all transfers through an intelligent Sync Queue. This system automatically optimizes performance, minimizes errors, and uses smart logic to retry failed attempts.

Every sync, whether Historic or Real-Time, is managed through this queue. You can visit the Sync Queue to monitor the status of all your jobs, from scheduled and active to completed. By default, Sync Queue comes with two Views: "Real Time Syncs" and "Historical Syncs".

 

 

Each Sync Queue Record comes with additional information to help you check the status of your Syncs.

You can check the following fields for more information:

Field Name	Description
Sync	The name of your sync mapping. (eg: "Leads to MoE Users")
Historical Sync Batch Size	This is the number of records that were sent to MoEngage per batch. This field is only populated for Historical Syncs.
Status	The current status of your sync.
Number of retries	The number of times Salesforce tried to sync this batch/record.
Record Type	The type of sync this was initiated from: Historical Sync Real-Time Sync
Sync Status	The Last Known Status of the Sync configuration. If this is Disabled from the "Syncs" page, then all further syncs will not be processed.
Parent Sync Queue	Which Sync did this record belong to? This is often populated if the sync failed at the first attempt.
Error Type	The Error type which was encountered during the sync.
Last Processed Record Id	The record ID of the last successfully synced record of a Historic Sync. This is useful to restart Historic Syncs from their last successful record sync. This field is only populated for Historical Syncs.

 

Each Sync Queue Record also has the following Related records:

Failed Sync Queues

These are subsequent Sync Queue Records created for records that have failed to previously sync and will be retried again in the future.

Exceptions

These contain individual Exception logs of why a particular Record failed to sync to MoEngage. It also captures logs for records coming in from MoEngage that failed to be updated within Salesforce. Each Exception Record has the following information:

Field Name	Description
Exception	The ID of this Exception Record.
Apex Class	The Exception was triggered as part of which Sync (Real-time/Historical Sync to MoEngage, or from MoEngage to Salesforce via Streams)
Sync Queue	Links to the parent Sync Queue that processed this record. This field is only populated for syncs from Salesforce to MoEngage.
Record Id	The ID of the record (Contact/Lead/etc) which failed to sync because of this Exception. You can click on the Record ID to go to the corresponding record within Salesforce.
Error Message	The error that was encountered with this Exception.
MoEngage Error Message	The actual response given by MoEngage for this Exception.
Salesforce Error Message	The error triggered by Salesforce during inbound syncs (MoEngage to Salesforce).

 

How Real Time Sync Works

On Create

• When a new record is created on an object with active mappings, MoEngage generates one Sync Queue record per active connection for that object.
• Example: If two connections map Contact, then creating a single Contact record generates two Sync Queue records, both sent to MoEngage.

On Update

• A Sync Queue record is created only if at least one mapped field changes.
• Updates to non-mapped fields do not create Sync Queue records.

Processing

• When a Real Time Sync is triggered, MoEngage runs a MoEngageSyncQueueBatch in the background, which picks up pending real-time syncs and processes them together.
• The default batch size comes from Sync Queue Batch Size (default: 20).
• New records added/updated while a batch is running are processed in the next iteration.
• If the Flex Queue is full, processing is rescheduled using the Sync Queue Scheduler Time (default: 5 minutes).
• The "full" threshold is configurable via Flex Queue Limit (default: 50).

Historical Syncs

• A Historic Sync is added to the Sync Queue as soon as it is scheduled.
• If the Salesforce Flex Queue is full, Historical Sync jobs are rescheduled after the delay interval set in the "Historical Sync Scheduler Time." (default 5 minutes).

Processing

• If a few records of the Historical Sync fail, related Exception Records and Sync Queue records are created.
• For each Historic Sync, you can click on the Sync Queue Record and view its failed Records and their related Exceptions. You can also manually trigger a retry in case an automatic retry is not possible.

Error Handling

Certain errors cause the batch to abort and require different retry approaches:

• Authentication Required → Batch aborts; requires manual retry.
• BlockedClient → Batch aborts; requires manual retry.
• Account Suspended → Batch aborts; requires manual retry.
• Unsupported Media Type → Batch aborts; requires manual retry.
• Server Error → Batch aborts but is automatically retried (within retry limits).

Retries

• Each queue item allows up to 4 automatic retry attempts (including the first attempt).
• No automatic retries occur for the following errors (these require user action):
  • Account Suspended
  • Authentication Required
  • BlockedClient
  • MissingAttributeError - This occurs if the record(s) do not have a value for Customer ID.
• If a payload error occurs, the batch size is halved on each retry until either:
  • The batch succeeds, or
  • The size reduces to 1

Manual Retry

• Manual retry for Real Time Sync applies only to the current Sync Queue record.
• MoEngage returns a clear success/failure response.
• The "Retry" button is available only to users with the MoEngage Admin User permission set.
• The Manual Retry option becomes visible when all the following conditions are met:
  • • Condition A: Status = Failed or Partial Success, Retries ≥ 4, and Sync Status = Active.
    • Condition B: Error Type ∈ {Account Suspended, Authentication Required, BlockedClient,
      MissingAttributeError}.

Behaviour

• Real-Time Sync:
  • Attempts to sync immediately.
  • Updates the record with Success or Failure.
  • Increments the Retries count if failed.
  • Logs an Exception if the retry fails.
  • Manual retry for Real-Time works only on the current Sync Queue record and returns a success/failure response.
• Historical Sync:
  • Schedules the historical batch job.
  • Displays a scheduled response to confirm the action.

Rate Limits Behaviour

Real-Time Sync Behaviour

1. Processing for the affected connection/object is paused.
2. Syncs automatically resume after the same back-off sequence once limits clear.

Historical Sync Behaviour

1. The running batch is aborted immediately.
2. Back-off retries follow the sequence: 1 → 2 → 4 → 8 → 10 minutes.
3. Any new historical syncs for the same connection/object remain in the Scheduled state.
4. The retry count for historical syncs is automatically reset to 0 once the configured limits are cleared.

Delete Processed Syncs

Scheduling

• On install/upgrade, MoEngage automatically schedules the Delete Processed Syncs job to run daily at 1:00 AM.
• You can adjust this schedule via: Setup → Scheduled Jobs.

What It Does

• Deletes Successful Sync Queue records (and their related failed queues & Exceptions) that are older than the Record Deletion Interval (default: 7 days).
• The cleanup is based on the Last Modified Date field.

(Admin Note) Package-Install Limitation

• If the packaging user does not have full access to run the schedule under the desired context, the job may fail to execute properly.
• Solution: Reschedule the job under an Admin user to ensure it runs with proper privileges.

 

 

 

Frequently Asked Questions