Pushing Won opportunities to Airtable¶
When a customer signs a BMS proposal in the client portal, the BMS automatically pushes the opportunity — and everything attached to it — into the shared Airtable base. This is what hands the new client off to the operational onboarding workflow. This page covers when the push runs, what it sends, how you trigger it, and what to do if it fails.
1. What the Airtable push is and when it runs¶
The Airtable push is a behind-the-scenes job that fires as soon as a customer signs their proposal in the portal. You don't kick it off manually — it runs by itself within a second or two of the signature, in the background, while the customer is still on the "thanks, you're signed" screen.
It sends the opportunity, the client and contact, every site on the proposal, every service, every shift and area inside those services, any C6 hygiene line items, and any consumables. By the time you next open the Airtable base, the new opportunity is sitting there in the Importing from BMS status with all of its supporting records already linked to it.
Nothing in Airtable is overwritten silently — the push looks for an existing record before creating a new one. If a client, contact, or site is already in Airtable (matched by ABN, name, or address), the push finds that record and updates it rather than creating a duplicate.
2. How the push is triggered¶
The push fires automatically when a customer signs their proposal in the client portal — there is no manual trigger.
Customer signs in the portal. When a customer clicks the Sign button on their proposal in the client portal, the sign confirmation goes through, and the push fires automatically straight after. You don't do anything. The push will have completed by the time you check the opportunity in the BMS a minute later.
3. What success looks like¶
If everything goes well, you'll see no SMS, no banner, no warning — the push completed quietly. To verify, open the shared Airtable base and search for the opportunity number (e.g. BMS5471). You should see:
- The Opportunity record sitting in the Importing from BMS status, assigned to Tom.
- Every site on the proposal linked from the Opportunity's
{Sites to quote on}field. - Every service linked from the Opportunity's
{Services to quote on}field, with the right service type, frequency, and price. - The client's contact record linked, with the contact's
{Opportunities}field including this opportunity. - Any consumables linked from the Opportunity's
{Consumables}view.
The Airtable opportunity stays in Importing from BMS — the push deliberately doesn't move it to Won. From there, the existing onboarding workflows in Airtable take over: the opportunity gets reviewed by Tom, then transitions through the rest of the Airtable sales pipeline as normal. That hand-off is the whole point of the push.
4. What failure looks like¶
If the push fails, two things happen at once: Glenn gets an SMS, and the opportunity page in the BMS shows a red "Airtable push failed" pill next to the opportunity title at the top of the page (visible to Admin and Sales users). You can hover over the pill to read the reason. Beside the pill is a Retry button — see §5 for when to use it.
The full error detail is also recorded permanently in a system table that Glenn can read in the Supabase Dashboard.
If Glenn asks you to look into a push failure: check the red pill on the opportunity page first — the hover text gives the reason. For most failures, Glenn will handle the fix himself and ask you to click Retry once he's done.
5. The push-status indicator¶
Next to the opportunity title at the top of the page, you'll see a small coloured label showing the push status — or nothing at all if no push has been attempted yet. Here's what each one means:
| Indicator | What it means |
|---|---|
| Nothing shown | No push has been attempted. The opportunity hasn't been signed yet, or was signed before this feature was added. |
| Grey "Pushing to Airtable…" | The push is running right now. Wait a few seconds — the label updates automatically without a page refresh. |
| Green "Pushed to Airtable" | Success. All records are in Airtable. |
| Amber "Pushed to Airtable with warnings" | The push succeeded, but one or more fields were left blank (see §7 on soft warnings). Hover the label to see which fields. |
| Red "Airtable push failed" | Something went wrong. Glenn will have received an SMS. Hover the label to read the reason. |
When you see the red label, there is a Retry button beside it. Clicking Retry re-runs the push immediately. Use it only after the underlying problem has been fixed — for example, Glenn has added the missing product to the Airtable Product list — or if Glenn specifically asks you to retry. Clicking it before the cause is addressed will just fail again.
The indicator is only visible to Admin and Sales users.
6. Common failures and what to do¶
A few failure modes show up in practice. In every case, the starting point is the same — check the red pill on the opportunity page, then contact Glenn — but it's useful to know what each one means so you can recognise them when Glenn describes them.
"Product not found in Airtable Product list." This happens when an opportunity has a consumable on it whose product hasn't been added to the Airtable Products table yet. The BMS won't create the product automatically (the Airtable Products table is the canonical product catalogue and is maintained manually). To fix it, the product needs to be added to Airtable first, then the push re-run with the Retry button. Contact Glenn — he'll add the product and ask you to retry.
"No services found on this opportunity." This happens if an opportunity has consumables but no services at all. We don't support this case yet. If it ever comes up legitimately, contact Glenn.
Any other failure. Network errors from Airtable, missing data on the opportunity, anything unexpected — contact Glenn. The hover text on the red pill will name the reason; Glenn will diagnose and advise.
If you get an SMS about a push failure outside business hours, it can wait until morning unless the customer is actively asking why their opportunity hasn't appeared in Airtable. The signed contract is already in place; the Airtable record is just a hand-off to onboarding and isn't time-critical for the customer.
7. Soft warnings — these are not failures¶
Sometimes the push succeeds but the amber "Pushed to Airtable with warnings" label appears. These are informational, not errors. They mean the push completed and everything landed in Airtable, but one or two fields were left blank because the BMS didn't have the information to fill them in. Hover the amber label to see which fields were affected.
The fields this can happen on today are State, Postcode, and Region on a site. If any of those are blank in the BMS site record, the push leaves the corresponding Airtable field blank and notes the skip.
You don't have to do anything about a soft warning — the push succeeded. If you want next time's push to be clean, open the affected site in the BMS, fill in the missing State / Postcode / Region, and save. The next time the same opportunity is re-pushed (or a different opp at the same site is pushed for the first time), the missing field will be populated automatically.
In production, current data already has all three columns filled in, so soft warnings shouldn't appear in practice. If you see one, treat it as a heads-up that a site needs cleaning up, not as something that broke.
8. Further reading¶
For the technical reference — what the push does step by step, what each entity looks like in Airtable, how failures are handled internally — see the technical reference. That doc is aimed at developers and Claude Code; you shouldn't need it for day-to-day operations.