MedBridge Sales Ops
Workflows for the MedBridge Sales Ops API: a shared CRM, quote, logistics, and milestone engagement data service for humanitarian medical supply chain at base URL <TASK_ENV_BASE_URL> (provided by the task runner).
Quick Reference
- API Schema — full collection list, record shapes, cross-reference keys
- Business Rules — tier matching, payment terms, freight validation, revenue recognition, event/voucher tasks
Load the corresponding reference when you need detailed field paths or rule specifics while executing a workflow.
Overall Approach
- Identify which workflow the prompt describes: quote decision package, indicative module quote, or engagement reconciliation.
- Fetch all required API records in parallel where possible. Start with the target record (quote, RFQ, or opportunity), then fan out to linked records (customer, product, freight, invoices, payments, revenue journals, events, vouchers, policies).
- Apply the business rules from business_rules.md to derive computed values.
- Fill the answer template exactly — every field populated, no invented values, no markdown wrapper.
Workflow 1: Quote Decision Package
Triggers: Revised quote with freight comparison. Prompt mentions a quote ID (Q-TR-WC-..., Q-TR-LD-..., Q-TE-...), customer name, product code, confirmed quantity, and quote date. Template keys include quote_summary/pricing, freight_options/transport_decisions, and policy_flags/client_warnings.
Step 1 — Fetch Core Records
Fetch in parallel:
GET /api/quotes/<quote_id> — the quote
GET /api/customers/<quote.customer_id> — the customer
GET /api/products/<quote.primary_product_code> — the product
GET /api/freight-quotes — all freight records (filter by quote_id client-side)
GET /api/policies — all policies (filter by policy_area client-side)
Step 2 — Determine Pricing
Read the confirmed quantity from the quote or its line items. Match the product's price tier:
- Iterate
product.price_tiers in order.
- Select the first tier where
min_qty <= confirmed_quantity and (max_qty is null or confirmed_quantity <= max_qty).
- Extract
unit_price_usd, lead_time_days, shelf_life_months.
Compute exw_total_usd = confirmed_quantity * unit_price_usd to two decimals.
Step 3 — Build Freight Options
Filter freight records to those with quote_id == <target_quote_id>. Exclude records where status is stale or mismatch. For each remaining record:
- Validity:
valid_until >= quote_date → VALID; otherwise STALE, source_is_stale = true.
- Grand total:
exw_total_usd + freight.cost_usd.
- Risk: Uppercase
route_risk. Derive risk_flag from route risk and risk_notes.
- Collect AIR, SEA, ROAD in that order.
Step 4 — Recommend Mode
Pick the lowest-cost valid (non-stale) freight option. If a valid option has HIGH route risk, skip it and recommend the next lowest-cost valid option. If no valid option survives, flag and default to the lowest-cost overall with a warning.
Step 5 — Policy Flags and Warnings
freight_reconfirmation_required: always true when freight options are included (POL-FREIGHT-RECONFIRM).
all_freight_options_valid_on_quote_date: true only if every collected freight record has valid_until >= quote_date.
payment_terms: resolve from customer profile (see business rules).
- For templates with
client_warnings: include a freight_warning if any freight option is stale or has HIGH risk.
quote_basis: "EXW" or "EXW_PLUS_FREIGHT_OPTIONS" based on incoterm.
Step 6 — Fill the Template
Use only the exact keys from answer_template.json. All money to two decimals. All dates as YYYY-MM-DD. Return raw JSON.
Workflow 2: Indicative Module Quote
Triggers: RFQ-based module quote with no freight. Prompt mentions an RFQ ID (RFQ-TR-...), customer name, module product codes, EXW-only basis. Template keys include quote_header, line_items, and quote_controls.
Step 1 — Fetch Core Records
Fetch in parallel:
GET /api/rfqs/<rfq_id> — the RFQ
GET /api/customers/<rfq.customer_id> — the customer
GET /api/products/<each_requested_module.product_code> — one per module
GET /api/policies — all policies
Step 2 — Verify EXW-Only Condition
Check rfq.destination — if it says "pending" or "to be confirmed", freight must be excluded. Check rfq.incoterm_requested — if "EXW", no freight. Apply policy POL-INDICATIVE-EXW.
Step 3 — Build Line Items
For each entry in rfq.requested_modules:
- Fetch the product by
product_code.
- Match the price tier to
quantity (same tier logic as Workflow 1).
- Extract
unit_price, lead_time_days, shelf_life_months.
- Compute
line_total = quantity * unit_price to two decimals.
- Include
article_number from the product record.
Critical: Do not split modules into components. Quote at the module product code level only. The component_composition_distractors field in the RFQ warns against this.
Step 4 — Quote Controls
grand_total: sum of all line_total values.
freight_excluded: true.
payment_terms: PREPAY_100 for new NGO clients; otherwise from customer payment_profile.
offer_validity_days: 30.
who_documentation_required: true for IEHK, cholera, or field clinic families.
Step 5 — Fill the Template
Return raw JSON matching the template exactly.
Workflow 3: Engagement Reconciliation
Triggers: Account review, milestone reconciliation, event briefing follow-up. Prompt mentions an opportunity ID (OPP-TR-...), customer ID (CUST-...), a contact name, and optionally event/voucher codes. Template keys include account_status/engagement_reconciliation, milestones, revenue_recognition/invoice_actions, event/event_actions, and follow_up_tasks.
Step 1 — Fetch Core Records
Fetch in parallel:
GET /api/opportunities/<opportunity_id> — the opportunity
GET /api/customers/<opportunity.customer_id> — the customer
GET /api/invoices — all invoices (filter by opportunity_id client-side)
GET /api/payments — all payments (filter by opportunity_id client-side)
GET /api/revenue-journals — all revenue journals (filter by opportunity_id client-side)
GET /api/events — all events (filter by opportunity_id client-side)
GET /api/vouchers — all vouchers (filter by opportunity_id client-side)
Step 2 — Build Milestone Table
For each phase in opportunity.phases:
- Find the invoice by
phase.invoice_id.
- Determine
payment_status: PAID if invoice.status == "paid", UNPAID for "unpaid"/"overdue"/"draft".
paid_amount from invoice.paid_amount_usd. unpaid_amount from invoice.outstanding_amount_usd.
- For revenue recognition: if invoice is paid, check for a revenue journal matching
phase_id or invoice_id. If found → RECOGNIZED; if paid but not found → MISSING_REVENUE_JOURNAL; if unpaid → NOT_REQUIRED_UNPAID.
Step 3 — Reconciliation Summary
opportunity_matches_milestones: sum of phases[].amount_usd == won_amount_usd.
outstanding_balance: sum of invoice outstanding_amount_usd across all invoices for this opportunity.
- Revenue recognition status: COMPLETE_FOR_PAID_MILESTONES if every paid milestone has a journal, MISSING_FOR_PAID_MILESTONES if any paid milestone lacks one.
Step 4 — Accounting Action
If any paid milestone lacks a revenue journal, generate an accounting action:
action: RECORD_REVENUE_MS<N> (N = milestone number, 1-based from phase order).
debit_account: DEFERRED_REVENUE.
credit_account: IMPLEMENTATION_SERVICES_REVENUE.
amount: the paid invoice amount.
owner_queue: ACCOUNTING.
Step 5 — Collection Task
For each unpaid invoice:
- If
due_date > current business date → MONITOR_UNPAID_NOT_DUE, owner_queue: ACCOUNT_MANAGEMENT.
- If
due_date <= current business date → SEND_COLLECTION_NOTICE, owner_queue: COLLECTIONS.
- Set
contact_name to the contact from the prompt.
Step 6 — Event and Invitation
For the event matching the opportunity:
- Map
event.status: "scheduled" → SCHEDULED, "confirmed" → SCHEDULED, "live" → ACTIVE, "completed" → COMPLETED, "tentative" → SCHEDULED.
- Look up the voucher by
event.voucher_code (or voucher.code). Map voucher status: "active" → ACTIVE, "draft" → DRAFT, "expired" → EXPIRED.
- For
voucher_discount/discount_amount: use discount_percent from the voucher record.
- If event status is
scheduled or confirmed: invite_action = SEND_BRIEFING_INVITE (or SEND_EVENT_INVITATION, matching the template's enum).
- Invite task
owner_queue: ACCOUNT_MANAGEMENT.
- Set invite task
due_date: typically 7-14 days before event.event_date, or the current business date if the event is sooner.
Step 7 — Fill the Template
Return raw JSON matching the template exactly. Sort milestones ascending by milestone_id (MS1, MS2, MS3). All amounts to two decimals. All dates as YYYY-MM-DD.
1---2name: medbridge-sales-ops-163description: MedBridge Sales Ops API workflows for humanitarian medical supply chain. Prepares quote decision packages (pricing, freight comparison, policy checks), indicative module RFQ quotes (EXW-only, module-level), and engagement reconciliations (milestone cross-referencing, revenue recognition, collection follow-ups, event/voucher invite tasks). Use for tasks referencing MedBridge Sales Ops, TASK_ENV_BASE_URL, quote IDs prefixed Q-TR, Q-TE, or Q-DIS, RFQ IDs prefixed RFQ-TR or RFQ-TE, opportunity IDs prefixed OPP-TR, customer IDs prefixed CUST-, and medical product codes like WC-KIT, IEHK, LD-REAGENT, MAT-EMERG, CHOL, FCLINIC, or PPE.4metadata:5 source: https://skillmd.com/skills/prism-shadow/medbridge-sales-ops-166---78# MedBridge Sales Ops910Workflows for the MedBridge Sales Ops API: a shared CRM, quote, logistics, and milestone engagement data service for humanitarian medical supply chain at base URL `<TASK_ENV_BASE_URL>` (provided by the task runner).1112## Quick Reference1314- [API Schema](references/api_schema.md) — full collection list, record shapes, cross-reference keys15- [Business Rules](references/business_rules.md) — tier matching, payment terms, freight validation, revenue recognition, event/voucher tasks1617Load the corresponding reference when you need detailed field paths or rule specifics while executing a workflow.1819## Overall Approach20211. Identify which workflow the prompt describes: quote decision package, indicative module quote, or engagement reconciliation.222. Fetch all required API records in parallel where possible. Start with the target record (quote, RFQ, or opportunity), then fan out to linked records (customer, product, freight, invoices, payments, revenue journals, events, vouchers, policies).233. Apply the business rules from [business_rules.md](references/business_rules.md) to derive computed values.244. Fill the answer template exactly — every field populated, no invented values, no markdown wrapper.2526---2728## Workflow 1: Quote Decision Package2930**Triggers:** Revised quote with freight comparison. Prompt mentions a quote ID (`Q-TR-WC-...`, `Q-TR-LD-...`, `Q-TE-...`), customer name, product code, confirmed quantity, and quote date. Template keys include `quote_summary`/`pricing`, `freight_options`/`transport_decisions`, and `policy_flags`/`client_warnings`.3132### Step 1 — Fetch Core Records3334Fetch in parallel:35- `GET /api/quotes/<quote_id>` — the quote36- `GET /api/customers/<quote.customer_id>` — the customer37- `GET /api/products/<quote.primary_product_code>` — the product38- `GET /api/freight-quotes` — all freight records (filter by `quote_id` client-side)39- `GET /api/policies` — all policies (filter by policy_area client-side)4041### Step 2 — Determine Pricing4243Read the confirmed quantity from the quote or its line items. Match the product's price tier:44- Iterate `product.price_tiers` in order.45- Select the first tier where `min_qty <= confirmed_quantity` and (`max_qty` is null or `confirmed_quantity <= max_qty`).46- Extract `unit_price_usd`, `lead_time_days`, `shelf_life_months`.4748Compute `exw_total_usd = confirmed_quantity * unit_price_usd` to two decimals.4950### Step 3 — Build Freight Options5152Filter freight records to those with `quote_id == <target_quote_id>`. Exclude records where `status` is `stale` or `mismatch`. For each remaining record:5354- **Validity:** `valid_until >= quote_date` → VALID; otherwise STALE, `source_is_stale = true`.55- **Grand total:** `exw_total_usd + freight.cost_usd`.56- **Risk:** Uppercase `route_risk`. Derive `risk_flag` from route risk and `risk_notes`.57- Collect AIR, SEA, ROAD in that order.5859### Step 4 — Recommend Mode6061Pick the lowest-cost valid (non-stale) freight option. If a valid option has HIGH route risk, skip it and recommend the next lowest-cost valid option. If no valid option survives, flag and default to the lowest-cost overall with a warning.6263### Step 5 — Policy Flags and Warnings6465- `freight_reconfirmation_required`: always true when freight options are included (POL-FREIGHT-RECONFIRM).66- `all_freight_options_valid_on_quote_date`: true only if every collected freight record has `valid_until >= quote_date`.67- `payment_terms`: resolve from customer profile (see business rules).68- For templates with `client_warnings`: include a `freight_warning` if any freight option is stale or has HIGH risk.69- `quote_basis`: `"EXW"` or `"EXW_PLUS_FREIGHT_OPTIONS"` based on incoterm.7071### Step 6 — Fill the Template7273Use only the exact keys from `answer_template.json`. All money to two decimals. All dates as `YYYY-MM-DD`. Return raw JSON.7475---7677## Workflow 2: Indicative Module Quote7879**Triggers:** RFQ-based module quote with no freight. Prompt mentions an RFQ ID (`RFQ-TR-...`), customer name, module product codes, EXW-only basis. Template keys include `quote_header`, `line_items`, and `quote_controls`.8081### Step 1 — Fetch Core Records8283Fetch in parallel:84- `GET /api/rfqs/<rfq_id>` — the RFQ85- `GET /api/customers/<rfq.customer_id>` — the customer86- `GET /api/products/<each_requested_module.product_code>` — one per module87- `GET /api/policies` — all policies8889### Step 2 — Verify EXW-Only Condition9091Check `rfq.destination` — if it says "pending" or "to be confirmed", freight must be excluded. Check `rfq.incoterm_requested` — if `"EXW"`, no freight. Apply policy POL-INDICATIVE-EXW.9293### Step 3 — Build Line Items9495For each entry in `rfq.requested_modules`:96- Fetch the product by `product_code`.97- Match the price tier to `quantity` (same tier logic as Workflow 1).98- Extract `unit_price`, `lead_time_days`, `shelf_life_months`.99- Compute `line_total = quantity * unit_price` to two decimals.100- Include `article_number` from the product record.101102**Critical:** Do not split modules into components. Quote at the module product code level only. The `component_composition_distractors` field in the RFQ warns against this.103104### Step 4 — Quote Controls105106- `grand_total`: sum of all `line_total` values.107- `freight_excluded`: `true`.108- `payment_terms`: `PREPAY_100` for new NGO clients; otherwise from customer `payment_profile`.109- `offer_validity_days`: `30`.110- `who_documentation_required`: `true` for IEHK, cholera, or field clinic families.111112### Step 5 — Fill the Template113114Return raw JSON matching the template exactly.115116---117118## Workflow 3: Engagement Reconciliation119120**Triggers:** Account review, milestone reconciliation, event briefing follow-up. Prompt mentions an opportunity ID (`OPP-TR-...`), customer ID (`CUST-...`), a contact name, and optionally event/voucher codes. Template keys include `account_status`/`engagement_reconciliation`, `milestones`, `revenue_recognition`/`invoice_actions`, `event`/`event_actions`, and `follow_up_tasks`.121122### Step 1 — Fetch Core Records123124Fetch in parallel:125- `GET /api/opportunities/<opportunity_id>` — the opportunity126- `GET /api/customers/<opportunity.customer_id>` — the customer127- `GET /api/invoices` — all invoices (filter by `opportunity_id` client-side)128- `GET /api/payments` — all payments (filter by `opportunity_id` client-side)129- `GET /api/revenue-journals` — all revenue journals (filter by `opportunity_id` client-side)130- `GET /api/events` — all events (filter by `opportunity_id` client-side)131- `GET /api/vouchers` — all vouchers (filter by `opportunity_id` client-side)132133### Step 2 — Build Milestone Table134135For each phase in `opportunity.phases`:136- Find the invoice by `phase.invoice_id`.137- Determine `payment_status`: PAID if `invoice.status == "paid"`, UNPAID for "unpaid"/"overdue"/"draft".138- `paid_amount` from `invoice.paid_amount_usd`. `unpaid_amount` from `invoice.outstanding_amount_usd`.139- For revenue recognition: if invoice is paid, check for a revenue journal matching `phase_id` or `invoice_id`. If found → RECOGNIZED; if paid but not found → MISSING_REVENUE_JOURNAL; if unpaid → NOT_REQUIRED_UNPAID.140141### Step 3 — Reconciliation Summary142143- `opportunity_matches_milestones`: sum of `phases[].amount_usd` == `won_amount_usd`.144- `outstanding_balance`: sum of invoice `outstanding_amount_usd` across all invoices for this opportunity.145- Revenue recognition status: COMPLETE_FOR_PAID_MILESTONES if every paid milestone has a journal, MISSING_FOR_PAID_MILESTONES if any paid milestone lacks one.146147### Step 4 — Accounting Action148149If any paid milestone lacks a revenue journal, generate an accounting action:150- `action`: `RECORD_REVENUE_MS<N>` (N = milestone number, 1-based from phase order).151- `debit_account`: `DEFERRED_REVENUE`.152- `credit_account`: `IMPLEMENTATION_SERVICES_REVENUE`.153- `amount`: the paid invoice amount.154- `owner_queue`: `ACCOUNTING`.155156### Step 5 — Collection Task157158For each unpaid invoice:159- If `due_date` > current business date → `MONITOR_UNPAID_NOT_DUE`, `owner_queue: ACCOUNT_MANAGEMENT`.160- If `due_date` <= current business date → `SEND_COLLECTION_NOTICE`, `owner_queue: COLLECTIONS`.161- Set `contact_name` to the contact from the prompt.162163### Step 6 — Event and Invitation164165For the event matching the opportunity:166- Map `event.status`: `"scheduled"` → `SCHEDULED`, `"confirmed"` → `SCHEDULED`, `"live"` → `ACTIVE`, `"completed"` → `COMPLETED`, `"tentative"` → `SCHEDULED`.167- Look up the voucher by `event.voucher_code` (or `voucher.code`). Map voucher `status`: `"active"` → `ACTIVE`, `"draft"` → `DRAFT`, `"expired"` → `EXPIRED`.168- For `voucher_discount`/`discount_amount`: use `discount_percent` from the voucher record.169- If event status is `scheduled` or `confirmed`: `invite_action` = `SEND_BRIEFING_INVITE` (or `SEND_EVENT_INVITATION`, matching the template's enum).170- Invite task `owner_queue`: `ACCOUNT_MANAGEMENT`.171- Set invite task `due_date`: typically 7-14 days before `event.event_date`, or the current business date if the event is sooner.172173### Step 7 — Fill the Template174175Return raw JSON matching the template exactly. Sort milestones ascending by milestone_id (MS1, MS2, MS3). All amounts to two decimals. All dates as `YYYY-MM-DD`.