Skip to content

Medical Representatives (Field-Force CRM)

Manage a pharma/device distributor's field force: territories, MR profiles, the client institutions they visit, and the mandatory Daily Call Report (DCR). Every MR is an HR employee first — the MR profile is a field-force extension, not a separate staff record.

Screenshot: MR home dashboard — TODO

Medical → MR (/medical/mr) shows active MRs, DCRs submitted today, territories and client institutions, with shortcuts into setup and field operations.

Set up territories

Medical → MR → Territories (/medical/mr/territories). Territories form a three-level tree — Region → Area → Territory — via the Parent field. Assign a manager by HR employee number. MRs, clients and (in later phases) analytics roll up through this tree.

Create MR profiles

Medical → MR → MR Profiles (/medical/mr/profiles). Each profile needs an existing HR employee number — create the employee in HR first; the form rejects unknown employees and an employee can hold only one MR profile. Set designation (MR / Senior MR / ASM / RSM), territory, monthly sales target and daily expense limit.

Register client institutions & contacts

Medical → MR → Clients (/medical/mr/clients). An institution is a hospital, clinic, pharmacy or wholesaler. The type drives the later order/sample workflow. Credit Limit is used by the order credit check (Phase 3). Open an institution's detail page to add contacts — doctors, pharmacists, purchasing officers. Phone numbers must be E.164 international format (+9779812345678).

Record a Daily Call Report

Medical → MR → Daily Call Reports (/medical/mr/dcr).

  1. Start DCR — pick the MR and date (defaults to today). If the browser allows location access, GPS check-in is captured automatically. One DCR per MR per day — a second attempt for the same day is rejected.
  2. On the DCR detail page, record each call: institution, call type (detailing, sample drop, RCPA audit, order collection…), outcome, and sample value if samples were given.
  3. Check Out & Submit — locks the report (Drug Act 2035 record; submitted DCRs cannot be edited or deleted) and queues the attendance event for HR (listener lands in Phase 3).

Sample value cap

The monthly per-MR sample value cap (SAMPLE_VALUE_CAP_NPR under Drug Act 2035) is seeded PROPOSED and therefore not enforced until a compliance admin enacts it for the fiscal year in the compliance dashboard. Once enacted, adding a call that would push the MR over the monthly cap is rejected with the amount already distributed.

Plan the month (Tour Plans)

Medical → MR → Tour Plans (/medical/mr/tour-plans). A Monthly Tour Plan (MTP) is the MR's pre-planned route for one calendar month.

  1. New Tour Plan — pick the MR and month (YYYY-MM). One plan per MR per month.
  2. On the detail page, add planned visits: a date within the month + the institution.
  3. Submit for approval — moves the plan to the manager's queue.
  4. Manager review (Approval queue, /medical/mr/tour-plans/queue): Approve or Reject with a note. Approval is blocked if any planned date falls on the MR's approved HR leave — conflicting dates are highlighted; the MR must revise first.

MTP compliance % (actual DCRs vs approved planned visits this month) and the pending-approval count surface as dashboard metrics on the MR home.

Attendance (automatic)

Submitting a DCR automatically marks the MR present in HR attendance for the report date — no separate punch needed. This runs in the background via the outbox event bus; if the employee has no shift assigned it is skipped (a warning is logged) and the DCR is unaffected.

Secondary orders (Pipeline B)

Medical → MR → Secondary Orders. Take a pharmacy/wholesaler order: pick MR + institution, add line items (materials products) with qty + price. Confirm runs a credit check — outstanding AR for the institution + its credit_limit; over-limit confirms are blocked. On confirm, inventory is issued and accounting is notified in the background (needs the tenant's inventory GL config + a stocked warehouse to post; skips gracefully otherwise). Sample drops on a DCR (with an item + warehouse) deduct field stock the same way.

Targets, commission & expenses (P4)

  • Targets & Performance: set a target per MR/period/category with a commission rate. Recompute pulls achievement from confirmed orders; Finalize locks commission (achieved × rate) — it then flows into the MR's next payroll run automatically (no manual entry).
  • Expense Claims: MR submits travel/meal/fuel/lodging claims (daily cap enforced). Approve queues the reimbursement into payroll; Reject closes it.

RCPA — prescription audit (P5)

RCPA Audit: at a pharmacy visit record our brand vs a competitor's units, the prescriber and molecule. The board shows our-brand share of audited units for competitor intelligence.

Offline (P6)

The MR pages install a service worker so they open with no network; a banner shows when you're offline and how many changes are queued. DCR entries made offline are saved on the device and sync automatically when connectivity returns.

Mobile app APIs

The MR field app talks to the JWT-secured mobile layer at /api/mobile/v1/mr/** (same login/device flow as the rest of the mobile app). Each call is scoped to the signed-in MR's own profile:

  • GET /me, GET /dashboard — profile + KPIs
  • GET /clients?q=, GET /tour-plan — who/where to visit
  • GET /dcr/today, POST /dcr/check-in, POST /dcr/{id}/calls, POST /dcr/{id}/submit — the DCR loop
  • POST /expenses, POST /rcpa — field expense claim, prescription audit

MED_MR already appears in the mobile navigation (menu-driven), so no separate mobile registration is needed. The web module also works offline as a PWA (see Offline above).

Roles & permissions

Access is gated per resource: MED_MR:HOME/TERRITORIES/PROFILES/CLIENTS/DCR with READ/CREATE/UPDATE/DELETE actions — assign via the standard role editor. The MED_MR module must be enabled for the tenant (standalone module; requires HR for employee lookups, not the hospital suite).

Phase roadmap

Built: P1 Core DCR Loop, P2 Tour Planning, P3 attendance bridge (DCR → HR attendance). Deferred: inventory/COGS + credit-check integration (needs product-master + order-taking), targets & commission into payroll (P4), RCPA intelligence (P5), offline PWA (P6). Blueprint: docs/medical/mr_module_17.md.