Sync Salesforce objects to MoEngage

​

Integration

​

Scope

​

Steps

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

​

Launch the MoEngage app

​

Step 1: Set up a connection

1

Add a new connection

Click Connections > Add New Connection.

2

Enter your MoEngage workspace details

Provide the workspace details.

Field name	Value
Connection Name	Any name for your connection (for example, MoEngage Prod or MoEngage Workspace).
Workspace ID	The Workspace ID of your MoEngage account, available at Settings > Account > APIs > Workspace ID.
Data Key	The Data API Key of your MoEngage account, available at Settings > Account > APIs > Data Key.
MoEngage Data Center	Your MoEngage data center. Read more.

3

Save the connection

Click Save.

​

Step 2: Set up a sync

​

Sync Salesforce Contacts to MoEngage as users

1

Open Map Fields

Click Map Fields.

2

Add a new sync

Click Add new sync.

3

Enter basic sync details

Provide the sync name, source object, and target.

4

Continue

Click Next.

5

Configure data mapping

Configure the data mapping between the two systems:

1. Define the identifier between the two systems. For MoEngage, the identifier name is Customer ID — it can be mapped to any field on the Contact object.
2. Set up mappings for other fields. Enter the MoEngage attribute (these appear as user attributes in MoEngage) and select the Salesforce field to map it to.
3. Click Save.

If you are setting up a sync for a Salesforce object for the first time, the system asks you to deploy the trigger on Salesforce. Click Deploy to continue.

Errors when deploying triggers

Contact testRecord = new Contact(LastName='');

Contact testRecord = new Contact(LastName='John Doe', Email='[email protected]');

​

Formula fields

• Salesforce does not detect underlying data changes for mapped formula fields.
• A change only in the formula’s calculated output does not trigger a sync.

​

Compound fields

• Do not map compound address or location fields (for example, 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 in MoEngage

​

Sync real-time updates

​

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

​

Performing a historic sync

1

Click Sync

Click the Sync button on your sync row.

2

Adjust the batch size (optional)

You can change the batch size depending on your Salesforce settings.The optimal batch size depends on the number of fields you are syncing per record to MoEngage and the overall sync volume.

3

Start the historic sync

Click Sync Historical Data.

​

Monitoring the historic sync

1

Check the Salesforce Apex Flex Queue

Open your Salesforce Apex Flex Queue and 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

Verify the batch has started

If your Flex Queue is empty or has no records from the HistoricalSyncBatch Apex class, the batch has started processing.

3

Check the Apex Jobs Queue

Open the Apex Jobs Queue and find the record submitted by the HistoricalSyncBatch Apex class. You can also search using the Last Historic Sync Apex Batch Job ID of the related sync.

​

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: Suppose 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 they are mapped to a different entity (Events).
• Manual refresh required: The sync status does not update automatically. 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

​

Failed sync queues

​

Exceptions

​

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.
• For example: if two connections map to Contact, then creating a single Contact record generates two Sync Queue records that are 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 or updated while a batch is running are processed in the next iteration.
• If the Flex Queue is full, processing is rescheduled using 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 set in 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, click on the Sync Queue record and view its failed records and related exceptions. You can also manually trigger a retry if an automatic retry is not possible.

​

Error handling

• 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 — occurs if the record does 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 or failure response.
• The Retry button is available only to users with the MoEngage Admin 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 is one of Account Suspended, Authentication Required, BlockedClient, or MissingAttributeError.

​

Behavior

• Real-time sync:
  • Attempts to sync immediately.
  • Updates the record with success or failure.
  • Increments the Retries count if it failed.
  • Logs an exception if the retry fails.
  • Manual retry for real-time syncs works only on the current Sync Queue record and returns a success or failure response.
• Historical sync:
  • Schedules the historical batch job.
  • Displays a Scheduled response to confirm the action.

​

Rate-limit behavior

​

Real-time sync behavior

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

​

Historical sync behavior

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 or 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 or upgrade, MoEngage automatically schedules the Delete Processed Syncs job to run daily at 1:00 AM.
• You can adjust this schedule under Setup > Scheduled Jobs.

​

What it does

• Deletes successful Sync Queue records (and their related failed queues and exceptions) that are older than the Record Deletion Interval (default: 7 days).
• 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

​

Integration

​

Scope

​

Steps

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

​

Launch the MoEngage app

​

Step 1: Set up a connection

1

Add a new connection

Click Connections > Add New Connection.

2

Enter your MoEngage workspace details

Provide the workspace details.

Field name	Value
Connection Name	Any name for your connection (for example, MoEngage Prod or MoEngage Workspace).
Workspace ID	The Workspace ID of your MoEngage account, available at Settings > Account > APIs > Workspace ID.
Data Key	The Data API Key of your MoEngage account, available at Settings > Account > APIs > Data Key.
MoEngage Data Center	Your MoEngage data center. Read more.

3

Save the connection

Click Save.

​

Step 2: Set up a sync

​

Sync Salesforce Contacts to MoEngage as users

1

Open Map Fields

Click Map Fields.

2

Add a new sync

Click Add new sync.

3

Enter basic sync details

Provide the sync name, source object, and target.

4

Continue

Click Next.

5

Configure data mapping

Configure the data mapping between the two systems:

1. Define the identifier between the two systems. For MoEngage, the identifier name is Customer ID — it can be mapped to any field on the Contact object.
2. Set up mappings for other fields. Enter the MoEngage attribute (these appear as user attributes in MoEngage) and select the Salesforce field to map it to.
3. Click Save.

If you are setting up a sync for a Salesforce object for the first time, the system asks you to deploy the trigger on Salesforce. Click Deploy to continue.

Errors when deploying triggers

Contact testRecord = new Contact(LastName='');

Contact testRecord = new Contact(LastName='John Doe', Email='[email protected]');

​

Formula fields

• Salesforce does not detect underlying data changes for mapped formula fields.
• A change only in the formula’s calculated output does not trigger a sync.

​

Compound fields

• Do not map compound address or location fields (for example, 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 in MoEngage

​

Sync real-time updates

​

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

​

Performing a historic sync

1

Click Sync

Click the Sync button on your sync row.

2

Adjust the batch size (optional)

You can change the batch size depending on your Salesforce settings.The optimal batch size depends on the number of fields you are syncing per record to MoEngage and the overall sync volume.

3

Start the historic sync

Click Sync Historical Data.

​

Monitoring the historic sync

1

Check the Salesforce Apex Flex Queue

Open your Salesforce Apex Flex Queue and 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

Verify the batch has started

If your Flex Queue is empty or has no records from the HistoricalSyncBatch Apex class, the batch has started processing.

3

Check the Apex Jobs Queue

Open the Apex Jobs Queue and find the record submitted by the HistoricalSyncBatch Apex class. You can also search using the Last Historic Sync Apex Batch Job ID of the related sync.

​

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: Suppose 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 they are mapped to a different entity (Events).
• Manual refresh required: The sync status does not update automatically. 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

​

Failed sync queues

​

Exceptions

​

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.
• For example: if two connections map to Contact, then creating a single Contact record generates two Sync Queue records that are 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 or updated while a batch is running are processed in the next iteration.
• If the Flex Queue is full, processing is rescheduled using 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 set in 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, click on the Sync Queue record and view its failed records and related exceptions. You can also manually trigger a retry if an automatic retry is not possible.

​

Error handling

• 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 — occurs if the record does 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 or failure response.
• The Retry button is available only to users with the MoEngage Admin 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 is one of Account Suspended, Authentication Required, BlockedClient, or MissingAttributeError.

​

Behavior

• Real-time sync:
  • Attempts to sync immediately.
  • Updates the record with success or failure.
  • Increments the Retries count if it failed.
  • Logs an exception if the retry fails.
  • Manual retry for real-time syncs works only on the current Sync Queue record and returns a success or failure response.
• Historical sync:
  • Schedules the historical batch job.
  • Displays a Scheduled response to confirm the action.

​

Rate-limit behavior

​

Real-time sync behavior

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

​

Historical sync behavior

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 or 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 or upgrade, MoEngage automatically schedules the Delete Processed Syncs job to run daily at 1:00 AM.
• You can adjust this schedule under Setup > Scheduled Jobs.

​

What it does

• Deletes successful Sync Queue records (and their related failed queues and exceptions) that are older than the Record Deletion Interval (default: 7 days).
• 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