| name | run-poller |
| description | Trigger Orderful's inbound polling MapReduce in a NetSuite customer's account by calling the SuiteApp's run-poller RESTlet. Use when the user wants to manually pull pending inbound EDI transactions from Orderful into NetSuite without opening NetSuite to run the script deployment, or says things like "/run-poller", "run the poller for <customer>", "trigger inbound polling", "kick off the poller", "pull EDI transactions for <customer>", or "poll Orderful for <customer>". |
Run Inbound Poller
Triggers customscript_orderful_inbound_mr (the inbound polling MapReduce) in a customer's NetSuite by POSTing { "action": "triggerInboundPolling" } to the SuiteApp's customscript_orderful_agent_write_rl RESTlet over TBA. The RESTlet is the generic Orderful Agent write surface; this skill exercises only its triggerInboundPolling action.
The polling MR pulls pending transactions from Orderful's polling bucket(s) into NetSuite. It runs on a 15-minute schedule by default; this skill is for ad-hoc triggers — after configuration changes, when debugging stuck transactions, during demos, or any time a contractor would otherwise open NetSuite to run the script deployment manually.
When to use this skill
- "run the poller for cambridge-pavers"
- "I just changed the polling bucket — pull now"
- "trigger inbound polling for "
- "the customer says they're missing 850s — kick off the poller"
- "/run-poller"
Inputs the skill needs
- Customer slug — which
~/orderful-onboarding/<slug>/ to use. Ask if not specified; list the available dirs.
That's it. The customer's .env (created by /netsuite-setup) supplies everything else.
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 — Trigger the poller
Run the script:
node <path-to-this-skill>/run-poller.mjs ~/orderful-onboarding/<slug>
The script loads the customer's .env, picks NS_SB_* or NS_PROD_* based on ENVIRONMENT, TBA-signs a POST to the RESTlet URL with { "action": "triggerInboundPolling" } as the body, and prints the response.
Step 3 — Read the result
A successful response looks like:
{
"status": "success",
"taskId": "MAPREDUCETASK_...",
"mrStatus": {
"type": "task.MapReduceScriptTaskStatus",
"taskId": "MAPREDUCETASK_...",
"scriptId": 546,
"deploymentId": 4,
"status": "PENDING",
"stage": null
},
"scriptId": "customscript_orderful_inbound_mr",
"deploymentId": "customdeploy_orderful_inbound_mr"
}
taskId is the NetSuite task scheduler ID for the running MapReducemrStatus.status will be PENDING, PROCESSING, COMPLETE, or FAILED — PENDING/PROCESSING is normal; the task continues server-side after this skill returns
To verify execution, hand the taskId to monitor-mr:
node skills/monitor-mr/monitor-mr.mjs <customer-dir> watch --flow inbound-polling --task <taskId>
It blocks until the task completes, surfaces the execution log (including the end-of-run SUMMARY with mapErrors/reduceErrors), and flags the chained processing run. Manual fallback: NetSuite UI Customization > Scripting > Script Deployments > "Orderful | Polling Inbound Transactions" > Execution Log.
Heads-up when verifying downstream: if the chained inbound-processing run shows mapKeys: {}, check whether the poll actually created OTs and whether they pass the pending-query filters — per source the ~10-minute freshness gate only bites around 00:00–00:10 account time, so it's rarely the reason (see reference/mapreduce-monitoring.md). To push one specific id through immediately, use reprocess-transaction. For after-the-fact "what did the scripts log about this transaction?", use which-script-ran.
Required role permissions
The token's role needs all of these on Setup > Users/Roles > Manage Roles > [role] > Permissions > Setup tab:
- Log in using Access Tokens = Full
- REST Web Services = Full
- SuiteScript = Full (executes the RESTlet itself)
- SuiteScript Scheduling (no level — just add the row; required because the RESTlet calls
task.create() to submit the MapReduce)
Administrator already has all four. Custom roles commonly ship with the first two but not the last two — that's the default failure mode for a fresh integration. See troubleshooting below for the specific error messages each missing permission produces.
Step 4 — Troubleshoot if needed
| Symptom | Likely cause | Fix |
|---|
404 with SSS_INVALID_SCRIPTLET_ID (or older accounts: INVALID_LOGIN_INVALID_SCRIPT_ID / INVALID_LOGIN_ATTEMPT) on a .env already validated by /netsuite-setup | Customer's installed SuiteApp version is older than the agent-write RESTlet. | Upgrade the SuiteApp via My SuiteApps to the version that includes NS-926 (netsuite-connector#758); or fall back to running the MR manually (NetSuite UI: Customization > Scripting > Scheduled Script Status > New > pick customscript_orderful_inbound_mr) |
INVALID_LOGIN_ATTEMPT and /netsuite-setup Step 5 also fails | Bad TBA credentials | Re-validate via /netsuite-setup; the Login Audit Trail diagnostic in that skill's Step 5 isolates which value is wrong |
Response body contains INSUFFICIENT_PERMISSION with message "You need the 'SuiteScript' permission..." | Token's role is missing the SuiteScript permission | Setup > Users/Roles > Manage Roles > [role] > Permissions > Setup tab — add SuiteScript = Full |
Response body contains INSUFFICIENT_PERMISSION with no specific permission named (or "You do not have permission to perform this operation") | Token's role can't submit MapReduce tasks via task.create() | Setup > Users/Roles > Manage Roles > [role] > Permissions > Setup tab — add SuiteScript Scheduling (no level selector — just add the row). Note: this is a different permission from "SuiteScript". Most custom roles need both |
| MR runs but processes 0 transactions | custscript_orderful_polling_bucket company-level script param is empty | Customization > Scripting > Scripts > "Orderful | Polling Inbound Transactions" > Deployments > the deployment > script param values |
Behaviour rules
- Never invoke the script without an explicit customer slug. Ask the user which customer; don't pick one.
- Don't poll for completion in this skill. The MR is asynchronous. Return the
taskId and follow through with monitor-mr (watch --flow inbound-polling --task <taskId>) for completion and output verification.
- If the endpoint 404s, do not retry or guess. Report the version-mismatch fix from Step 4 and stop. Don't fall back silently to a different deploy ID.
- 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.
- One customer per invocation. No batch mode. Each customer's TBA token is per-account; running across multiple customers needs multiple invocations and is the user's call to make sequentially.
- Don't paste TBA secrets into chat. Everything stays in the
.env; the script reads it locally.
Reference material
