Technical Guide
This page contains technical information for experienced Salesforce administrators who are looking for a deeper explanation of the key jobs that run as part of the Emma for Salesforce application.
Below is an overview of the key Emma for Salesforce custom objects (this can be useful when running Salesforce reports).
API Usage
Salesforce has strict governor limits around the use of API calls. The Emma for Salesforce application does not use any API calls when syncing.
There are two types of API calls; inbound and outbound. Outbound calls from Salesforce do not count against governor limits.
All syncing to and from Emma are done via outbound calls. For example, if you are sending 100K emails to Emma via any of our syncing methods (i.e. import wizard, list views etc), these do not count against your salesforce API limit.
The only time the Emma for Salesforce application uses inbound API calls is when you:
a) Use a Salesforce list view to perform a bulk operation. i.e. If you select add contacts to Emma when working from a list view or via the import wizard. This will use up just 1 inbound API call.
b) Navigate to the sync settings page. This will use up just 1 inbound API call.
In general, you should not need to worry about the Emma application using up your inbound API limits.
Background Jobs
The following table provides a list of Emma for Salesforce batch jobs that can run in the background within Salesforce.
BatchDeleteSubscribers
Run as part of the import wizard job if the replace subscribers on list option is enabled under advanced settings. It removes any subscribers from Emma that were not in the import wizard report or list view. If there are a large number of subscribers to remove from Emma, this job can take a long time to complete (if this is the case, you could also consider creating a completely separate subscriber list for the import and deleting the old list - as this could be more efficient).
BatchEmailOptOut
This batch updates the standard Salesforce email opt-out field on the contact and lead records based on the member status. It will opt out any members that are unsubscribed in Emma. This job optionally runs as part of the primary sync between Salesforce and Emma. It runs when the following setting (in the general settings → options) is enabled: ‘Set email opt to true when a contact or lead is unsubscribed’ and a contact or lead is unsubscribed.
BatchSubscriber
Updates Salesforce with the status of any subscribers it finds in Emma. If the create rule is enabled it may create and link new subscribers as contacts or leads in Salesforce along with any mapped fields. This job runs as part of the primary sync between Salesforce and Emma. If it is unable to update Salesforce (due to restricted fields etc), then a message will be logged under maintenance messages.
BatchSubscriberStats
Updates Salesforce members with statistics from the related Emma subscriber list. This job runs as part of the primary sync between Salesforce and Emma.
ConfigBatch
Syncs Emma configuration data with Salesforce. This includes syncing any groups, clients and users with Salesforce. For example, if a user has created a group directly in Emma, then this job needs to have run before it will appear in Salesforce. This job runs as part of the primary sync between Salesforce and Emma.
ScheduleSubscribers
This is a schedulable job that is called from ScheduleSubscriptions when the sync is enabled. It starts the primary sync between Salesforce and Emma.
ImportListViewBatch
Called from the import wizard, details from a Salesforce list view into Emma . It can run import wizard). The process runs under the scheduled user and as such will only have access to the Salesforce records that user can see.
ImportScheduler
Scheduler for running import wizard jobs. It runs hourly under the Salesforce user who requested the scheduled import jobs. This is to ensure the import wizard runs under the owner of the person who started the job (and therefore can only see records available to them).
ProcessAsyncRecords
This is a queueable job that runs if it needs to send Salesforce data to Emma (typically for a single CRUD operation on an account, lead or contact). It can be invoked from a trigger or process builder action.
It will typically only run if there are a) any mapped fields for the subscriber list that the contact or lead is associated with, or b) there is an email change on the contact or lead.
You can prevent the ProcessAsyncRecords from being called by setting 'Disable Salesforce account, contact and lead triggers' to active under sync settings.
ProcessAsyncRecordsBatch
This is a batch job that runs if it needs to send Salesforce data to Emma. It is similar to ProcessAsyncRecords in that it can be invoked under the same conditions. The difference is that it will run when there are multiple records that need to be processed. It works by processing items held in a custom object called Queue_Item__c. It will continue to process these records in atomic transactions. If there are still more items to be processed in the Queue_Item__c object when the batch job completes, it will re-spawn itself.
N.B. If you are running multiple Salesforce process flows that update the same Salesforce object, this can result in multiple ProcessAsyncRecordsBatch jobs running at the same time. To reduce the chance of this happening, where possible, structure your Salesforce process flows to update the same Salesforce object.
You can reduce the number of ProcessAsyncRecordsBatch from being run by setting 'Disable bulk triggers for account, contact and lead triggers' to active under Sync Settings. This will result in only the first record in a transaction being processed.
RefreshSubscribers
Clears out the Subscriber List Member (em4sf__Subscription__c) object. It’s called when a full refresh is requested a full re-import Emma data into Salesforce.
ReportToListBatch
Called as part of the import wizard, this imports subscriber details from a Salesforce report into Campaign Monitor. It can run as a once off manually initiated job or via a scheduled process (if the user has configured this via the import wizard).
Process Builder Invokable Action
The Salesforce Process builder is a powerful tool and when combined with Emma for Salesforce, it provides fine grain control over sending targeted transactional emails to subscribers.
The trade off comes with the complexity of setting up and debugging processes. To help troubleshooting emails not sending, you can test the last step in the process builder action with the code below (i.e. try running the code in the Salesforce developer console). This is essentially the code that is called when you use the smart email invokable action in the process builder. If the code below works, then any problems are likely to be related to the fact that the invokable action is not being triggered (i.e. a status on a field used in your Salesforce process builder logic may not be correct etc).
You can also test your Salesforce process by creating a dummy task or updating a value on an object. The code below will help check if the correct Ids were used in the smart email invokable action in the process builder.
When selecting the object to base the process on in process builder, avoid checking "Recursion - allow process to evaluate a record multiple times in a single transaction?" - this can cause issues with Salesforce governance limits as the action may be called multiple times.
Salesforce domain name
The Salesforce Process builder is a powerful tool and when combined with Emma for Salesforce, it provides fine grain control over sending targeted transactional emails to subscribers.
If you are using Salesforce Lightning but don't have a domain set up, you may receive the error similar to this: NO CONTROLLER named js://wbsendit.pagination found
Salesforce requires a domain to be set up in order to use lightning components (which are used as part of the Emma for Salesforce application).
Setting up a Salesforce domain will remove this message.
This video walks you through setting up a domain name.
Sandboxes
You can install our integration in one or more sandboxes. You can also refresh a sandbox and our application will be copied across below is some more detailed information.
How to install in a sandbox
Go to our Salesforce AppExchange listing.
Click the Get it now button.
If you are not already logged in you will be prompted to do so.
Choose Sandbox.
Select I have read and agree to the terms and conditions, then click Confirm and Install.
Choose whether to install for admins only, all users or specific profiles. We recommend you select Admins only and once installed give users access via our permission sets.
Click Install.
Select Yes, grant access to these third-party websites then click Continue.
Sandbox refresh
When you start a sandbox refresh a copy of your installed applications will also be copied. This will include Emma for Salesforce and there are some important points below to consider.
- When strongley recommend not to connect any sandbox to your live Emma account.
- When a sandbox refresh happens we use a standard Salesforce process to disconnect Emma from Salesforce.
- You can also manually run a process before or after the sandbox refresh to clear out connection settings.
- When refreshing either a full or partial sandbox data from our objects can be copied from production.
We don't recommend connecting a sandbox to your live Emma account. Changes made in a sandbox can incorrectly update your Emma data.
Sandbox conflicts
As mentioned above when refreshing a Salesforce sandbox, there may be some settings carried across from production. It is worth noting we do have some code that runs as part of the refresh to avoid this. But in very rare scenarios, the code can be conflicted with. So to help we have two options to return settings to their default state.
1. Before starting the sandbox refresh
When refreshing the Salesforce sandbox, there is now an option to run a post-installation script. You can enter the value SandboxRefresh this will execute our code to clear out the settings.
2. After the sandbox has been refreshed
a. Open the Salesforce developer console (developer console-->debug-->open execute anonymous window).
b. Enter in EM4SF.resetSettings()();
c Press Execute, this will take a few seconds to execute.
Either option will reset the main settings, after performing these steps you will need to connect to Emma.
How to test in a sandbox
When you have our product in a sandbox we recommend connecting it to a test Emma account.
If you have questions on which Emma account to setup please contact Emma directly - https://help.myemma.com/s/
uninstall process
Before uninstalling any Salesforce application you need to remove dependencies.
If you are on a paid for plan you first need to contact us to cancel.
Generally only a Salesforce administrator can uninstall.
Automated uninstall process
We have built a fully automated uninstall process. However, it is possible that this flow may not work, particularly if our application has been customized or it runs into a conflict. If this happens there are Manual steps below.
To start the automated process click one of the buttons below depending on what type of Salesforce environment you are working with.
Manual install process
There are two dependencies you need to remove, page layouts and permission sets. Start by removing page layouts.
In Salesforce go to the Emma admin app.
Click on the General settings tab.
Select the Maintenance option.
From here click Remove layouts.
Next you need to remove users from our two permission sets.
In Salesforce go to the Emma admin app.
Click on the General settings tab.
Then select User security.
Search and select for the user(s) you want to assign the permission set to.
Click the Edit permissions button.
Select the None and click Assign permission set.
Finally with all dependencies removed you can now uninstall the package.
Click Setup.
In the Quick Search type installed.
Next to Campaign Monitor for Salesforce, click Uninstall.
Choose whether or not to save a copy of the package's data.
Select Yes, I want to uninstall this package and permanently delete all associated components.
Click Uninstall.
The uninstall process takes some time, once completed you will receive an email from Salesforce.
