Reprocess Transaction

Reprocess Transaction

Triggers customscript_orderful_transaction_mr (the inbound MapReduce) for a single Orderful Transaction record by POSTing { "action": "reprocessTransaction", "recordId": <id> } to the SuiteApp's customscript_orderful_agent_write_rl RESTlet over TBA. Every agent-write request must also carry authorizedBy + agentPlanId — since v1.22 the RESTlet rejects the request before it dispatches on action without them. The script fills these from AGENT_AUTHORIZED_BY in the customer's .env, falling back to cli:<os-user>.

The handler (handleReprocess in the SuiteApp) loads the transaction, resets custrecord_ord_tran_retry_count to 0, resets the status from Stale to Pending if applicable, then dispatches the inbound MR with the single transaction's internal ID. This is the same code path the Reprocess button on the transaction record runs.

When to use this skill

• "reprocess transaction 39449 for cambridge-pavers"
• "retry the failing 850 — internal id 39449"
• "the customer's PO failed; rerun it"
• "/reprocess-transaction 39449"
• "this transaction is Stale, kick it back to Pending"

Inputs the skill needs

• Customer slug — which ~/orderful-onboarding/<slug>/ to use. Ask if not specified; list the available dirs.
• Transaction internal ID — the id of the row in customrecord_orderful_transaction. This is the NetSuite internal ID, not the Orderful UUID.

If the user only has the Orderful UUID, ask them to look up the corresponding NS internal ID in NetSuite first (search customrecord_orderful_transaction by custrecord_ord_tran_orderful_id).

The recipe

Step 1 — Pick the customer

List ~/orderful-onboarding/ and confirm which customer the user wants. If the dir has no .env, stop and direct the user to /netsuite-setup.

Step 2 — Run the script

node <path-to-this-skill>/reprocess-transaction.mjs ~/orderful-onboarding/<slug> <transaction-id>

The script:

1. Loads the customer's .env and picks NS_SB_* or NS_PROD_* based on ENVIRONMENT.
2. Looks up the transaction's current status via SuiteQL. This is a guard rail — calling reprocess on certain statuses is a no-op or actively harmful (see Status guard below).
3. If the status is not eligible for reprocess, exits with a clear explanation and does not call the RESTlet.
4. If eligible, TBA-signs a POST to the RESTlet with { "action": "reprocessTransaction", "recordId": <id> }.
5. Prints the response.

Step 3 — Read the result

A successful response looks like:

{ "status": "success", "recordId": 39449 }

The MR is now queued in NetSuite — the actual reprocessing happens asynchronously, and the response carries no taskId. Verify with monitor-mr using the marker pattern (capture the marker before Step 2 when you can):

# before triggering (optional but ideal on noisy/prod accounts):
node skills/monitor-mr/monitor-mr.mjs <customer-dir> logs --flow reprocess --tail 1   # note "marker: N"
# after triggering:
node skills/monitor-mr/monitor-mr.mjs <customer-dir> watch --flow reprocess --after-id <N> --ot <recordId>

Completion is detected by the next MR SUMMARY log row; the log line Beginning to process NetSuite Orderful Transaction internalid: <recordId> confirms the run picked up your record, and the final OT status (Success / Error + error text) is the authoritative outcome. custrecord_ord_tran_retry_count should have reset to 0. Manual fallback: Customization > Scripting > Map/Reduce Script Status in the NS UI.

For after-the-fact diagnosis (the reprocess already ran, what did it log?) use which-script-ran: its lifecycle query pulls every log line mentioning the OT id across all three processing-MR deployments in one shot — no marker needed. Note the reprocess task lands on any free deployment of the script, so per-deployment UI log checks miss it half the time.

Status guard

orderful_inboundProcessing_MR.queryPendingInboundOrderfulTransactions() excludes transactions whose status is Success, Ignore, PendingCustomProcess, or Stale from its bulk processing pass. The single-transaction reprocess path bypasses that filter — meaning if you call reprocess on a transaction in one of those statuses, the MR will load it and try to process it again. That's almost always wrong:

The script enforces the ❌ rows; ⚠️ rows proceed but the script logs a warning.

Required role permissions

The token's role needs all of the base TBA permissions in INTEGRATION-RECORD-SETUP.md, plus these specific ones for reprocess:

The Custom Record Entries permission is the most commonly missed one. It lives on the Lists subtab of the role, not the Custom Record subtab. With access type CUSTRECORDENTRYPERM, NetSuite ignores per-record-type permissions and the custom record's own Permissions tab — only the generic Lists permission counts.

Administrator already has all three. Custom roles often have the SuiteScript permissions but not Custom Record Entries with Edit; that's the typical failure mode. See troubleshooting below for the exact error message each missing permission produces.

Troubleshoot if needed

Behaviour rules

1. Never invoke without explicit customer slug AND transaction ID. Ask the user for both; don't pick or guess. The transaction ID must be the NetSuite internal ID, not the Orderful UUID.
2. Honor the status guard. Don't suggest workarounds (e.g., "change the status to Error first") just to bypass the refusal. If the user truly intends to reprocess a successful transaction, they should make that decision deliberately in the NS UI.
3. Don't poll for completion in this skill. The MR is asynchronous. Return the success response and follow through with monitor-mr (watch --flow reprocess --ot <recordId>) to confirm the outcome.
4. Don't assume sandbox vs. production. The script reads ENVIRONMENT from the .env. If the user expected production but the env says sandbox (or vice versa), ask before changing.
5. One transaction per invocation. No batch mode. If the user wants to reprocess multiple, run the skill multiple times — they can decide which IDs deserve retry.
6. Don't paste TBA secrets into chat. Everything stays in the .env; the script reads it locally.
7. If reprocess succeeds but the transaction lands back in Error, don't loop. Diagnose the underlying error first. Repeated reprocess calls on a structurally-broken transaction don't help and pollute the audit trail.

Reference material

• The agent-write RESTlet (the endpoint this skill posts to): FileCabinet/SuiteApps/com.orderful.orderfulnetsuite/ConfigAndUISupport/orderful_agentWrite_RL.ts in the netsuite-connector repo. Action used here: reprocessTransaction
• The reprocess handler: FileCabinet/SuiteApps/com.orderful.orderfulnetsuite/TransactionHandling/common/action.handlers.ts → handleReprocess
• The MR being dispatched: customscript_orderful_transaction_mr — defined in Objects/customscript_orderful_transaction_mr.xml (entry point: TransactionHandling/orderful_inboundProcessing_MR.ts)
• Transaction status enum: Models/orderful_transaction.ts → OrderfulTransactionStatus
• Status filter logic (which statuses the MR's bulk pass excludes): Repositories/orderful_transaction.repository.ts → queryPendingInboundOrderfulTransactions
• Custom record schema: reference/record-types.md §customrecord_orderful_transaction
• Companion skill: /run-poller — triggers the same MR but for all pending transactions, not a single one
• Companion skill: /reconcile-860-with-so — when reconciling change orders against open Sales Orders across an ERP cutover, that skill identifies which customrecord_orderful_transaction rows (if any) need reprocessing through this one