Batch Receipt Logs and Background Jobs
This article explains how Dryad Receipting runs large jobs in the background and how to follow them with Batch Receipt Logs. It covers what each log shows, how one run's logs fit together, how to stop a job, and what to do when a job looks stuck. It is written for Salesforce administrators and the staff who run receipting.
Why Jobs Run in the Background
Creating receipts, building .pdfs, merging, emailing and printing can involve thousands of records. Salesforce limits how much one request can do, so the app splits this work into background jobs that handle a few records at a time (the Receipt Batch Size setting).
Each job writes a Batch Receipt Log, numbered BRL-0001, BRL-0002 and so on. Open them from the Batch Receipt Logs tab. A job keeps running if you close the page that started it.
What a Log Shows
| Field | What it tells you |
|---|---|
| Action | What the job does (see the table below). |
| Status | "In Progress", "Complete", "Complete with Errors" or "Aborted". |
| Records Targeted | How many records the job set out to process. |
| Records Processed | How many it has processed successfully so far. |
| % Complete | Records Processed divided by Records Targeted. |
| Results | Error messages and other details. Long results are cut short. |
| Parent BRL | The "Create Receipts" log of the same run, so a run's steps can be followed from one log. |
| Dryad Mailer only: the Email record of the send. | |
| Printed | Merge logs only: ticked once the merged .pdf has been set as printed. |
The Batch Receipt Log Fields article lists every field.
Log Actions
| Action | Written by |
|---|---|
| Create Receipts | Batch Receipts, the New Receipts button on a list view, the scheduled job, and your own automation when it creates many receipts at once. |
| Create .pdfs | Every job that creates receipts, and also the Create Missing .pdfs button, and voiding a receipt (which re-creates its .pdf). |
| Merge .pdfs | Merging receipts for printing. The merged .pdfs are attached to this log. |
| Print Receipts | Setting receipts as printed. |
| Email Receipts | Emailing receipts, through Salesforce or Dryad Mailer. |
| Preview Report | The Create Preview Report button on the Batch Receipts screens. |
How One Run's Logs Fit Together
A run of Batch Receipts or the scheduled job usually writes several logs:
- a "Create Receipts" log for the receipts,
- a "Create .pdfs" log for their .pdfs, and
- when the run continues, "Email Receipts", "Merge .pdfs" or "Print Receipts" logs.
The later logs point to the first one through Parent BRL. Records a job works on are stamped with its log ID (the Batch Receipt Log Id field on receipts and gifts). That's how the app later finds "the receipts from this run", for example to email or print them.
.pdfs Are Created in Parallel
To finish sooner, a large "Create .pdfs" job is split into segments that run at the same time. The .pdf Segments setting sets how many: 3 by default, at most 5. Each segment is a Batch Receipt Log Segment record under the log, with its own status and counts.
- The log's Records Processed adds up its segments.
- The log is finished when no segment is still "Queued" or "In Progress".
- If any segment failed to create some .pdfs, the log ends "Complete with Errors" and Results says how many failed.
Stopping a Job
Open the log and click Abort Job, then confirm. The action doesn't check a receipting permission: anyone who can edit the log can use it. A job can be aborted as soon as it is started, even while it is still waiting in Salesforce's queue.
- The log and its open segments are set to "Aborted", and every segment's background job is stopped.
- Work already done is kept. Receipts that were created stay created, and their gifts show as "Receipted".
- A job that is already "Complete", "Complete with Errors" or "Aborted" can't be aborted. The action says "Cannot abort the job because the status is …".
Note: After aborting a "Create .pdfs" job, run Receipt Settings > App Utilities > Create Missing .pdfs to finish the receipts that have no .pdf yet.
One Run at a Time
Batch Receipts won't start a job while the same kind of job is already running in your org, whoever started it. This stops two runs from receipting the same gifts, or emailing or merging the same receipts twice.
| Action in Batch Receipts | Waits while this is running |
|---|---|
| Create receipts (non-recurring or recurring donations) | Any receipt or .pdf creation job, including the scheduled job. |
| Email receipts | Any receipt email job, including the scheduled job's emails. |
| Merge receipts | Any merge job. |
Different kinds of jobs don't block each other: for example, you can email receipts while other receipts are being created. An email job only picks up receipts whose .pdf is already created, so it never sends a receipt another job is still creating.
Batch Receipts checks when you open the action and again just before the job starts. If it is blocked, you see a message such as "Receipts are already being created by another user. Please wait for that process to finish, then try again." Click Finish, and try again once the other job's log is no longer "In Progress".
Note: The check looks at the background jobs that are actually running, not at log statuses, so a log stuck at "In Progress" never blocks Batch Receipts. Creating receipts from a list view or a record page isn't checked. Printing isn't checked either, because it doesn't run as a background job.
When a Job Looks Stuck
Sometimes a background job ends without updating its log, for example when it is stopped from Setup or hits a Salesforce error it can't catch. Its log stays "In Progress".
The app repairs these logs itself:
- Each time you open a create, email or merge action in Batch Receipts, it looks for logs whose background job has already ended. If the job was aborted, the log is set to "Aborted". Otherwise it is set to "Complete with Errors", and Results says "This job stopped before it finished. Some records may not have been processed."
- Each time .pdfs are created, and at the start of each scheduled job run, it also looks for .pdf segments whose background job has already ended. It closes them, counts their missing .pdfs as failed, and completes the log.
Logs created by older versions of the app may not record their job, so they can't be repaired this way. Abort them instead.
An "In Progress" log can block the scheduled job. The scheduled job skips its run while a "Create Receipts" or "Create .pdfs" log created today is "In Progress".
Troubleshooting
| Symptom | Check |
|---|---|
| A log stays "In Progress" for a long time | Look in Setup > Apex Jobs. If its jobs are still running, wait. If they have ended, open a create, email or merge action in Batch Receipts (or, for a .pdf log, start any .pdf job such as the Create Missing .pdfs button) and the log is closed automatically. Otherwise click Abort Job. |
| Batch Receipts says receipts are already being created, emailed or merged | A job of the same kind is running, started by someone else, the scheduled job, or you. Find its "In Progress" log and wait for it to finish, or abort it if it was started by mistake. |
| "Complete with Errors" | Read Results for the reason, such as an inaccessible field or a daily limit. For .pdf logs, open the segments to see which ones failed, then run the Create Missing .pdfs button. |
| Records Processed is lower than Records Targeted | Some records failed, or were skipped because they no longer met the rules when the job reached them. Check Results. |
| Receipts exist but have no .pdf | Their "Create .pdfs" log failed or was aborted. Run the Create Missing .pdfs button. |
| The Abort Job button doesn't appear | Check that the button is on the Batch Receipt Log page layout and that the user can edit the log. |