Admin Inpatient BHT Number Management - hmislk/hmis GitHub Wiki

Admin — Inpatient BHT Number Management

BHT (Bed Head Ticket) and OPD Card numbers are generated from a per-admission-type sequence counter. Occasionally staff need to correct that counter — for example, after cancelling an admission so its number can be reused, after manually typing a custom number to keep a paper card register gap-free, or to recover from a historical mismatch. This page covers the three ways to view or reset the counter: the admin UI, the AI Assistant, and the REST API.

Page: Admin → Manage Inpatient Services → Admission Types → BHT Number Management
XHTML: /inward/inward_admission_number_management.xhtml
Controller: AdmissionNumberController
Privilege: InwardAdministration


Background

Each admission type (e.g. "BHT", "OPD Card") has its own counter — or a single shared counter, if "Count as a separate Number" is off; see Admin — Inpatient Admission Types. If config key BHT Number can be edited at the time of admission is enabled, staff can type their own number over the suggestion when admitting a patient (see Inpatient — Admit a Patient). When that happens, today's system does not consume a counter value for the discarded suggestion — but if the visible sequence still doesn't match what's physically printed (e.g. after historical data issues, or a bulk correction), the counter itself can be realigned here.

Every counter also always shows the same thing two ways:

  • Last Used BHT — the last number actually handed out
  • Next BHT to Issue — what the next admission of that type will receive (Last Used + 1)

Option 1: Reset via the UI

  1. Go to Administration → Manage Inpatient Services.
  2. Under the Admission Types tab, click BHT Number Management.
  3. The table lists every counter — one row per institution + admission type combination (or "All Institutions" if numbering isn't split per institution).
  4. Find the row you need and click Edit.
  5. Enter the corrected Last Used BHT Number — the next admission of that type will receive this value + 1.
  6. Click Save.

BHT counter saved

After saving, the table shows the new Last Used and Next BHT to Issue values.

This is the simplest option and needs no technical knowledge — just the InwardAdministration privilege. Every save is recorded in the audit log (who, when, old value, new value).

If someone admits a patient of that type while you have the edit form open, the counter has moved since you clicked Edit. Your save is then refused instead of overwriting a number that has just been issued:

Save refused because a number was issued meanwhile

A BHT number was issued while the form was open, so the change was not saved. Check the current value and edit again.

After cancelling an admission

To reuse the number of a cancelled admission, set Last Used BHT Number to one less than that number, but only if no later number has been issued yet. If a later number has been issued, lowering the counter would give the next patient a number that is already in use.

The hospital can also have this done automatically on cancellation; see Inpatient — Cancel Admission.


Option 2: Ask the AI Assistant

If AI Chat is enabled for your account, you can simply describe the correction in plain language, e.g.:

"The OPD Card counter for Galle is showing 43472 but the physical card register is at 43475. Can you check and fix it?"

The assistant will look up the current counter (read-only), show you the current and requested values, and ask you to confirm before making any change — it's required to do this and will not reset the counter silently. This is a good middle ground: no need to know internal IDs, but you still get the same audit trail and protection as the API (below), since the assistant calls the same endpoint.


Option 3: Reset via the REST API

For integrations or when a developer/support engineer is making the correction directly, use the /api/admission-numbers endpoint. Unlike the UI option, every reset here is audit-logged (who, when, old value, new value) and protected by a compare-and-set check — if someone else's admission changes the counter between your GET and your PUT, the reset is rejected instead of silently overwriting a number that's already been issued.

Authentication

All requests need an API key in the Finance header:

Finance: <your-api-key>

Keys are issued under Settings → Manage My API Keys — see Manage My API Keys.

1. View the current counter

GET /api/admission-numbers?admissionTypeId=1192&institutionId=
Param Required Description
admissionTypeId Yes Numeric ID of the admission type (e.g. "OPD Card"). Ask a developer to look this up if you don't have it handy
institutionId No Only needed if numbering is split per institution
{
  "status": "success",
  "code": 200,
  "data": {
    "admissionTypeId": 1192,
    "admissionTypeName": "OPD Card",
    "institutionBased": false,
    "lastAdmissionNumber": 43472,
    "nextAdmissionNumber": 43473
  }
}

2. Reset the counter

PUT /api/admission-numbers?admissionTypeId=1192&institutionId=
Content-Type: application/json
{
  "lastAdmissionNumber": 43475,
  "expectedLastAdmissionNumber": 43472
}
Field Required Description
lastAdmissionNumber Yes The corrected last-used number (not the next number)
expectedLastAdmissionNumber Yes The lastAdmissionNumber you just saw from GET — this is the compare-and-set check. If the real counter has since moved on (e.g. someone else admitted a patient), the request is rejected with 409 instead of quietly reissuing a number that's already been used
{
  "status": "success",
  "code": 200,
  "data": {
    "admissionTypeId": 1192,
    "admissionTypeName": "OPD Card",
    "institutionBased": false,
    "previousLastAdmissionNumber": 43472,
    "lastAdmissionNumber": 43475,
    "nextAdmissionNumber": 43476
  }
}

Errors

Code Meaning
400 Missing/invalid admissionTypeId, missing/invalid JSON body, or missing/non-numeric/negative lastAdmissionNumber / expectedLastAdmissionNumber
401 Missing or invalid Finance API key
404 admissionTypeId or institutionId doesn't match an existing record
409 The counter changed since your last GET — fetch it again and retry with the current value

Full technical reference (for developers): developer_docs/api/API_ADMISSION_NUMBERS.md in the codebase.


Related Articles