Skip to content

CTC Billing, QBO, Files And Email Operator Runbook

Purpose

  • Status: SOURCE-RECONCILED OPERATOR DRAFT / NOT PUBLISHED - Audience: Office/Billing, Operations Office, Accounting manager, file/document operator and support.

Who does this

Whoever owns this job.

Before you start

  • You have the right account (see Permissions and Access).
  • The record and date you are working on are correct.

  • Words you do not know are in the Glossary.

  • Status: SOURCE-RECONCILED OPERATOR DRAFT / NOT PUBLISHED

  • Audience: Office/Billing, Operations Office, Accounting manager, file/document operator and support.
  • Operating profile: ctc-execution
  • Composite process: PROC-BMS-BILLING-CLOSE-CTC
  • Process detail: CTC_BILLING_QBO_FILES_EMAIL_RECONCILIATION.md
  • Recovery diagrams: CTC_BILLING_QBO_FILES_EMAIL_SEQUENCE_DIAGRAMS.md
  • Important: this Runbook describes source-reconciled current operating boundaries and safe recovery principles. Exact current labels, role access and Production provider behavior still require target-role review before Wiki publication.
  • Does not authorize: financial correction, QBO resend/void, file cleanup, Gmail resend, Wiki DB write, deployment or Production action.

1. Core Rule

Billing and document close is not one button and not one status.

Local transaction
Local AR invoice
QuickBooks Online
File object
Transaction file link
BOL email
Packing List target/parts

Each checkpoint must be reviewed independently.

Never assume

Closed locally = synced to QuickBooks
QuickBooks error = no invoice exists
File uploaded = attached to every transaction
File row visible = file can be opened
BOL/Packing action returned = every message was sent
One Packing part sent = all parts sent

Before retrying anything

  1. Identify the exact local record or provider/file/email effect.
  2. Refresh or reopen the owning screen.
  3. Read the authoritative current state.
  4. Check whether the action may already have committed.
  5. Retry only the missing eligible boundary.

2. Roles

Role Normal work Escalate when
Office/Billing review/create/close local transactions, preview/confirm AR, review QBO and daily close wrong committed values, duplicate invoice risk, provider uncertainty, role denial
Accounting manager approve correction/void/provider reconciliation financial/provider change needs approval or external accounting action
Operations Office verify and send BOL/Packing emails recipient, attachment, duplicate-send or target-part uncertainty
File/document operator upload/link/read/unlink documents orphan object, unreadable link, shared-object cleanup or retention issue
Support investigate request IDs, records, provider/storage evidence code/schema/config/role fault or unknown result cannot be resolved safely

A Super Admin should investigate platform state but should not substitute for the business/accounting owner.

3. Daily Start Checklist

Before processing Billing/document work:

  • confirm the correct tenant and operating date;
  • confirm your personal account and expected role/menu;
  • verify the source work is complete enough for the intended accounting/document action;
  • confirm billing customer/vendor and account (AP or AR);
  • confirm QBO module/configuration is expected for the tenant when applicable;
  • confirm intended BOL/Packing recipients and source files;
  • note unresolved items carried from the previous operating period.

Do not begin by resending every ERROR or reopening every incomplete row.

4. Classify The Applicable Checkpoints

For each business item, select only the checkpoints that apply.

Checkpoint Typical reason it applies
Generic local AP/AR transaction source work needs a local accounting row
Container AR invoice AR Billing candidate should become a local container invoice
QBO invoice local AR invoice must be delivered to QuickBooks Online
Transaction file supporting document must be stored and linked
BOL email transload BOL/weight/files must be sent
Packing List email selected booking report must be sent to Customer/Inspector

Not every transaction requires every child process.

5. Generic Local Transaction Procedure

5.1 Before create/edit

Verify:

  • source record and reference;
  • AP/AR account;
  • billing company/customer/vendor;
  • source rate or expected line values;
  • whether a transaction already exists for the same source;
  • whether the transaction is already closed or provider-linked.

5.2 Create or edit

  1. Open the applicable transaction/source page.
  2. Select the intended source row(s).
  3. Confirm account and billing company.
  4. Submit once.
  5. Refresh the transaction list/detail.
  6. Verify the exact header and all active lines.

5.3 Close

Before selecting multiple rows:

  • confirm they belong to the intended account;
  • confirm billing company and common close values are compatible;
  • confirm none is protected by a completed provider/accounting state;
  • review invoice/check number, complete date and remark.

After submit:

  • refresh every selected transaction;
  • verify each close field individually;
  • do not rely only on one success message.

5.4 Unknown close result

When the response is missing or unclear:

  1. Do not select and close the same rows again immediately.
  2. Record the selected transaction IDs/references.
  3. Refresh each row.
  4. Compare status, complete date, invoice/check number and remark.
  5. Repeat only rows that are still unchanged and still eligible.
  6. Escalate any partially or incorrectly committed result.

5.5 Wrong committed value

  • stop further provider/file/email actions for the affected transaction;
  • preserve the transaction ID/reference and before/after evidence;
  • use the approved accounting correction path;
  • do not raw-delete or clear provider fields.

6. AR Billing Review And Local Confirm

6.1 Load candidates

Open AR Billing and verify:

  • date/filter scope;
  • booking/container identity;
  • customer;
  • source work completion/readiness;
  • warnings or source AR conflicts;
  • existing invoice and QBO state;
  • expected amount.

6.2 Review lines

Use Review before Complete whenever available.

Check:

  • service/charge description;
  • quantity;
  • rate;
  • amount and total;
  • customer mapping;
  • invoice number and grouping choice;
  • unexpected default/preset values.

The preview is not a committed invoice.

6.3 Confirm local invoice

  1. Select only reviewed candidates.
  2. Select Complete once.
  3. Wait for the local result.
  4. Refresh/reopen the workbench.
  5. Verify the local transaction identity, active lines and local QBO state.

Current source treats all items in one confirm request as one local DB transaction. If one item fails, the expected current result is a rollback of the request batch; still reread all candidates before changing inputs.

6.4 Local success versus QBO

Local invoice READY
= CTC local AR invoice committed

It does not mean
= QuickBooks invoice exists

The current browser normally starts QBO delivery after local success. A browser interruption can leave a valid local invoice waiting for a later QBO action.

6.5 Existing invoice cases

Observed result Safe interpretation/action
Existing source-specific AR Use/review that existing owner; do not create duplicate container AR.
Existing unsynced container AR Current source may rewrite it; confirm the reviewed result and escalate if correction policy is unclear.
Existing QBO SYNCED Do not overwrite/recreate through AR confirm. Use provider-aware correction.
Two apparent invoices for same booking/container Stop. Preserve both identities and escalate duplicate reconciliation.

6.6 Unknown confirm result

  1. Search by booking/container in AR Billing.
  2. Read the active local transaction and lines.
  3. Check whether the whole request appears committed or absent.
  4. Do not repeat Complete for candidates whose local invoice now exists.
  5. If the result is contradictory or duplicated, escalate before QBO send.

7. QuickBooks Online Procedure

7.1 Before send/retry

Verify:

  • local invoice exists;
  • selected local transaction UUID/reference;
  • customer mapping;
  • item/service mappings;
  • invoice/document number;
  • amounts and grouping;
  • current QBO status and provider ID;
  • no existing send is in progress or unresolved.

7.2 State meanings

Current local state Operator meaning
READY Local invoice is ready; QBO not complete.
SYNCING A send attempt claimed the row. Provider result can be in progress, committed or unknown. Do not resend.
SYNCED with QBO ID Local QBO reconciliation is recorded. Use provider-aware correction if needed.
ERROR A handled local error exists. It does not prove the provider invoice is absent.
blank/legacy not-synced No provider completion proof; inspect current context before sending.

7.3 Normal send

  1. Select the intended completed invoice rows.
  2. Confirm the grouping mode.
  3. Select Send to QuickBooks once.
  4. Keep the per-group result visible.
  5. Refresh the workbench.
  6. Verify QBO ID/document/status for each group.
  7. When possible, reconcile the provider invoice customer/document/amount.

7.4 Mixed group result

A request can return different results by group.

Group A SYNCED
Group B ERROR
Group C SKIPPED
  • preserve Group A;
  • inspect why Group C was skipped;
  • work only Group B or unresolved groups;
  • do not resend the whole selection.

7.5 SYNCING or unknown result

Do not reset or resend based only on time.

Collect:

  • local transaction UUIDs;
  • customer;
  • document/invoice number;
  • total amount;
  • QBO local state/error;
  • attempt/request time and request ID when available.

Search/reconcile QuickBooks by customer, document number and amount through the approved support/accounting procedure.

Provider evidence Safe next step
Intended invoice found Reconcile local QBO ID/status. Do not create another invoice.
Provider absence established Retry the same eligible invoice/group through the approved path.
Result still uncertain Keep manual review. Do not resend.

7.6 QBO correction

Do not:

  • clear QBO ID;
  • set status back to READY manually;
  • recreate the local invoice;
  • resend to create a replacement.

Use the approved accounting/provider correction or void procedure.

8. Transaction File Procedure

8.1 Before upload

Verify:

  • intended transaction(s);
  • file content/type/name;
  • whether the same object should link to every selected transaction;
  • whether a file/link already exists;
  • whether sensitive/retention requirements apply.

The current flow has two checkpoints:

1. object upload
2. transaction link registration

Procedure:

  1. Upload once.
  2. Keep returned file metadata/result available.
  3. Register/link it to the intended transactions.
  4. Refresh every intended transaction.
  5. Open/download the file through each intended link.
  • do not upload the same binary again immediately;
  • identify the uploaded object metadata/UUID/path if available;
  • inspect every intended transaction for a link;
  • register only missing links through the approved recovery path;
  • if no safe link recovery exists, mark the object as an orphan candidate and escalate.
  • compare object/path/UUID, target transaction and type;
  • identify the canonical link;
  • unlink duplicate relation only through approved file procedure;
  • do not delete the physical object while any active link may use it.

8.5 Unlink/delete

Before any delete/unlink:

  • list every active row/link sharing the object/path;
  • verify retention/legal hold;
  • verify whether the action means unlink or physical cleanup;
  • preserve required evidence.
Unlinking one transaction
!= deleting the shared object
  • capture file/link identity and error;
  • verify storage/object metadata;
  • inspect whether other links are also broken;
  • do not create another link to the same missing object;
  • escalate storage/object reconciliation.

9. BOL Email Procedure

9.1 Before send

Verify:

  • correct transload and reference;
  • billing company;
  • BOL recipient(s);
  • optional scale ticket;
  • all intended active files and readability;
  • expected subject and attachment set.

Current subject is normally:

{REFERENCE_NUMBER} BOL and Weight

9.2 Send

  1. Select the BOL email action once.
  2. Keep the response/result visible.
  3. Confirm the intended recipient and attachment set used.
  4. Reconcile the provider message/Sent evidence when available.

9.3 Failure before provider send

Recipient invalid, attachment read failure or mail initialization failure does not undo other CTC business work. Correct the exact source and retry the send action only.

9.4 Unknown provider result

When the response is lost or uncertain:

  1. Do not send again immediately.
  2. Search Gmail Sent/provider logs by recipient, subject/reference and time.
  3. If the message exists, treat it as sent and record/escalate reconciliation.
  4. Retry only after absence is established.

9.5 Important distinction

IS_DOC_SUBMITTED or local transaction status
!= BOL email sent

10. Packing List Email Procedure

10.1 Before send

Verify:

  • booking and equipment rows;
  • Customer, Inspector or Both target selection;
  • customer and inspector recipients;
  • weight/reference options;
  • generated body/report content;
  • attachment list and expected number of parts.

The current CTC route does not support MK report mode.

10.2 Target and part model

Treat every item separately:

CUSTOMER Part 1 of N
CUSTOMER Part 2 of N
INSPECTOR Part 1 of N
...

10.3 Normal send

  1. Submit one reviewed batch.
  2. Keep returned Results visible.
  3. Verify every intended target and part.
  4. Reconcile provider messages/Sent evidence for each part when needed.
  5. Mark complete only when all intended target-parts are verified.

10.4 Partial result

Example:

CUSTOMER 1/2 sent
CUSTOMER 2/2 failed
INSPECTOR not attempted
  • preserve CUSTOMER 1/2 evidence;
  • do not replay the full Customer target;
  • current endpoint has no part-only resume, so manual reconciliation/escalation is required before another send;
  • record exact target/part/subject/time.

10.5 Unknown part result

Search Sent/provider evidence for that exact target, subject with part suffix and time. Retry only the exact unresolved part when the system supports it; with the current endpoint, do not blindly invoke the full target again.

10.6 Source/options changed

If booking content, recipients, options or generated partitioning changed after partial sends:

  • treat the new output as a new batch/version;
  • do not mix old successful parts with newly generated parts without explicit review;
  • notify recipients appropriately under business policy.

11. Daily Billing And Document Close

11.1 Open items

For each item, record/check:

Child checkpoint Identity/evidence Result
Local transaction transaction ID/UUID, source, account, close fields verified/carried/not applicable/blocked/unknown
Local container AR booking/container, transaction UUID, lines result
QBO group, provider/local ID/status result
File object and every intended link/readability result
BOL email transload/reference/recipient/provider message result
Packing email booking/target/part/provider messages result

11.2 Close or carry

Use these meanings:

VERIFIED
= applicable child result is confirmed from its authority

CARRIED
= unresolved result has exact state/evidence/owner and next action

NOT_APPLICABLE
= child is intentionally not required

BLOCKED
= unsafe or missing dependency prevents progress

UNKNOWN
= current state cannot yet be established

These are daily-review dispositions, not child DB states.

11.3 End-of-day handoff

For every carried/blocked/unknown item include:

  • source/reference;
  • transaction/invoice UUID/ID;
  • provider/file/email identity when known;
  • exact current state;
  • last action/time/request ID;
  • what was reread;
  • what must not be repeated;
  • next owner;
  • expected next review time/cadence after Operations policy is approved.

12. Common Unknown-Result Procedure

Response missing or result unclear
-> identify the boundary
-> reread local record
-> reread provider/storage evidence when applicable
-> classify complete / absent / partial / unknown
-> perform only the missing eligible action

Boundary checklist

Boundary Read before retry
Generic transaction header, active lines and close fields for every selected ID/UUID
AR confirm active invoice and lines for booking/container
QBO local group state, provider ID/doc, provider search evidence
File upload object UUID/path/storage result
File link all intended target links and readability
BOL email recipient/subject/reference/provider Sent evidence
Packing email batch target/part Results and provider Sent evidence

13. Do-Not-Repeat List

Do not repeat without authoritative reread:

  • source transaction create;
  • bulk transaction close;
  • AR Complete;
  • QBO send;
  • object upload;
  • transaction file registration;
  • physical object delete;
  • BOL send;
  • Packing target or full batch send.

Do not use a success toast, browser timeout or local ERROR alone to decide whether an effect happened.

14. Escalation Evidence

Provide only necessary, safe evidence:

tenant/profile and environment
actor/role
source/reference
transaction/invoice ID/UUID
booking/container/transload identity
QBO state/provider ID/doc number/amount
file object/link identity and readability error
email target/part/recipient/subject/message/thread ID
action time and request/correlation ID
current screenshot without secrets
what was reread
what must not be repeated

Do not paste credentials, tokens, raw customer data dumps or full provider payloads into tickets/docs.

15. Current Limitations To Show In Wiki

Until corrected/verified, the user-facing Operations Manual must not imply:

  • generic close enforces compatible selected rows server-side;
  • Review is a mandatory AR server gate;
  • concurrent AR confirm is duplicate-proof;
  • SYNCING automatically expires safely;
  • QBO ERROR means no provider invoice;
  • file unlink safely cleans shared objects;
  • BOL/Packing sends have a durable local ledger;
  • Packing can resume one part;
  • the admin recipient override is a normal role policy;
  • there is an approved daily close SLA/escalation owner.

16. Future React/Next.js Procedure Changes

Stable Wiki topics remain:

billing
ar-billing-qbo
ctc-daily
errors-recovery

During migration, update only the application entry/link and any accepted visible workflow differences. Preserve:

  • independent child checkpoints;
  • local/provider/file/email distinctions;
  • no-blind-retry rules;
  • exact readback;
  • target-part visibility;
  • correction/escalation ownership.

The future interface should reduce cross-page searching but must not hide independent authority behind one “Complete” button.

17. Field Acceptance Checklist

Office/Billing

  • can identify transaction source/account/company;
  • can create/edit/close without mixed-row confusion;
  • can distinguish local AR from QBO;
  • can recover an unknown local result without blind replay;
  • can identify provider-protected correction.

File operator

  • can distinguish object upload from link registration;
  • can verify readability per intended transaction;
  • understands unlink versus object cleanup;
  • can escalate orphan/shared-object cases.

Operations Office

  • can verify BOL recipient/attachments/result;
  • can interpret Packing target/part partial results;
  • can search/reconcile before resend.

Manager/support

  • can trace request, local state and provider/storage result;
  • can identify exact next owner;
  • does not force status or replay unknown effects.

Field acceptance must use current labels/routes and target-role accounts before publication.

---

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