AR Collections Note Logging Copy link

🚨 Blitz data = Excel worksheet UDFs, not MCP tools/connectors. Extract data only by writing =br_...() into a cell (via execute_office_js) and reading the spill — never tool_search for br_*, never refresh_mcp_connectors, and never conclude "no Oracle EBS / Blitz connector is set up" (the Blitz Report add-in is an Excel add-in, not an MCP connector, so it never appears in the connector list — its absence there is expected).

Read br-run-uploads FIRST (read_skill("br-run-uploads")) — it owns the upload mechanics (the blitz_ helper sheet, sheet layout, column contract, trigger-cell placement, _blitz_run_status polling, the talk-in-the-user's-language rule). This skill only adds what is specific to collection notes.

What this writes — and what it deliberately does not

A collection note is an internal activity record in Advanced Collections — the lowest-risk write in the AP/AR family, but permanent and visible to every collector on the account. So:

1. One note per customer per run. Never one per invoice — that floods the account history and buries real activity. The invoice detail belongs INSIDE the one note's text.
2. The note is a record, not an outbound dunning email. This skill never contacts a customer. Say so if the user seems to expect sending.
3. Confirm before submitting — the user must see which customers get which text. Drafted messages come from the worklist's dunning tiers; the user may want to soften wording before it becomes a permanent record.
4. Never log against excluded customers — anyone the worklist excluded (disputes, legal, payment plans) stays excluded here.

When to use

"Log the collection notes", "post the worklist to Collections", "record these follow-ups in EBS", "action the collections worklist". For building the worklist, use br-ar-collections-worklist.

Inputs

• A Worklist sheet from a br-ar-collections-worklist run in this workbook — the normal entry (it carries the ranked customers, exposure, dunning tier, and drafted message). If absent, run that skill first; do not re-derive a worklist here.
• Scope — default: the tier the user names ("log notes for the top tier"); otherwise ask which tiers/customers.
• Note Type — from the LOV (below); the user picks once for the run.

The upload (authoritative — do NOT broad-search for it)

IEX Collection Note Upload (Type U). Logging is adding NEW rows, so download an empty grid: =br_run_upload_external("IEX Collection Note Upload","Operating Unit=<OU>; Upload Mode=Create") (omit the template argument unless the instance shows templates).

The column contract — per new note row

Confirm with =br_upload_columns_external(FALSE, "<Upload Sheet Name>") and write by Sheet Column letter:

Drafting rule for the note text

Per customer, resolve the tier's drafted message with real numbers: total past due $, oldest invoice ref + days, promised/next action. Prefix with a run marker the collectors can recognise, e.g. [Blitz worklist <date>] — it is also how a later run detects already-logged customers. Keep each note under ~2000 characters; move overflow to Note Detail.

Pipeline

Step 1 — Build the proposal (single read call)

From Worklist: filter to scope, drop exclusions, resolve each customer's drafted text, and check for the run marker from a previous logging run — a customer already logged this cycle is skipped (re-logging is noise, not diligence).

Step 2 — Confirm (one ask_user_question)

Show customer, tier, exposure $, and the exact note text (or a sample plus "same pattern for the rest" when >10). Then:

"Log <n> collection notes in <OU> — one per customer, <tier breakdown>? These become permanent account activity visible to the collections team." → Yes / Edit the wording first / Cancel

If they edit, apply the edit to the affected tier's text and re-show.

Step 3 — Fill the grid (one write call)

Look up Note Level / Note Type (and Note Status if required) from the LOVs first — ask, never guess. Then paste all confirmed rows in ONE call, by Sheet Column letter.

Step 4 — Validate

=br_prepare_upload_external() in row 1, a few columns right of the sheet's used range. Poll, then =br_validation_results_external(FALSE, ...). Typical refusals: an account number not found (worklist customer merged/renamed — drop and report), a required LOV column blank (fill from its LOV), an OU mismatch. Fix and re-prepare; stop after ~3 unproductive rounds.

Step 5 — Confirm again, then submit

Second explicit confirmation on the validated set, then =br_process_upload_external(); poll for DONE: <n> succeeded, <n> errored (request <id>). The add-in clears the trigger cell itself.

Step 6 — Report and cross-link

Read =br_validation_results_external(TRUE, ...); report logged / failed per customer + request id. A DONE with errors is a partial success — the succeeded notes are live; fix only the failures. Annotate Worklist with a Logged <date> column so the next worklist run shows follow-up state.

Validation (before declaring done)

• One note per customer; every one individually visible (or pattern-approved) at Step 2.
• No excluded customer logged; no transaction-level rows unless the user asked.
• Reported count = Success rows. Upload sheet clean; blitz_ deleted.

Re-run / refresh

"Log the next tier too" → same grid, append rows, repeat Steps 4–6 (untouched rows already submitted are inert only if the sheet was not reprocessed — prefer a fresh Create-mode grid for a second batch). A fresh worklist run supersedes the old sheet; carry the Logged markers across by account number.