How Screening Works¶
PhoneTools screens the phone numbers held on your Salesforce records against the Telephone Preference Service (TPS) and Corporate Telephone Preference Service (CTPS) registers, and writes the result back onto the record.
Screening is driven by configuration rather than by code. You tell PhoneTools which phone fields to screen, and PhoneTools looks after the rest. The only places code is involved are a custom trigger, if you screen an object other than Account, Contact or Lead, and an optional screening formula if you want to limit which records are screened.
What You Get out of the Box¶
PhoneTools supports Account, Contact and Lead out of the box. For each of these objects the package already provides:
- a trigger that notices when a phone number changes,
- the three functional fields that hold the screening result,
- an entry in the phone field configuration for each standard phone field.
The phone fields configured when the package is installed are:
| Object | Phone fields |
|---|---|
| Account | Phone |
| Contact | AssistantPhone, HomePhone, MobilePhone, OtherPhone, Phone |
| Lead | MobilePhone, Phone |
Being configured is not the same as being screened. Each entry also carries an Enable Screening setting, which is off until you turn it on, so no numbers are screened until you say so. See Configure a Field to Screen.
If you want to screen a phone field on any other object, or a custom phone field on one of these three, you will need to create a trigger, create the functional fields, and then add the field to the configuration.
The Three Functional Fields¶
Every object you screen needs three custom fields, which we call the functional fields. They record the outcome of screening, tell PhoneTools when the record is next due, and hold the detail behind the summary. On Account, Contact and Lead these fields ship with the package:
| Role | Field label | API name | Data type |
|---|---|---|---|
| Phone Status Field | Phone Screening Status | pw_pss__PhoneScreeningStatus__c |
Picklist |
| Next Screen Due Field | Next Phone Screen Due | pw_pss__NextPhoneScreenDue__c |
Date/Time |
| Screening Results Field | Phone Screening Results | pw_pss__PhoneScreeningResults__c |
Text Area (Long) |
- The Phone Status Field summarises the screening result for the whole record, across every phone field configured on that object. Because it is an ordinary picklist, you can use it in reports, list views and automation.
- The Next Screen Due Field is stamped with a date and time when the record is screened, and marks the point at which the result is treated as stale and the record becomes eligible for screening again.
- The Screening Results Field holds a JSON summary of the result for each number screened. It is there for reporting and custom development on top of PhoneTools; the Lightning Component reads it to build the on-screen breakdown.
The same three fields are shared by every phone field configured on an object. Changing them for one phone field changes them for all of the screenable phone fields on that object. If the object already has more than one phone field with screening enabled, PhoneTools asks you to confirm the change before it saves, and names the fields it is about to change. If only one phone field is enabled there is nothing to share yet, so no confirmation appears.
Screening Statuses¶
The Phone Status Field holds one of five values: Not Screened, Safe to Call (not listed), Caution (partially listed), Do Not Call (listed) and Error. The PhoneTools Lightning Component then breaks that summary down, number by number, for the user looking at the record.
What each status means, how PhoneTools arrives at it, and how the two levels relate to each other are covered in Phone Screening Statuses.
When Does a Record Get Screened?¶
A record becomes eligible for screening when its Next Screen Due Field is empty or holds a date and time in the past.
When a user or an integration changes a phone number on a record, the trigger resets all three functional fields before the record is saved: the Phone Status Field goes back to Not Screened, and the Next Screen Due Field and Screening Results Field are cleared. The record is then waiting to be screened again.
Eligibility governs the routes that pick records up for you: batch screening from the PhoneTools Administration tab, scheduled screening, and screening from a Flow. Screening on demand from the record page ignores it, so a user can press Screen and get a fresh result whether or not the record is due.
Converted Leads are never screened, on any route.
When a record is screened successfully, the Next Screen Due Field is stamped 21 days into the future. Screening the same record more than once in the same month does not use another lookup, so you are free to re-screen sooner if you want to.
Note: The 21-day interval sits inside the 28-day re-screening interval the Information Commissioner's Office expects, which gives you a margin before a result is considered out of date.
If screening fails at the service, for example because you have run out of credits, the Next Screen Due Field is left alone so that the record stays eligible and is picked up on the next run.
How Your Users See the Result¶
Add the PhoneTools Lightning Component to the Lightning Record Page for each object you screen. It appears as a Phone Numbers card listing every phone number on the record, with the result for each register alongside it, and a Screen button so a user can screen the record there and then. See Add the PhoneTools Component to a Record Page.
The Phone Status Field gives the same information at record level rather than number level. Because it is a field on the record, it is the value to use when you want to filter a call list, drive a report, or stop an automated process from dialling a number it should not.