The office phone rang all day. None of it reached Salesforce.

The RingCentral managed package is an Open CTI softphone. It logs calls handled in a signed-in user's browser tab, not calls that ring desk phones. Why it never saw the office line, the CTI Adapter URL that showed "This content is blocked" in a sandbox, and the server-side sync that replaced it: JWT auth through an External Credential, twelve scheduled jobs, upsert on an external ID, SOSL IN PHONE FIELDS matching, and the deploy lock a running schedule puts on its own code (corrected: Type.forName did not lift it).

The office phone rang all day, and none of it reached Salesforce.

The phone integration was installed. The admin settings said calls would be logged automatically. Someone called the main number from a cell phone as the first live test, the desk phone rang, the call was answered, and the softphone’s call history said “No calls yet”.

The integration everyone assumed would handle it only watches calls made from a browser. Nobody at this company makes calls from a browser.

What the managed package actually is

At Doorvana the plan was the obvious one: install RingCentral for Salesforce, the vendor’s managed package, and let it log every call to the office line on the right customer. That was my assumption going in.

The package is an Open CTI softphone. Its Setup Assistant creates a Call Center, the softphone lives in the utility bar, and its admin UI has settings that read like exactly what was wanted: “Auto create call log on: ringing” and “Auto create SMS log”. A test call placed from the softphone would have logged perfectly.

But that logging runs in the softphone, inside a signed-in user’s Salesforce tab. The office’s main number is routed by RingCentral to an extension that rings physical desk phones. Those calls never pass through a browser, so the package never sees them. And the client did not want the softphone at all: nobody here calls from Salesforce.

The sandbox detour: “This content is blocked”

Before that test could even run, the softphone panel in the sandbox showed:

This content is blocked. Contact the site owner to fix the issue.

The Call Center the Setup Assistant generated had its CTI Adapter URL pointed at a production-style …--rcsfl.visualforce.com host. In a sandbox with enhanced domains, that redirects to a My Domain that does not exist. Pointing the CTI Adapter URL at the …--rcsfl.sandbox.vf.force.com host fixed it. Worth knowing, but it was fixing a component that turned out not to be the answer.

Pulling the call log from the server instead

If the phones will not come to Salesforce, Salesforce goes to the phone system. RingCentral keeps an account-wide call log whatever device answered, so the replacement is a scheduled server-side sync:

  • a RingCentral private REST app using the JWT auth flow, with Read Call Log, Read Accounts and Read Messages;
  • an External Credential and Named Credential called RingCentral, with the client ID, secret and JWT entered on the principal in Setup and never in source;
  • a Queueable that pulls /restapi/v1.0/account/~/call-log?view=Detailed and each extension’s message-store for texts and voicemail, and upserts a custom Phone_Activity__c;
  • a matcher that links each row to a Contact, open Lead or Account and logs a completed Task.

The secrets never appear in Apex. RingCentral issues its own JWT, so Salesforce’s built-in JWT Bearer protocol (which signs a JWT itself) does not fit; the External Credential uses a custom protocol and the token request merges the credentials in at callout time:

force-app/main/default/classes/RingCentralClient.cls

request.setEndpoint(NAMED_CREDENTIAL + '/restapi/oauth/token');
request.setHeader(
    'Authorization',
    '{!\'Basic \' & BASE64ENCODE(BLOB($Credential.RingCentral.ClientId & \':\' & $Credential.RingCentral.ClientSecret))}'
);
request.setBody(
    'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion={!$Credential.RingCentral.JwtToken}'
);

The Named Credential allows merge fields in the header and body, and does not generate its own Authorization header:

force-app/main/default/namedCredentials/RingCentral.namedCredential-meta.xml

<allowMergeFieldsInBody>true</allowMergeFieldsInBody>
<allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
<generateAuthorizationHeader>false</generateAuthorizationHeader>
<namedCredentialType>SecuredEndpoint</namedCredentialType>

Every five minutes is twelve jobs

A cron expression on a Schedulable fires at most hourly, so a five-minute cadence is twelve scheduled jobs, one per five-minute mark, each enqueuing the sync:

force-app/main/default/classes/RingCentralSyncSchedule.cls

public static void scheduleEveryFiveMinutes() {
    for (Integer minute = 0; minute < 60; minute += 5) {
        String name = JOB_PREFIX + String.valueOf(minute).leftPad(2, '0');
        System.schedule(name, '0 ' + minute + ' * * * ?', new RingCentralSyncSchedule());
    }
}

The Queueable checks AsyncApexJob and returns early if another sync is already processing, so a slow run never overlaps the next one.

Re-reading on purpose, without duplicates

A call only reaches RingCentral’s call log once it ends, so a long call can start before the newest one already stored. The sync therefore reads from the newest stored Start_Time__c minus a two-hour overlap, and makes the overlap harmless with an upsert on an external ID:

force-app/main/default/objects/Phone_Activity__c/fields/RC_Id__c.field-meta.xml

<fullName>RC_Id__c</fullName>
<description>RingCentral call-log record id (call:...) or message id (sms:...). Upsert key, so a re-pulled call never duplicates.</description>
<externalId>true</externalId>
<type>Text</type>
<unique>true</unique>

force-app/main/default/classes/RingCentralSyncQueueable.cls

Database.UpsertResult[] results = Database.upsert(
    activities, Phone_Activity__c.RC_Id__c, false, AccessLevel.SYSTEM_MODE
);

The same overlap is what picks up recordings and voicemail transcripts that arrive after the first pull. A field is only set when RingCentral sends it, so a later pull without the recording never blanks one already stored.

Matching a number to a customer

Phone numbers are stored however people typed them. The matcher normalizes every number to ten digits and finds candidates with SOSL IN PHONE FIELDS, which ignores formatting:

force-app/main/default/classes/PhoneActivityMatcher.cls

String sosl = 'FIND {' + String.join(keys, ' OR ') + '} IN PHONE FIELDS RETURNING '
    + 'Contact(Id, AccountId, OwnerId, Phone, MobilePhone, HomePhone, OtherPhone, AssistantPhone ORDER BY LastModifiedDate DESC), '
    + 'Lead(Id, OwnerId, IsConverted, Phone, MobilePhone, Secondary_Phone__c WHERE IsConverted = false ORDER BY LastModifiedDate DESC), '
    + 'Account(Id, OwnerId, Phone ORDER BY LastModifiedDate DESC)';

When several records share a number, a Contact (an existing customer) wins over an open Lead, which wins over an Account. A match logs a completed Task with TaskSubtype = 'Call', CallType and CallDurationInSeconds, so it shows in the activity timeline like any logged call. A missed call or voicemail from the last day also opens a call-back Task; older ones do not, so a backfill of last week’s history cannot flood everyone’s task list. An outbound call to a Lead stamps its Last_Outreach_Date__c.

A number nobody recognises becomes Unknown caller and lands in an Unknown Callers list view. Those are often the most important calls, a new customer ringing for the first time, so they are not left there. After-save triggers on Lead, Contact and Account re-run the match the moment a record gains that phone number, and link every earlier call from it. They use the trigger’s own records as candidates rather than SOSL, because the search index lags a record that was just saved.

The org refused the code, not the logic

Three deploy failures came from the platform rather than the sync.

The first:

This schedulable class has jobs pending or in progress

A scheduled class is locked while its jobs exist, and the lock covers every class it references. With twelve jobs always pending, any change to the sync meant stopping the schedule first. The fix I shipped was to give the scheduler no compile-time reference to the worker:

force-app/main/default/classes/RingCentralSyncSchedule.cls

public void execute(SchedulableContext context) {
    // Resolved by name on purpose: a scheduled class locks every class it references at compile
    // time, and deploys fail with "This schedulable class has jobs pending or in progress" while the
    // jobs exist. With no static reference, the sync code can be redeployed under a running schedule.
    Type syncType = Type.forName('RingCentralSyncQueueable');
    if (syncType != null) {
        System.enqueueJob((Queueable) syncType.newInstance());
    }
}

What actually works: stop the schedule before any deploy that touches the sync, and keep the sync’s classes out of deploys that do not need them.

The second: this project’s sourceApiVersion is 67.0, and at that version Apex database operations in this org ran in user mode. The sync failed with:

Operation failed due to fields being inaccessible on Sobject Phone_Activity__c

The sync and matcher now say what they mean: WITH SYSTEM_MODE on queries, as system or AccessLevel.SYSTEM_MODE on DML. Integration bookkeeping that must see every record with a number should not depend on who happened to fire it.

The third: Salesforce automatically added the new Phone Activity related list to the Account mini layout, then rejected its own addition:

miniRelatedList: Phone_Activity__c.Account__c is not present in the full layout

The related list has to be on the full page layout before the mini layout can carry it.

And one in testing. Apex tests see the org’s real CronTrigger rows, so the test that schedules the twelve jobs failed in the sandbox while the live sync was running:

The Apex job named "RingCentral Sync :00" is already scheduled for execution

Practical summary

  • RingCentral for Salesforce is an Open CTI softphone. It logs what the softphone handles in a browser tab, not calls answered on desk phones.
  • In a sandbox with enhanced domains, a CTI Adapter URL on a visualforce.com host can show “This content is blocked. Contact the site owner to fix the issue.” Use the sandbox’s vf.force.com host.
  • To log every call, pull the RingCentral call log server-side: JWT auth through an External Credential, a Queueable for the callouts, twelve Schedulable jobs for a five-minute cadence.
  • Each extension’s message-store does not include texts to a company number that uses the Business SMS shared inbox. Those need the Message Threads API.
  • Re-read with an overlap and upsert on an external ID; late calls and late recordings then cost nothing.
  • Match with SOSL IN PHONE FIELDS on normalized numbers, and re-match from Lead, Contact and Account triggers when a number first appears.
  • A running schedule blocks deploys of the sync’s code, and Type.forName in the Schedulable did not change that here. Stop the jobs, deploy, reschedule.
  • Say WITH SYSTEM_MODE and as system explicitly in integration code; do not rely on the API version’s default.

Filed under

Disclosure: Doorvana's owner is also a co-owner of Nocona Consulting. This is a real engagement between two separate companies, but not an arm's-length one — and not an independent reference. More on the work page.

FAQ

Does the RingCentral for Salesforce app log calls to desk phones automatically?

Not on its own. The managed package is an Open CTI softphone, and its call logging, including the "Auto create call log" setting, applies to calls the softphone handles while a user has Salesforce open in a browser. A call that rings a physical desk phone never passes through that browser tab, so the package does not see it. Logging every call to a line needs a server-side pull from the RingCentral call log API.

Why does the RingCentral softphone show "This content is blocked. Contact the site owner to fix the issue." in a sandbox?

In this build, the Call Center that the package's Setup Assistant generated pointed its CTI Adapter URL at a visualforce.com host. In a sandbox with enhanced domains that redirected to a My Domain that did not exist, and the utility bar panel showed the blocked-content message. Pointing the CTI Adapter URL at the sandbox's vf.force.com host fixed it.

How do you run a Salesforce Apex job every five minutes?

A Schedulable cron expression can fire at most once an hour per job, so a five-minute cadence takes twelve scheduled jobs, one at each five-minute mark. Each job can enqueue a Queueable that does the callouts. Check for a sync already queued or processing before enqueuing, so a slow run does not overlap the next one.

What does "This schedulable class has jobs pending or in progress" mean on deploy?

A scheduled Apex class is locked while its jobs exist, and in this build the lock reached well past the Schedulable itself. Loading the worker by name with Type.forName did not get around it: with that version scheduled in production, a validation that included the worker and the classes around it failed with this error on every one of them. Plan to stop the scheduled jobs (System.abortJob on their CronTrigger rows), deploy, and schedule them again, or deploy only components outside the scheduled code.

Why does Apex DML fail with "Operation failed due to fields being inaccessible" after raising the API version?

In this org, at API version 67 Apex database operations ran in user mode, so a sync running as a user without field access to the custom object failed. Integration code that must write regardless of the running user should say so explicitly, with WITH SYSTEM_MODE on queries and as system or AccessLevel.SYSTEM_MODE on DML.

Working on something like this?

I can tell you what it takes.

If you run a home services business and this looks like a problem you have, book a call and we will talk through it.