Inpatient Covering Letters - hmislk/hmis GitHub Wiki

Inpatient Covering Letters

Overview

The Inpatient Covering Letters feature lets hospital staff generate, edit, save, print, and download covering letters for admitted patients. Letters are created from pre-defined templates where patient details, admission information, and credit company data are automatically filled in. An AI-assisted generation option is also available.

Covering letters are commonly used for:

  • Insurance pre-authorisation requests
  • Guarantee of Payment (GOP) letters to credit companies
  • Referral cover letters
  • Medical reports for employers or insurers
  • Any formal correspondence linked to an admission

One letter for several admissions or bills? For a dialysis covering letter listing several BHTs, or an OPD invoice listing several patients' bills, use Covering Letters for Multiple Admissions and Bills instead.

Page: Admission Profile → Clinical Data → Letters XHTML: /inward/inward_letters.xhtml Controller: InpatientClinicalDataController / DocumentTemplateController Privilege: InpatientLetter

How to Use

Accessing the Letters Page

  1. Open the Inpatient Dashboard for the patient (search for the admission and click the patient's record)
  2. In the Clinical Data panel (third column), click Letters
  3. The Letters page opens, showing the patient's details at the top, the letter generation panel on the left, and the letter viewer/editor on the right

Generating a Letter from a Template

  1. On the left panel under Generate New Letter:
    • If the patient has one or more credit companies linked to their admission, a Credit Company dropdown appears first — select the relevant credit company (this determines which company details are substituted into the template)
  2. In the Select Template dropdown, choose the document template that matches the letter you need (e.g. "Insurance Pre-authorisation Letter", "GOP Request Letter", "Medical Report")
    • Click the 🔄 Refresh button if new templates have been added and are not yet visible in the list
  3. Click Generate from Template
  4. The system substitutes all placeholders in the template with the patient's actual data and the letter appears in the right-hand viewer
  5. The generated letter is automatically saved and appears in the Saved Letters list on the left

Note: If the Select Template dropdown is empty, no document templates of type "Letter" have been configured. Contact your system administrator to create letter templates under EMR → Settings → Document Templates.

Generating a Letter with AI

  1. Optionally select a template from the Select Template dropdown — when a template is selected, the AI uses it as a guide for structure and style
  2. Optionally select a Credit Company if available
  3. Click Generate with AI
  4. The AI analyses the patient's admission data (diagnosis, procedures, medications, allergies, clinical notes) and generates a draft letter
  5. The letter appears in the viewer and is added to the Saved Letters list
  6. Review and edit the AI-generated content before printing or downloading

Note: AI generation may take a moment. A loading indicator is shown while the AI is working.

Editing a Letter

  1. Select the letter from the Saved Letters list — it appears in the right-hand viewer
  2. Click Edit (pencil icon) — the viewer switches to an HTML editor
  3. Make your changes in the editor
  4. Click Save (floppy disk icon) to save your changes
  5. Click View (eye icon) to switch back to read-only mode

Deleting a Letter

  1. Select the letter from the Saved Letters list
  2. Click Delete (trash icon)
  3. Click Yes in the confirmation dialog
  4. The letter is permanently removed

Printing a Letter

  1. Select the letter from the Saved Letters list
  2. Click Print (printer icon)
  3. The browser's print dialog opens — choose your printer and settings
  4. The letter is printed with the hospital's letterhead styling

Downloading a Letter as PDF

  1. Select the letter from the Saved Letters list
  2. Click Download PDF (PDF icon)
  3. The letter is downloaded to your computer as a PDF file

Navigating Back

  • Back to Inpatient Dashboard — returns to the patient's admission profile
  • Clinical Data — opens the clinical data overview page for this admission

Template Placeholders

Document templates use placeholders written in curly braces. When a letter is generated, each placeholder is replaced with the admission's data. The full list is also shown at the bottom of the template editor (Inward Administration → Document Templates → Add Letter Template).

Placeholder list in the letter template editor

The placeholder list shown under the template editor, including the credit company contact, commitment amount and final bill number.

Placeholder Replaced With
{letter_date} Today's date
{name} / {patient_name} Patient's name with title
{age}, {sex} Patient's age and gender
{bht} The admission's BHT number
{doa}, {dod} Date of admission, date of discharge
{doctor} Admitting doctor
{institution}, {department} Hospital name, ward / department
{credit_company} Name of the selected credit company
{credit_company_address} Address of the credit company
{credit_company_contact} Contact person's name, as entered on the credit company's Contact Person Details tab
{policy_no} Policy number entered on the admission
{reference_no} Insurer reference number entered on the admission
{credit_limit} Credit limit entered for the credit company on the admission
{company_amount} The amount the selected credit company has committed to pay. After the final bill is processed this is the amount allocated to that company; before that it is the credit limit. Blank if neither exists
{final_bill} Total of the final bill (blank/zero until the final bill is processed)
{final_bill_no} Number of the current final bill, as printed on the final bill

Amounts are shown with thousand separators and two decimals (for example 99,000.00). The credit company placeholders follow the credit company selected on the Letters page.

Templates are created and managed by system administrators. See Admin — Inpatient Form Templates for template configuration.

Example: Settlement of Medical Bill (single admission)

To ask an insurer to settle one admission, create a letter template with text like the one below. Contact designation, hospital name, bank account details and the cheque wording are typed into the template as fixed text.

Date: {letter_date}

{credit_company},
{credit_company_contact},
Senior Manager - Health Operation,
{credit_company_address}

Dear Sir/Madam,

SETTLEMENT OF MEDICAL BILL
Settlement of Hospital Charges Against Bill No {final_bill_no}
{name}

I wish to inform you that the above person has received treatment at this Hospital.
Enclosed please find our bill for Rs. {company_amount} being his/her Hospital charges & Professional charges.
You are kindly requested to remit this amount. Cheques to be written in favour of
<hospital legal name> with the least possible, in the event of cheque payment.

<bank account details>

* Please note that prevailing bank overdraft interest rate will be applied for all overdue debts.*

Thanking You,
Yours' faithfully,
Accountant
{institution}

If your hospital quotes the full bill rather than the insurer's commitment, use {final_bill} instead of {company_amount} in the "Enclosed please find our bill for Rs." line.

Before generating: enter the contact person on the credit company (Administration → Manage Institutions → Credit Companies → Contact Person Details), and make sure the final bill has been processed so the bill number and amounts are available.

Multi-Credit-Company Support

If a patient's admission is linked to multiple credit companies (e.g., primary insurance and a secondary top-up insurer), the Credit Company dropdown appears at the top of the Generate New Letter panel:

  1. Select the credit company you are writing to from the dropdown
  2. Generate the letter — the selected company's name, address, and policy number are substituted into the template
  3. To generate a letter for a different credit company, simply select a different company from the dropdown and generate again
  4. Each generated letter is saved separately in the Saved Letters list

Note: If the patient has no credit companies linked, the Credit Company dropdown is hidden and credit-company placeholders in the template are left blank or replaced with a dash.

Understanding the Saved Letters List

The Saved Letters list on the left shows all letters previously generated for this admission. Click any letter to view it in the right-hand panel. Letters are identified by the name given at the time of generation (the template name or a custom title).

Best Practices

  • Always review AI-generated letters before printing or sending — the AI drafts content based on available clinical data and may need adjustment
  • Select the correct credit company before generating a letter — if you generate with the wrong company, delete the letter and generate again with the correct company
  • Edit and save before printing to make sure the letter is final
  • Use descriptive template names to make it easy for staff to find the right letter type
  • After a letter is printed and sent, it remains in the Saved Letters list for future reference

Permissions

Access to the Letters page requires the InpatientLetter privilege. If the Letters button is not visible in the Clinical Data panel of the Admission Profile, contact your system administrator to have this privilege assigned to your role.

Troubleshooting

The Letters button is not visible on the dashboard

Cause: Your user role does not have the InpatientLetter privilege. Solution: Ask your system administrator to assign this privilege to your role.

No templates appear in the Select Template dropdown

Cause: No document templates of type "Letter" have been created, or the templates are retired. Solution: An administrator must create letter templates under EMR → Settings → Document Templates.

Generate from Template produces a letter with blank fields

Cause: The patient record may be missing the data that the placeholder expects (e.g., no consultant assigned, no diagnosis recorded). Solution: Fill in the missing data on the admission or patient record, then generate the letter again. You can also manually edit the letter after generation.

Credit Company dropdown does not show the expected company

Cause: The credit company has not been linked to this admission. Solution: Edit the admission's payment details to add the credit company, then return to the Letters page.

AI generation takes too long or fails

Cause: The AI service may be temporarily unavailable or the patient has a very large clinical record. Solution: Wait a moment and try again. If the problem persists, use Generate from Template instead.

Related Features