Practitioner Link to Institution for Channelling - hmislk/hmis GitHub Wiki
Practitioner — Link to Institution for Channelling
A consultant is only bookable through the channelling module at institutions where they have been linked. If a consultant is registered but not linked to any institution, they will not appear in the booking dropdown at any branch. This article explains the linking screen.
Navigation
Top menu → Administration → Manage Staff → (Setup tab) → Add Channelling Consultants to Institutions.
Path: /admin/staff/person_institution.xhtml.
Privilege required: AdminStaff.
What the screen does
The screen has two stacked panels:
- Manage Doctors — pick an institution, then add consultants to it in bulk.
- Person Institutions Search — review and remove existing links.
The link itself is a separate PersonInstitution row connecting one consultant to one institution. A consultant who sees patients at three branches has three such rows.
Adding consultants to an institution
- Pick the target institution. Use the Instituion [sic — the field is spelled this way in the UI] autocomplete to choose the branch.
- Optional: filter by speciality. Use the Doctor Speciality autocomplete next to it. Only consultants matching that speciality will be loaded into the candidate list.
- Click Fill Doctors. The system loads consultants who are not yet linked to the selected institution into the table below (showing No, Doctor Name, Speciality).
- Select rows to add by ticking the checkbox at the left of each row. The header checkbox selects all rows currently shown.
- Click Add Doctors. Each selected consultant becomes linked to the selected institution.
The newly linked consultants disappear from the candidate list (because they are now linked, so the "without institution" filter no longer matches them).
The candidate list is restricted to consultants and doctors whose speciality matches the chosen filter (if any) and who are not yet linked to the chosen institution.
Reviewing and removing links
- In the Person Institutions Search panel, use the Instituion, Speciality, and Staff autocompletes to filter the existing links.
- Click Fill Person Institutions to load the matches.
- The results table shows: No, Doctor Name, Speciality, (Institution Name only when no institution filter is set), Code, Phone, Mobile, and a Remove action.
- Click Remove on any row to delete the link. The consultant is no longer associated with that institution.
- Click Excel to export the results to
Channel_Doctor_List.xlsx.
Removing a link does not delete the consultant record itself — it only severs the consultant-to-institution association.
Practical scenarios
| Scenario | What to do |
|---|---|
| A new consultant has just been registered and should be bookable everywhere. | For each institution, run the steps in "Adding consultants to an institution" with that consultant selected. |
| A consultant has stopped visiting one branch but continues at others. | In the Search panel, filter by the consultant; remove the row for the branch they have left. |
| All Cardiologists should be available at a new branch. | Pick the new institution and the Cardiology speciality filter, then Fill Doctors → select all → Add Doctors. |
| The candidate list is empty but you expect names there. | The consultants are already linked, or the speciality filter is hiding them. Try clearing the speciality filter and Fill Doctors again. |
Limitations
- The screen does not show retired consultants, even if they were linked before retirement. To clean up old links to retired consultants, ask an administrator to query the database directly.
- The "Code" column in the search panel shows the consultant's internal code, not their consultant serial number.
- The institution field is spelt "Instituion" in the UI (typo preserved for backward compatibility); the filter still works as expected.