MSP Teleplan Integration

MSP Module — User Manual

A practical guide for reception, billing staff, optometrists, and anyone using the MSP Teleplan module day-to-day. No code, no technical jargon — written so a new staff member can pick this up in under 30 minutes.

1. What this module does, in plain terms

• Before this module existed, billing MSP meant logging into Teleplan separately, typing PHN numbers, copy-pasting eligibility responses, and tracking remittances by hand.
• This module brings all of that into Odoo:
• The module mirrors how the existing OHIP (Ontario) module works, so if you've used that, the MSP one feels familiar.

2. Who uses this module

3. Where things live in the menus

4. One-time setup (office manager / admin)

Done once per clinic. Skip this section if you're using the module day-to-day and the setup is already in place.

4a. Configure the company

Settings → General settings . Scroll to the MSP section:

4b. Configure clinics

MSP Claim → MSP Clinic. One record per physical clinic location:

• Name, address
• Data Centre Number
• Payee Number

4c. Configure doctors

MSP Claim → Doctors. One record per practitioner who will bill MSP:

• Practitioner Name
• Practitioner Number (6-digit MSP number)
• Default clinic

5. Day-to-day: Validating MSP eligibility

The single most common action. Done before rendering service to make sure MSP covers the patient.

5a. Open the patient profile

• Patients menu → search for the patient → click their name

5b. Confirm MSP-relevant fields are filled

The MSP check needs these patient fields to work:

5c. Click "Validate MSP"

Top of the patient form. Click it.

What happens behind the scenes:

1. Odoo calls Teleplan over the internet (takes 1-3 seconds) 2. MSP responds with eligibility: Eligible / Not Eligible 3. Patient form updates: - "MSP Validated" toggle flips to ✅ - "Last MSP Check" timestamp updates - Green/orange banner shows the response message 4. Audit log row written (see Section 11)     

5d. Reading the result

| 🟠 Not Eligible — ** | MSP rejected. Common reasons: PHN typo, patient not enrolled, coverage lapsed | Verify the PHN with the patient; check MSP coverage status | | 🔴 **Error:     | Network issue, MSP system down, or credentials wrong | Try again in a few minutes; if persistent, alert IT |

5e. The Returned Patient Data section in the audit log

When MSP returns the patient's name/DOB/gender, it's stored in the audit log row. If the returned name doesn't match the local record, that's a flag — possibly the PHN is wrong, or the local record was set up under a different name. Reception should verify with the patient.

6. Day-to-day: Authorizing MSP for appointments

Once the patient is MSP-validated, the appointment form will guide you through authorizing the specific services they're receiving.

6a. Open or create an appointment

• Calendar / Appointments → open or create a new event for the patient

6b. The MSP Authorization section auto-appears

If the patient has been MSP-validated, you'll see a new section on the appointment form titled MSP Authorization. It shows up automatically — no need to click anything to enable it.

6c. Add the services

Pick the service products on the appointment (e.g. "Eye Examination"). The MSP procedure codes for those services are pulled from inventory automatically — reception doesn't enter codes manually.

If extra modifier or CPT codes are needed beyond the standard procedure code, type them into the Additional CPT Codes free-form field (comma-separated, e.g. 99213, 25     ).

6d. Click "Authorize MSP"

What happens:

1. Odoo re-runs the eligibility check (in case anything changed) 2. The codes from the linked service products are confirmed 3. The "MSP Authorized" toggle on the appointment flips to ✅ 4. "Last MSP Authorize" timestamp updates 5. A success notification shows: "Authorized for codes [V404] + CPT [99213]" 6. Two audit rows written: one patient-level, one appointment-level   

6e. Filter the calendar to MSP appointments

Calendar / Appointments → use the MSP Patients filter to see only patients with MSP coverage, or MSP Authorized to see appointments where MSP has already been authorized.

7. Day-to-day: Submitting a claim

Claims are usually auto-generated when you create a sales order with MSP-billable services and confirm the invoice. The flow:

Customer comes in → service rendered → sales order created → invoice generated → MSP Claim auto-created (claim_type=Regular MSP by default)     

7a. Find your claim

MSP Claim → MSP Claim. New claims are in Draft status.

7b. Validate (optional pre-check)

• Click Validate — Odoo checks the claim has a PHN and a Practitioner Number
• If anything's missing, you'll see a friendly error

7c. Submit to MSP

Two ways:

1. Odoo builds the Teleplan V4.7 fixed-width record (~100 chars wide) 2. POSTs to MSP via the connector 3. MSP returns a C02 sequence number (auto-assigned) 4. Claim status moves: draft → sent 5. Claim's "Teleplan Sequence" field updates with the C02 number 6. A claim.manager stub is paired (for batch payment reconciliation later)   

7d. Other claim type options

For non-standard claims, change Claim Type before submitting:

The form fields adjust based on claim type — e.g. ICBC needs an ICBC Claim Number, Debit needs a reference to the original claim.

7e. Test the file before submission

If you want to inspect the Teleplan file Odoo would send, click Test Generate File. Downloads as a .txt      you can open in any editor. Useful for troubleshooting V4.7 formatting issues.

8. Day-to-day: Receiving remittances

MSP processes claims on their schedule (typically within a few business days). Remittance files are downloaded periodically.

8a. Pull the latest remittance

• MSP Claim → Configuration → ...connector retrieval action (manual button or scheduled cron)
• Or via Teleplan's web UI, download the .txt      file and import via Odoo's importer

8b. View remittance summaries

• MSP Claim → Remittance Summaries
• Each summary lists payments + refusals against the claims it covers

8c. Send to batch payment

• Open a remittance → click Send to Batch Payment
• The synthetic 835 translator turns the MSP remittance into X12-flavoured data that the existing Insurance batch-payment pipeline can read
• Claims marked paid, refusals show up for follow-up

8.e Day-to-day: Navigating between Patient, Claim, Sale Order, and Invoice

The MSP module is bi-directionally linked — you can pivot from any of these records to the related ones with a single click. No need to search across menus.

From an MSP Claim

The claim form has three smart buttons at the top:

8d.From a Sale Order

Sales orders that resulted in MSP claims show a count badge in the header:

• MSP Claims (with badge showing the count, e.g. "2 MSP Claims") — opens the linked claims
• Exactly one claim → opens the claim form directly
• Multiple claims → opens a filtered list scoped to this sale order

Useful when reception or sales is curious whether a particular order has been billed to MSP yet, and what the status is

8e. From an Invoice

Customer invoices have TWO MSP-related buttons in the header:

When you click Create MSP Claim, Odoo automatically fills:

• Patient — invoice's customer (must have PHN on file)
• Doctor — matched from invoice salesperson's MSP doctor record
• Service Date — invoice date
• Fee Item Code — first invoice line product's internal reference
• Billed Amount — first invoice line subtotal
• Clinic — company's default MSP clinic
• Back-links — to the invoice and source sale order, so both smart-button counts go up

If anything's missing (no PHN on the customer, no doctor linked to the salesperson, no product internal reference, etc.), the button shows a friendly error explaining exactly what to fix.

8f. The full navigation map

From any record in this set, you're one click away from any other:

        Patient (got2.patient)
                 ↑
                 │ "Patient Profile" smart button
                 │
   ┌──────── MSP Claim ─────────┐
   │             ↑               │
   │             │               │
"Sale Order"     │       "Invoice"
smart button     │       smart button
   │             │               │
   ↓             │               ↓
Sale Order       │           Invoice
   │             │               │
   │             │               │ "Create MSP Claim"
   │             │               │ action button
   └─→ "MSP Claims" smart button ←┘
       (with count badges on both)

This means staff don't have to memorize "which menu has the X for record Y" — they just click whichever smart button takes them where they need to go.

9. Demo mode buttons (test mode only)

When your company has MSP Test Mode ON, two extra buttons appear:

9a. Simulate Eligible Demo (patient form)

• Pretends MSP returned "Eligible" — no network call
• Lets you demo the success path when the testlab is unavailable
• Audit log row gets (SIMULATED)      suffix
• Disabled in production — even if a power user tries to invoke it on a customer instance, it raises an error

9b. Simulate Remittance (claim form)

• Creates a fake msp.remittance.summary      paying the claim in full plus two fake refusals
• Lets you demo the full claim → batch payment flow in one sitting
• Disabled in production

10. The Audit Log (MSP Transaction Logs)

Every Validate MSP / Authorize MSP click writes a row. This is the audit trail for compliance.

10a. Where to find it

MSP Claim → Configuration → MSP Transaction Logs

10b. What each column means

10c. Drilling into a row

Click into any row to see:

• Returned Patient Data — what MSP knows about this PHN (name, gender, DOB). Mismatch with local record = potential billing issue
• MSP Response — full message, codes, action
• Error Messages — if it failed

10d. Filters

Save common searches:

• Success — only successful calls
• Failure — only failures (useful for troubleshooting)
• Eligible — only Eligible results
• Group by Patient / Result / Date

11. Common scenarios and troubleshooting

11a. "I clicked Validate MSP and nothing happened"

• Check the PHN and Date of Birth are filled on the patient
• Open MSP Transaction Logs → look for the most recent row by your user → check the Error Messages field
• Most common: network glitch (retry) or wrong credentials in company settings

11b. "MSP returned 'FUTURE DATE' error"

• Module sends yesterday's date as service date by default — this shouldn't happen
• If it does, check the patient's DOB is in the past (not future)

11c. "Patient name on the MSP response doesn't match my local record"

• This is the demographic mismatch detection — feature, not bug
• Verify the PHN with the patient (could be a typo) OR
• The local patient record may have been set up with the wrong name
• Either fix the local name to match MSP, or correct the PHN

11d. "Authorize MSP fails saying 'No MSP fee codes'"

• The appointment's service products aren't linked to MSP procedure codes
• Go to Inventory → open the service product → set the MSP Procedure Code field
• Save, go back to appointment, click Authorize MSP again

11e. "Claim went to 'refused' status — now what?"

• Open the claim → check Response Message field
• MSP returns 2-character explanation codes (AP, Y4, Y9, etc.)
• Common: AP (info not provided), Y4 (non-covered charge), Y9 (patient not insured)
• Resubmit with the explanation addressed, or contact MSP

11f. "I want to test the workflow without affecting real claims"

• Make sure MSP Test Mode      is ON on the company
• Use the Simulate Eligible button to fake an Eligible response
• Submit a few test claims — they go to MSP's testlab, not production
• Use the Simulate Remittance button to fake a remittance for end-to-end demo

12. Whole model in one paragraph

> Reception validates a patient's MSP coverage by clicking one button on the patient profile. When the patient is booked, the appointment screen auto-shows an MSP Authorization section that pulls the right billing codes from inventory based on the services the patient is receiving. Reception confirms by clicking Authorize MSP. After the visit, sales orders auto-create MSP claims, billing staff submits them to MSP in batches, and remittances flow back into the existing batch payment workflow. Every click is logged in MSP Transaction Logs for compliance. In test mode, simulation buttons let you exercise the whole flow without real network calls — perfect for staff training.

13. Glossary

14. Quick reference card

For printing / pinning to reception desk:

``` ───────────────────────────────────────────────────── MSP WORKFLOW — Quick Reference ─────────────────────────────────────────────────────

BEFORE the visit: Patient form → Validate MSP button → 🟢 Eligible?

DURING booking: Appointment form → MSP Authorization section Pick services → Authorize MSP button → 🟢 Authorized?

AFTER the visit: Sales order → invoice → MSP Claim auto-created Submit → status: draft → sent

WHEN MSP responds: Remittance Summaries → Send to Batch Payment Claims marked paid or refused

TO CHECK who-did-what: MSP Claim → Configuration → MSP Transaction Logs

IF SOMETHING'S WRONG: Open the audit log row → check Error Messages Or contact IT

───────────────────────────────────────────────────── ```