Skip to content

Run a One-Time Batch Screen

Batch screening screens every record in your org that is configured for screening and is due, in one go. Use it when you have just finished configuring PhoneTools and want your existing data screened, and any time you want to bring everything up to date without waiting for the daily job.

Running the Batch

  1. Open the App Launcher and select PhoneTools.
  2. Go to the PhoneTools Administration tab.
  3. Go to the Screening tab and find the Batch Screening section.
  4. Select Screen Now.

PhoneTools starts a Salesforce batch job for the first object you screen, and starts the next object about twenty seconds after that job finishes, until every configured object has been through. The table underneath the button lists the jobs as they run.

Note: Global Screening Settings, Scheduled Screening, Screening Count and Batch Screening are only shown to a user whose profile has the Modify All Data permission. Other users can open the tab and use Phone-Field Configuration and Screening Credits, but not the four sections above. Modify All Data has to be on the profile, because a Permission Set cannot satisfy this particular check. See Permission Set Assignments.

Which Records Are Screened

A record is picked up by the batch when all of the following are true.

  • Its object has at least one phone field that is configured and has Enable Screening ticked. See Configure a Field to Screen.
  • If that configuration names a Formula Field, the formula returns 1 for the record. See Define a Screening Formula.
  • Its Next Screen Due Field is empty or holds a date and time in the past. Records that have been screened recently enough to still be in date are passed over.

Converted Leads are never screened, by the batch or by any other route.

Only the registers selected in Global Screening Settings are used. If none is selected, the batch does not start and PhoneTools reports:

No services are selected. Please check services to screen against and save settings.

Watching it Finish

The table in the Batch Screening section shows one row for each job PhoneTools has started, which means one row per object, with its status and its error count. A row reads Queued, then Processing, then Completed. Aborted means it was cancelled, and Failed means it stopped on an error.

Salesforce splits each job into batches of up to 200 records. Total is how many batches the job was divided into and Processed is how many of them have finished, so those two columns count batches rather than records. Errors counts batches as well: it goes up by one for each batch that hit at least one error, not once per failed record.

That count covers every record the job has to look at, not the number it will screen. A job that reads a hundred thousand records but finds only two hundred of them due still works through all five hundred batches.

Screening is finished when no row is left in Queued or Processing. Below the table, "Click here to view screening jobs using the Apex Jobs viewer." opens the standard Salesforce Apex Jobs page if you want the full picture.

To stop a run part way through, select Stop to end all of it, or Cancel in the Action column to end one object's job and leave the rest running.

You Cannot Start Two Runs at Once

Screen Now is greyed out for as long as any screening job is in Queued or Processing, so an accidental second run is not possible while the first is going. If a run is somehow started anyway, PhoneTools refuses it and reports:

Operation cannot be performed as a screening operation is in progress. Please wait or click the 'Stop' button.

There is no way to queue a second run behind the first. To screen sooner, stop the run that is going, then start a new one.

Credits

Every number PhoneTools sends to a register uses a lookup, and a batch screen sends every due number in your org at once, so it is worth knowing the size of the run before you start it.

  • The Screening Count section, and its Calculate Now button, works out how many records would be involved. Qualifying is every record configured for screening whatever its due date, and Due is the number that would actually be screened if the job ran now.
  • The Screening Credits section shows what is left on each register. Refresh Remaining re-reads it from the service.
  • Screening the same record more than once in the same month does not use another lookup, so re-running a batch shortly after the last one is not as expensive as it looks.

If your credits run out part way through a run, screening stops. The records that had already been screened keep their result, the record that failed is left with a status of Error, and its Next Screen Due Field is left alone so that it is picked up again once you have more credits. PhoneTools also cancels the daily scheduled job if you have one, so remember to re-enable it. See Schedule a Daily Batch Screening Job.

If Something Goes Wrong

Errors from a batch run are emailed to the address in Email address for screening alerts, under the subject "PhoneTools: batch DNC-screening errors", with the org ID and the Apex job ID so support can trace the run. The Details column of the table also carries one error for the job, taken from the most recent batch that failed, so treat it as a sample rather than as the full list. The email is the complete record.

Keep that address pointed at a monitored mailbox: it is how you find out that screening has stopped. If the address is empty, PhoneTools falls back to the email address of the user who started the job. See Choose Which Services to Screen Against and Common Error Messages.