Skip to content

This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

CTC Billing, QBO, Files And Email — Current Source Operator Addendum

  • Status: CURRENT SOURCE-BASED RUNBOOK ADDENDUM / FIELD EVIDENCE REQUIRED
  • Current review ref: qa/master@58c24661902c10a30209bab62d43fc5490feaeba
  • Source refresh: CTC_BILLING_QBO_FILES_EMAIL_CURRENT_SOURCE_REFRESH_2026-08-08.md
  • Original Runbook: CTC_BILLING_QBO_FILES_EMAIL_OPERATOR_RUNBOOK.md
  • Read-only evidence: RBR-BILL-QBO-FILE-MAIL-READONLY-PREFLIGHT.md
  • Publication: repository only; current Wiki content not read
  • Program state: PHASE IMPLEMENTATION USER HOLD

1. Use This Addendum For

Use this addendum when:

  • a local AP/AR record appears saved but another checkpoint is unresolved;
  • AR Billing confirmation completed but QBO status did not;
  • QBO is SYNCING, ERROR or has a missing local reference;
  • a file appears in metadata but cannot be opened;
  • a BOL or Packing List send timed out or returned a partial result;
  • Staff Time/QuickBooks Time is confused with QBO Invoice status;
  • source drift makes an older runbook status ambiguous.

The original runbook remains the detailed procedural source. This addendum supplies the current source-freshness and recovery interpretation.

2. Checkpoints To Read Separately

Local Transaction
Local Container AR
QBO Invoice
File Object
T_FILE Link
File Readability
BOL Gmail Message
Packing List Target/Part Messages
QuickBooks Time

Never replace these with one status.

3. First Response To An Unknown Result

1. Stop repeating the action.
2. Record tenant, role, page, source record and time.
3. Reread the authoritative local row.
4. Reread each independent child checkpoint.
5. Determine the last confirmed successful boundary.
6. Reconcile provider/object evidence when separately authorized.
7. Resume only the missing owner step.

Do not use a toast or timeout message as the final authority.

4. Local Generic Transaction

Normal readback

After Save or Close:

  • reopen the exact transaction;
  • confirm the intended source relation;
  • confirm active lines and totals;
  • confirm current status and dates;
  • confirm intended files separately;
  • confirm QBO/email separately when applicable.

Response missing

Save/Close response missing
-> search by exact source relation or transaction ID/UUID
-> compare header and active lines
-> classify committed / absent / partial / conflict

Do not create a second transaction until the first result is known.

Correction

Current correction/void/reversal policy is not fully accepted across all source families. Escalate rather than editing raw tables or creating an offsetting row without the owner procedure.

5. Local Container AR

Before Confirm

Confirm:

  • intended Booking/container source;
  • current candidate and preview values;
  • customer mapping;
  • selected rows;
  • service descriptions, quantities, rates and amounts;
  • no already-active local invoice for the same intended scope.

After Confirm

Reread:

  • local transaction ID/UUID;
  • active transaction lines;
  • current QBO state;
  • exact Booking/container relation.
READY
= local QBO-ready projection
!= QBO delivered

Confirm response missing

Reread exact local AR before any second Confirm. A second Confirm can create or rewrite an unintended record when the original request committed.

6. QBO Invoice

Current local states

NOT_SYNCED
READY
SYNCING
SYNCED
ERROR
VOIDED

These local labels are not a complete provider attempt history.

SYNCED

Confirm all intended local group rows contain the expected provider invoice reference and locally reconciled values.

SYNCING

Do not press Sync again merely because the row is old.

SYNCING
-> provider result may be absent, pending or accepted
-> search/reconcile provider evidence first

ERROR

ERROR does not prove that QBO created nothing. Inspect whether provider invoice ID/doc/sync-token fields exist and reconcile provider-side state before retry.

Provider accepted, local reference missing

provider invoice exists
+ local rows lack final provider reference
= provider committed / local pending

Link or reconcile the existing invoice through an approved recovery procedure. Do not create another invoice.

No provider search available

When the current account/tool cannot search safely, classify MANUAL REVIEW REQUIRED. Do not convert uncertainty into a create retry.

7. File Object And Business Link

Normal readback

object metadata
+ intended T_FILE relation
+ readable download/open
= file checkpoint

File listed but unreadable

Do not re-upload immediately. Determine whether:

  • metadata points to a missing object;
  • storage configuration is unavailable;
  • object exists but the link/path is wrong;
  • access policy denies the reader;
  • a shared object/path is involved.

Upload response missing

Reread both:

  • object/storage result when available;
  • intended T_FILE relation.

A second upload can create a duplicate object or duplicate link.

unlink business relation
!= delete physical object

Do not delete an object until every active relation and retention rule is known.

8. BOL Email

Current send input

  • exact Transload/reference;
  • active BOL recipient configuration;
  • optional Scale Ticket PDF;
  • active Transload-linked files;
  • intended subject.

Response missing or timeout

Search provider Sent evidence by:

recipient
subject/reference
narrow time window
attachment names when available

Do not resend until provider absence or a specifically missing message is established.

Missing attachment

A Gmail success can still be operationally incomplete if an intended attachment was not prepared. Compare the intended attachment set to the provider message before calling the BOL complete.

9. Packing List Email

Current dimensions

Target:
CUSTOMER / INSPECTOR / BOTH

Part:
1..N generated attachment batches

Completion

Every intended target and every intended part must be reconciled.

Partial result

The current response can include earlier successful parts before a later failure.

Customer part 1 sent
Customer part 2 failed
Inspector not attempted
= partial result

Do not repeat BOTH or the full target blindly. Reconcile the provider messages and resume only the approved missing target/part.

GP OUT REF prerequisite

When the current source blocks send because an OUT REF is missing, resolve the Booking/equipment-load business data. Do not bypass the prerequisite or use a different recipient as a workaround.

10. QuickBooks Time Is Separate

QuickBooks Online Invoice
!= QuickBooks Time

A local Clock Out or Job event can succeed while QuickBooks Time fails. That does not alter local AR/QBO Invoice state.

Likewise, QBO Invoice SYNCED does not prove employee time synchronization.

Use the Staff Time/Integration recovery procedure for QBT.

11. Daily Close Review

Before closing the day, classify each required child:

NOT_REQUIRED
COMPLETE
PENDING
PARTIAL
UNKNOWN
MANUAL_REVIEW

A day can be operationally closed only with an explicit disposition and owner for unresolved required children.

Minimum unresolved-work record:

  • source record ID/reference;
  • child checkpoint;
  • current local state;
  • provider/file evidence state;
  • last safe action;
  • next owner;
  • forbidden repeat action;
  • follow-up time.

12. Escalation Packet

Provide:

Environment and source SHA
Tenant/profile
Actor/role
Page/API/action
Source and transaction/booking/transload IDs
Current local status and timestamps
QBO/File/Mail checkpoint state
Request/correlation ID when available
Exact expected versus actual result
Provider/object read authorization status
Actions already taken
Actions intentionally not repeated

Do not include credentials, full tokens, session cookies or unrestricted customer email exports.

13. Current Evidence Boundary

Static current source refresh:
COMPLETE

Current DB/schema/row inventory:
NOT RUN

Current QBO/Gmail provider evidence:
NOT RUN

Current file object readability:
NOT RUN

Current target-role behavior:
NOT RUN

Current Wiki content:
NOT READ

This addendum must be reconciled with actual current evidence before it is presented as field-accepted current procedure.

---

Source: docs/runbooks/CTC_BILLING_QBO_FILES_EMAIL_CURRENT_SOURCE_ADDENDUM.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.