Run Poller

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. 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 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 MapReduce
• mrStatus.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

Behaviour rules

1. Never invoke the script without an explicit customer slug. Ask the user which customer; don't pick one.
2. 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.
3. 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.
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 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.
6. Don't paste TBA secrets into chat. Everything stays in the .env; the script reads it locally.

Reference material

• customscript_orderful_inbound_mr (the MR being triggered) — defined in Objects/customscript_orderful_inbound_mr.xml in the netsuite-connector repo
• The agent-write RESTlet (the endpoint this skill posts to): FileCabinet/SuiteApps/com.orderful.orderfulnetsuite/ConfigAndUISupport/orderful_agentWrite_RL.ts — introduced in netsuite-connector#758 (NS-926). Action used here: triggerInboundPolling
• Polling docs: docs.orderful.com — inbound poller
• NetSuite N/task module: https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4623372451.html