Connecting Salesforce to Medallia via API
Medallia for Salesforce communicates with Medallia Experience Cloud via secure APIs. These instructions detail how to setup the secure connection.
Required information
Before setting up the connectivity for Salesforce to send data to Medallia Experience Cloud, the Medallia administrator must configure the Medallia Experience Cloud instance to authorize inbound communication. Once that is done, the Medallia administrator will provide the information in the table below, which you will need to complete the process.
| From Medallia | Value | |
|---|---|---|
| OAuth (authorization to connect to the instance) | Client ID | salesforce_oauth |
| Client Secret | Password for the Client ID. | |
| Token URL | OAuth token endpoint for the Medallia Web reporting instance. The URL looks similar to this: | |
| Medallia Instance URLs | Base URL | URL to the production Medallia Web reporting instance. The URL looks similar to this: |
| Sandbox URL | (optional) URL to the sandbox instance | |
| Services (web feeds) | Case closure | sfdc_create_survey_case_closed |
| Opportunity Won | sfdc_create_survey_opportunity_won | |
Notes:
-
Instance URLs — The address to access Medallia Web reporting. You will use these to Allow-list the instance URL(s).
-
OAuth — OAuth provides authorization to applications that make connections to Medallia Experience Cloud. You will use this information to Configure the API connection.
-
Services (webfeed endpoints) — Web Feeds are the in-bound endpoints for passing data to Medallia Experience Cloud. The default web feed endpoints are already configured; however, the company may have additional endpoints depending on the use cases.
-
When there are additional endpoints, configure new processes in Salesforce. Use a web feed endpoint as an input in a custom process to specify how information will be passed to Medallia Experience Cloud.
-
For Feedback Programs, configure a unique endpoint by entering the value in the Program Service field.
-
Allow-list the instance URL(s)
Tell Salesforce to allow Medallia for Salesforce to connect to Medallia Experience Cloud.
-
In Salesforce Setup, navigate to the Remote Site Settings page.
-
Locate Medallia in the list of remote sites and click Edit (on the same row).
-
In the remote site editor, set the Remote Site URL to the Base URL provided by the Medallia administrator. Enter the production URL.
-
Click Save.
-
If you also have a sandbox URL:
-
Switch the production URL for the sandbox URL.
-
Optionally, update the Description.
-
Turn on Active.
-
Click Save.
-
Configure the API connection
When making the connection to Medallia Web reporting, the application uses OAuth authorization. To complete this configuration step, you need the information previously provided by the Medallia administrator.
In Salesforce, click the Medallia Setup tab.
-
For Step 1 of the API Connection screen, enter:
-
Base URL — The address provided by the Medallia administrator.
-
OAuth Token URL — The token endpoint provided by the administrator and where the application can get an OAuth token for the Experience Cloud instance.
-
-
Click Set URLs.
-
For Step 2, enter the credentials:
-
Client ID
-
Client Secret
-
-
Click Connect to Medallia.
A message indicates you are connected to Medallia's API.
"You are connected to Medallia's API. To reconnect, click the 'Disconnect' button below."
Troubleshooting:
-
Verify the URLs, including the domains (such as .com, .eu, .ca, etc.)
-
Verify the Client ID and Secret
-
Refer to Troubleshooting for Salesforce Administrators for more information on root cause issues.
-
For Medallia Administrators: In Medallia Web reporting Setup, if the Client ID is configured to Enforce IP allow-listing:
-
In Medallia Web reporting Setup navigate to the Company > Users > Users > Logon Restrictions screen and verify the Salesforce IP addresses are in the End User IP allow-list list.
-
Optionally turn off Enforce IP allow-listing if it is not required.
-
Configuring the Logging service
Use the Logging service to leverage Platform Events.
-
In Salesforce Setup, search "Custom Metadata Types" and open it from the search results.
-
Click Manage Records next to the Log Settings entry.
-
In the Log_Settings list view, click Edit next to Default.
-
In the Log_Settings pane, the default values are:
-
Enable Logging is selected.
This allows the Logging service to capture logs generated from the managed package. Select this option to capture logs for troubleshooting and support purposes.
-
Enable Pruning is selected.
This allows the Log Pruning service to automatically delete log records when the Max Number of Logs value is reached.
-
Bypass Platform Events is not selected.
When you select this option, Platform Events are bypassed when creating the record in the Log Object. Note that in this scenario, created records are rolled back when there are transaction failures. When you do not select this option, Platform events are triggered to write the record in Log Object. Do not select this option unless otherwise advised by your Medallia expert.
-
Log to System Debug is not selected.
When you select this option, the Logging service also writes to debug logs while running a Debug Trace on a user account.
-
Max Number of Logs is set to 1,000.
The maximum number of log records are retained at any given time. This can be tuned to your needs.
-
Interfaced Class Order is set to "LogToObject".
Do not modify this setting. This functionality may change in a future release.
-
Configuring the Queueing service
Use the Queueing service to leverage SFDC platform features:
-
In Salesforce Setup, search Custom Settings and open it from the search results.
-
Click Manage next to Medallia Settings.
-
For new installations, click New.
-
For existing installations, click Edit.
-
Configure these parameters to manage the Queueing service:
-
Tab URL — Medallia Web reporting URL defined when enabling an iframe to Medallia reporting from the Salesforce UI. For existing installations, this field is already populated. See Enable experience reporting in Salesforce to learn more.
Record size — Use this setting to configure the queue size. Its default value is "10", which means each queue job will contain a maximum of 10 invitations. This setting ensures maximum compatibility with custom implementations, but it should be fine-tuned to the needs of each organization:
-
If you notice there is a lengthy delay between Invitation creation and Invitations being sent to Experience Cloud, increase the record size value to process larger volumes for each queue transaction.
-
If you know the average volume of Invitations that are generated per minute, increase the record size value to match; however, note that processing a larger number of Invitation records per job can reduce the overall time between the creation of Invitation records and when Invitation records are sent to Experience Cloud.
Note: SFDC Apex CPU Time Limits apply to queue processing. If you experience an Apex-CPU-Time-Limit-Exceeded error during queue processing, reduce the record size value.
-
-
Add To Program Contact Fieldset — Determines the data payload that Medallia receives. For existing installations, this field is already populated. See Send data from Salesforce to Medallia to learn how to configure or modify this fieldset.
Number of Invitation Retries — Sets the number of times the Queueing service retries processing queue items. The default value is "5". After 5 retries, the queue item record is marked as "Failed" and the Queueing service does not retry to process the items in that queue item.
-
Minimum Queueable Delay in Minutes — Sets the minimum delay between queueable transactions. It allows the Queueing service to check queueable jobs against the
Duplicate Signature Checkclass to ensure duplicate invitations are not created or sent. The default value (in minutes) is "1". Use higher values when duplicate invitations are being created.The value provided for this setting defines the period in minutes it takes the Queueing service to execute each queue item.
Important: This also delays the sending of records from SFDC to Experience Cloud by the number of minutes defined for this parameter. -
Notification Email Recipient — Enter the email address of a shared inbox or group email monitored by your Salesforce administrators to ensure queue processing error emails are not missed. By default, this value is null on both new installs and upgrade installs. When you do not enter a recipient, the default behavior is to send an email notification to the email address associated with the first administrator user found when querying users in the Salesforce org.
-
Queue Processing — This parameter controls whether the queue processor is active and processing queue item records through to the Medallia API endpoint. When it is unchecked, queue processing is inactive and no records are sent to Medallia. On new installs, the default value is set to “True”. On upgrade installs, the value is “False” and must be changed to "True" to process the invitation queue.
-
-
Click Save.
Resuming queue processing after fatal Medallia API error
When the Medallia API returns an HTTP 429 or 500 error code, the queue processor is turned off until an administrator activates it. An email is sent to the designated recipient.
Additionally, an entry is created in the Logs__c object with the message: “The Medallia API returned Error Code -### when attempting to send the Queue Items. Queue processing has stopped. Please contact Medallia Support.”
To resume queue processing after you have verified that the Medallia API is up and the errors have been resolved:
-
Navigate to the Medallia Setup app from the App Launcher.
-
Click Restart Queue Processing.
Restriction: This action must be performed by an Administrator user with the Medallia Admin permission set.Tip: The Restart Queue Processing button is only active if the queue processor has stopped due to an error or when the Queue Processing checkbox in the custom Medallia settings is not selected.
Deleting old queue item records to force the queue to resume
When the Medallia queue processor fails to process queue item records, the queue can back up and enter a state where queue items are not processed in a timely fashion. To remedy this situation, create a batch job to be called on-demand from the Developer Console to delete queue item records, or execute a code snippet to delete the queue item records as a non-batched one-time run.
To create a delete-queue-item batch:
-
Create a batch class.
-
Open the Developer Console, select New, then select Apex Class.
-
Paste the code below into the code editor.
global class MedalliaDeleteQueueItemBatch implements Database.Batchable<SObject> { // Select all medallia_xm__QueueItem__c records global Database.QueryLocator start(Database.BatchableContext BC) { return Database.getQueryLocator('SELECT Id FROM medallia_xm__QueueItem__c'); } // Batch the record deletion operation global void execute(Database.BatchableContext BC, List<medallia_xm__QueueItem__c> scope) { try { // Delete records Database.delete(scope, false); } catch (Exception e) { // Log Error System.debug('Error deleting records: ' + e.getMessage()); } } //Finish method after all batches process global void finish(Database.BatchableContext BC) { System.debug('Batch processing completed.'); } } -
Click Save.
To execute the Medallia delete-queue-item batch job:
-
Open the Developer Console.
-
Open the Debug > Execute Anonymous screen.
-
Paste the code below into the code editor.
MedalliaDeleteQueueItemBatch delBatch = new MedalliaDeleteQueueItemBatch(); Database.executeBatch(delBatch, 200);Tip: "200" in the code above represents the batch size. Adjust this value according to your needs. -
Click Execute.
To execute the non-batchable queue-item record deletion:
-
Open the Developer Console.
-
Open the Debug > Execute Anonymous screen.
-
Paste the code below into the code editor.
List<medallia_xm__QueueItem__c> queueItems = [SELECT Id FROM medallia_xm__QueueItem__c LIMIT 10000]; if (!queueItems.isEmpty()) { try { delete queueItems; System.debug('Deleted ' + queueItems.size() + ' queue items.'); } catch (DmlException e) { System.debug('An error occurred: ' + e.getMessage()); } } else { System.debug('No queue items found to delete.');} -
Click Execute.
