RO Import Guide
RO Import Guide
Three ways a BOM becomes a Requirements Order. Pick the one that matches what you have in front of you.
| You have | Use | What it does |
|---|---|---|
| A FieldPulse job number | Import → FP # | Goes and finds the BOM itself |
| A BuilderTrend job | Import → BT | You pick which document is the BOM (BT jobs are also polled — see Polling) |
| A spreadsheet on your desktop | Import → Upload | Reads the file you drop in |
Nothing becomes an RO until you press Accept on the review screen. Everything before that is a waiting room you can fix or reject.
Most ROs now arrive on their own through polling (see below). The three manual routes are for jobs the poller doesn't cover or that you want right now.
Every import runs the same two steps: the sheet is read into staged lines, then a description → SKU lookup fills in the QuickBooks item for lines that came across with no stock number. Only certain matches are written; the rest are held for you.
1. FP job number
Type the FP # crews use (e.g. 4235). It looks for the BOM in this order:
- Files on the FieldPulse job.
- If there are none, files on the project the job belongs to (commercial BOMs usually hang on the project).
- If there is no BOM file anywhere, the job's material list.
What counts as a BOM file: the file name must contain the letters bom (BOM, bom, Roof_BOM_v2 …). A spreadsheet named "Picklist.xlsx" or "Materials.xlsx" is not seen by FP import or FP polling.
On the manual FP # import: it never picks between two BOMs for you (it asks), and it will not import a BOM that isn't a spreadsheet — a PDF has to be converted first. (Polling is different: it handles text PDFs and scanned PDFs — see Polling.)
2. BuilderTrend job
BT has no API, so manual import drives a browser and takes about 30 seconds. It lists the documents in the job's Engineering folder and you choose which one is the BOM. BT cannot tell commercial from residential, so you check the Class yourself.
BT is also polled (see Polling): the poller finds BOM files on its own and stages them with Class Commercial. You only use this manual route for a file the poller hasn't picked up.
3. Drop a spreadsheet
Upload an .xlsx or .xlsm (a PDF is rejected). Until you link it, the RO's source is Manual — it isn't attached to any job.
Linking to an FP job — what "Check" does
On the review screen, set Source order # to FP and the job number, then press Check. Check reads FieldPulse live and fills the header in front of you:
| Field | What Check does |
|---|---|
| Customer | Overwritten with the FP job's customer |
| Class | Overwritten — from the FieldPulse project's workflow |
| Priority | Filled only if you left it blank |
| Required date | Filled only if you left it blank, from the class lead time |
| FP job status | Always FieldPulse's — you can't edit it here |
If the job has no project, or its project is on a workflow we don't map, Check leaves Class alone and tells you to set it — it will not guess. (This is the Check behaviour only; polled rows get Class differently — see Class below.) Some commercial jobs in FieldPulse still sit on the Service workflow, so they come in as Service and you change the Class on the RO screen.
It works the same whether you enter the FP # first or last. If it changes something you typed, it says so on the line under the box. It also stamps the FP # onto the row, which is what lets a later re-import update this RO instead of making a second one.
You don't need to save. Header fields save themselves as you change them. Accept is the only button.
Linked vs not linked — what actually differs
| Linked to FP | Not linked | |
|---|---|---|
| Customer / Class | Filled by Check | You key them |
| FP job status | Shows and stays current | Stays blank — correct, there's no job to read |
| Priority | From FP if you left it blank | You key it |
| Re-import of the same BOM | Updates the same RO | Creates a separate RO |
| Nightly status sync | Keeps status and priority current | Never touches it |
An unlinked RO is not broken — it just means nothing will ever update it automatically. If the work belongs to a real FP job, link it.
Same job, more than one BOM
Roof and electrical BOMs on one FP # are two ROs — they are told apart by the BOM file name, not the job. That is why the file name matters:
- Same FP # + same BOM name → an inbox row for it, once Accepted, refreshes that RO: quantities change in place, new SKUs are added (non-inventory lines are matched on description), and lines that disappeared from the BOM go on HOLD with an open "no qty" issue — they are never deleted. Every touched line is written to the audit log. Heads-up: this refresh does not check whether the line was already picked or ordered, so a quantity change or HOLD on a line with downstream activity needs a human look. The row only exists if a manual import or recheck created it (see Polling).
- Same FP # + different BOM name → a new, separate RO.
- Renaming a revised BOM (adding "-1") makes it a different BOM, so you get a second RO, not an update. If you mean it as a revision, keep the file name the same. (Planned, not built: content-hash change detection, "-revN" handling, a revision review screen and routing downstream-activity changes to Issues.)
Polling — how jobs get into the inbox by themselves (updated 2026-10-25)
IM2 checks FieldPulse and BuilderTrend on a timer. How often is the FieldPulse polling / BuilderTrend polling number on System Settings (hours between checks, 0 = off). Each sweep does the same thing:
- FieldPulse: look at every FP job in the status named in System Settings → FP Status Trigger (today: Pending Material; change the setting and polling follows — it is not hard-wired). BuilderTrend: look at every open BT job for .xlsx / .xls / .pdf files whose name looks like a BOM or picklist, in any folder of the job.
- FP file choice: a file counts only if its name contains bom. Job files are checked first; project files only if the job has none. Every BOM file found is staged as its own row (a job with a roof BOM and an electrical BOM gives two rows). The job's material list is used only when there is no BOM file; each live material list is its own row. Archived and Canceled material lists are skipped.
- For each, ask: is this (job, BOM name) already in the system? For FP, "already" means an RO exists, or an inbox row is still open (Awaiting Review, Held, Error).
- If not, stage a new inbox row under Awaiting Review.
PDFs. Polling reads text PDFs by converting them to a sheet, and runs OCR on scanned PDFs. OCR rows are flagged PDF BOM Error and need a careful look before Accept. Two System Settings switches — Excel only (FP) and Excel only (BT) — set to Yes make polling skip PDFs altogether.
Class on polled rows. FP rows take the QuickBooks customer type of the matched customer (Residential / Commercial …). Blank, no match, or more than one possible match → Service. BT rows come in as Commercial. Always check the Class chip before Accept. (Check on the review screen later overwrites it from the FP project workflow.)
It never touches a spreadsheet you dropped in yourself, and anything outside the FP Status Trigger has to be imported by hand — that is normal, not a failure.
What polling does NOT do
- It does not notice that a BOM file changed. If the job already has an RO for that file name, the sweep skips it ("already an RO") — even if the file was edited or replaced with the same name. To pull in a change today, import the FP # by hand (it stages a row only if something differs; otherwise "nothing to import") or ask for a recheck run, which compares every FP RO to its source and stages change rows. The recheck is manual — it is not on the polling timer.
- BuilderTrend: a changed file with the same name is never re-staged, and an inbox row in any status (including Rejected) blocks its re-staging.
- It does not re-stage a job that already has an RO.
- It does not move anything around.
Rejected rows and re-polling. Reject only closes the inbox row. If the FP job is still in Pending Material and still carries the same material list / BOM, the next sweep sees "no RO, no open inbox row" and stages it again. That is by design (Dave, 2026-09-17): Reject means "not this copy", not "never this job". To stop a job coming back, fix the source — remove the invalid material list or spreadsheet from the FP job, or move the FP job out of Pending Material. (BuilderTrend is the exception: a BT row in any status — including Rejected — blocks that BOM file name from re-staging. A new file name is needed.)
Deleting an RO. An Admin deleting an RO (Order Maintenance → Delete RO) puts the job's original inbox row back to Awaiting Review with the note "RO N was deleted — back in the queue". Nothing is re-fetched from FP — it is the same row, re-opened, so the job can be re-imported cleanly or Rejected. Because that row is open again, the poller will not stage a duplicate for it.
When something looks wrong
- "has a BOM but it is not a spreadsheet" — manual FP # import only; the file is a PDF. Convert it (polling handles PDFs on its own).
- Job in the trigger status but nothing staged — check the file name contains bom, and whether an RO or open inbox row already exists for that name.
- "nothing to import, needs a human" — no spreadsheet and no material list on the job. Attach the BOM in FieldPulse, then import again.
- "already waiting in the inbox" — someone already staged it. Open that row.
- Lines on hold — fix the SKU or quantity right on the review screen before you Accept, and they never become Issues at all.
Class and Type are two different fields
Class is the QuickBooks class the RO posts to — Residential, Commercial, Service, Administration. On a polled row it comes from the QuickBooks customer type (blank/ambiguous → Service; BT → Commercial). Check replaces it from the FieldPulse project's workflow. You can always change it.
Type is what kind of demand the RO is: Job (from a BOM, against a job — this is everything you import today), Stock, or Truck for replenishment orders that have no job and no customer. Imported ROs are always Job. Stock and truck orders book to SA:Admin, class Administration.
You do not need to touch Type on an imported RO. It is on the screen because the RO Inquiry filter uses it.
In summary — pick the outcome you want
| What you want | What to do | What you get |
|---|---|---|
| The RO gets created automatically from the BOM | Attach a file with bom in its name to the job (or its project) in FieldPulse and leave the job in the polling status (Pending Material today) | The watcher stages the BOM once (named "bom" files, or the material list if none). It does not re-stage when the file later changes — run a manual FP # import to pull changes; then Accept updates quantities in place, adds new lines, and puts removed lines on HOLD with an issue |
| The RO linked to the FP job, but you decide when it updates | Type the FP job number in the RO Inbox and import | Same link, same refresh behaviour, but only when you run it. Customer, Class, FP job status carry over; priority and required date fill only if blank |
| A spreadsheet that isn't in FieldPulse, linked to the FP job anyway | Drop the file, then key the FP # in Source order # and press Check | The file's lines, plus everything FieldPulse knows about the job. Refreshes when you drop the same file name again |
| A spreadsheet with no FieldPulse link at all | Drop the file and leave Source order # blank | An RO with only what's in the file. No customer, class, status or priority from FP, never polled, no FP job status on the RO |
| A BuilderTrend job | Type the BT job number and pick the file from Documents → Engineering | An RO linked to BT. BT is polled for new BOM files, but a changed file with the same name is never picked up — re-import by hand under a new name. Check the Class |
| Two ROs on one job (roof and electrical) | Import each BOM by its own file name against the same FP # | Two separate ROs on the same job. They never merge and never overwrite each other |
| A brand-new RO instead of an update | Rename the BOM file | A second RO. The file name is the identity — a rename is always a new RO, never a revision |
| A stock or truck replenishment order | RO Inquiry → + New RO, set Type to Stock or Truck | An RO with no job and no FP link, booked to SA:Admin / class Administration |
| A job with no BOM file anywhere | Import the FP job number as usual | The job's FieldPulse material list is used instead — this only happens when there is no BOM file on the job or its project |
If none of these is what you got, the guide above says why — start with "When something looks wrong."
After Accept, what the marks did (2026-09-10)
On the review screen the non-inventory / drop buttons and the per-line × only mark lines. Accept is what applies them: marked-drop lines are left off the RO (they stay in the staged row as the record), marked-non-inventory lines go on as non-inventory demand with no issue raised. Until you press Accept, nothing has changed.