Understanding the functionality of Patient List and Queues


Could you please help correct my understanding or help me understand the feature patient list and queues.

I registered two patients and started OPD visit for visit type PHY_OPD V.

I have created location PHY_OPD too.

I logged in as doctor and for location PHY_OPD

The queue displays as follows:

Active (2) : I understand that all patients who’s visited started are show here, irrespective of location.

Programs (2) : I have not created any program for the patients, how come it is showing 2?

My Patients (2) : this should be the providers or doctors active patients (who’s visit started). But in registration module or after I started the visit I have not marked the location or the provider. what does this mean?

OPD-1(2) : What does this mean, I have several other visit types or location, why are they not showing up, why only this.

PatientsByLocation : As there is no mapping of location to providers or visit type, what is the understanding behind this.

Providers, location are mapped only in appointment scheduling not during start of the visit. I tried to interpret from the feature guide, but I couldn’t get the clarity.

I am trying to set the flow for one of the implementation, I see this is a good feature. But I am not clear.

Request for help.

1 Like

If you look in the OpenMRS administration – advanced settings, you will see some sql queries which populate each of the tabs, that will hopefully help, as well as where these tabs are defined in clinical/extension.json


Search for extension point ids “org.bahmni.patient.search” in the extension.json. Each of them appear as tabs in the clinical module. Notice the “searchHandler” parameter? Search for that name in OpenMRS => Admin Console => Advanced Settings. The “searchHandler” name will be the a SQL thats run when you shift to tabs in clinical.

Chances are that those SQL queries are exact reflection of the queues defined in the demo setup with demo database. You can always change the SQLs based on what you need.

Thank you Liam and Angshuman for your quick replies. Let me give background about me. I am a week old into Bahmni. I am working with a customer and evaluating Bahmni suitability for them. I have about 4 weeks on this project to map business requirement and do the gap fit analysis. Already a week and half gone by. I understood the flow of Bahmni and open erp, open elis. My experience is largely on functional side, project mgt and little technical. I worked with various open source products and erp products in implementations. That is one of the reason to take up Bahmni suitability and implementation for this customer. I have gone through all the available documentation on the internet in terms of patient list and queues, I understand the SQL queries are set in the advance settings in openmrs. I tried to interpret SQL queries, I had a challenge in understanding. I made few entries, I found inconsistent results for various locations. So I tried to read feature guide to understand its expected behavior. It did not throw up much light, hence reached out to community for understanding. If someone can help me understand the expected behavior of each tab then I can quickly go through by making the entries and see the results. Why I am asking this question is, nowhere in the setup through UI we are mapping, visit types to locations or to providers or patients to providers. Then how queries could retrieve such an information like mypatients and patientbylocation and so on… programs, i have not created any programs, how is system showing a numeric in programs tab.Hence what to understand the functionality of patientlist and queues and the expected behavior.

1 Like

Here is the expected Behaviour and the explanation:

  • PatientsByLocation: There is no mapping between the visit type & location. This queue takes the login location where the patient visit was opened. So the queue shows only those patients who have a active visit opened in that logged in location. (active visit meaning an Open Visit)

  • My Patients: Here also there is no mapping between patient & provider. The queues here should show the patients who have had atleast one encounter with the logged in provider.

  • Active: All patients with an open visit

If you want to test the Mypatients & PatientsBy location queues, try logging in as a different user or change the login location.

  • Other two queues like Programs and OPD-1 are just examples. If you check extension.json in the default config, you will see that these queues are using the same queries as Patientsbylocation & Mypatients. Thats why they are showing up the same patients. Ideally Programs queue should show Patients enrolled in a program, with an open visit and OPD-1 should show patients with open visit in that location. (We will fix them in the default. Apologies for that). BTW you can remove these two from extension.json to avoid confusion.

Also, like others have pointed out in the thread above, these queues are highly configurable, you can choose to write sql queries to meet your use case. Please post any specific use cases that you have in mind. We will try and help you.

Let us know if you need any more clarifications.


Thank you Sruti for the detailed response. I think, I got the understanding now.

In mypatients or patientbylocation queue, the provider/doctor or the registration desk should login through each location of the visit for each patient and start the visit. That means the doctor has to pull in through start visit into their location. Only then the number would reflect appropriately.

Mine is a very generic usecase, where registration desk takes the responsibility of appointments, registering patients and starting the OPD.

Registration desk logsin with their locations registration desk and registers patients and starts OPD based on visit types.

Doctor ( who is provider) does only consulting.

Then in this case in the product, the doctor will see all the active patients visit irrespective whether they pertain to his OPD or not…

How can we address this without having to change the location by registration desk each time?

I think some of the confusions are result of copy and paste of configuration wherein for some queues, someone just copied the same configuraiton and SQLs. Maybe I can add some clarity (Do read more about list/queue here)

  • Every such queue executes a query which can be defined in the extension definition as extensionParams.searchHandler (as you have already found out)

  • Bahmni while making an API call, passes the parameters - which include the searchHandler name (which corresponds to a query defined as part of Global Property) and other like “provider_uuid”, “location_uuid” etc. “provider_uuid” is the uuid of the provider who has logged in, and “location_uuid” is the location where the provider has logged in. The API also finds out whats the visit location as well. (see location hierarchy, how you can define a visit location, login location etc here).

  • So you have now 3 things which you can use as parameters in your query. “provider_uuid”, “location_uuid”, “visit_location_uuid”. These can be used in the SQL statement like “${parameter_name}”.

So, lets assume if you want to achieve

  1. Patients who have been assigned to a doctor (patients who have been told to go and see a particular doctor)
  2. Patients who may have been sent to a department (or a room)

Example implementation of Case 1)

  • Define a concept “consultant” and set class as “misc” and datatype as “complex” and handler as “providerobshandler”. Lets assume that the defined concept_id is “101”.
  • Define a form (using form builder) and use this concept in the form and publish the form. assuming form name is “Consultant to see”
  • Define an extension in “bahmni_config/openmrs/apps/registration/extension.json” and add one like below
        "id": "bahmni.registration.conceptSetGroup.consultantToSee",
        "extensionPointId": "org.bahmni.registration.conceptSetGroup.observations",
        "type": "forms",
        "extensionParams": {
            "formName": "Consultant to see",
            "showLatest": true
        "order": 2,
        "requiredPrivilege": "Edit Visits"

INFO: Now, when you register a patient, in the second page, you will have to choose a consultant (a provider). Lets say you select a provider “Dr. Yogesh”, who’s ID (provider.provider_id) will be captured in the observation table against the concept “consultant”.

  • Create a new extension for search in clinical (bahmni_config/openmrs/apps/clinical/extension.json) with something like below
"myPatientsToSee": {
    "id": "bahmni.clinical.patients.search.myPatientsToSee",
    "extensionPointId": "org.bahmni.patient.search",
    "type": "config",
    "extensionParams": {
      "searchHandler": "emrapi.sqlSearch.myReferredPatients",
      "translationKey": "MODULE_LABEL_ALL_KEY_97",
      "forwardUrl": "#/default/patient/{{patientUuid}}/consultationContext"
    "label": "My patients",
    "order": 7,
    "requiredPrivilege": "app:clinical"
  • Define a global property by the name “emrapi.sqlSearch.myReferredPatients” with value as

      select distinct 
      concat(pn.given_name," ", ifnull(pn.family_name,'')) as name,
      pi.identifier as identifier,
      concat("",p.uuid) as uuid,
      concat("",v.uuid) as activeVisitUuid,
      IF(va.value_reference = "Admitted", "true", "false") as hasBeenAdmitted
      obs o 
      join encounter e on o.encounter_id = e.encounter_id 
      join visit v on v.visit_id = e.visit_id and v.voided = 0
      join person p on e.patient_id = p.person_id
      join person_name pn on p.person_id = pn.person_id
      join patient_identifier pi on v.patient_id = pi.patient_id and pi.voided=0
      join patient_identifier_type pit on pi.identifier_type = pit.patient_identifier_type_id
      join global_property gp on gp.property="bahmni.primaryIdentifierType" and gp.property_value=pit.uuid
          left outer join visit_attribute va on va.visit_id = v.visit_id and va.voided = 0 and va.attribute_type_id = (
      				select visit_attribute_type_id from visit_attribute_type where name="Admission Status"
      where o.concept_id = 3630 
      and (CAST(o.value_complex as UNSIGNED)=(select p1.provider_id from provider p1 where p1.uuid = ${provider_uuid}))

(NOTE: Don’t go the above SQL, it will surely require more work.)

So what we have done is define a list/queue which essentially lists the logged in provider’s patients irrespective of whether the provider saw the patient ever or not. If login as Dr. Yogesh, you will only see patients who the registration clerk has referred to. Note: you can do the same with patient relationship and write a similar SQL


Thanks @angshuonline for the elaborate reply :slight_smile:

@jayasri , Just as he has explained in Case 1 above, for Case 2 instead of the provider you will have to capture the location as a concept with the handler as "LocationObsHandler (room or department - E.g OPD-1, Dental Department, Diabetic OPD etc). You can read about location & location hierarchy here. Then in a similar way, as in Case 1, you can define a sql query to show up patients sent to a particular room/department in a queue.

Thank you Angshuman for such a thorough and detailed response. I appreciate your support. Put me to thinking. Sorry couldn’t respond sooner due to festival around and we were engrossed into mapping the workflow with the product. Thanks Sruti for your response too.


Let me see if I understood right: you were mentioning about 2 ways to implement it right? Case 1: Create a separate page in registration and add a concept and field for consultant to see and capture that as part of the query for mypatients and this could be entered by Registration desk. Case 2: is to use Patient Relationships -> Select Doctor and run the sql query using this datapoint.

could you please confirm.

Also you mentioned in case 1, second page means as a tab when we enter into “enter visit details form”?

Another point - I am using location tags. I understood about Login location - this will display all the location marked as login at the login screen as against locations Appointment location - this will display all location marked as appoint in appointment module however for visit location - what does that mean, I haven’t see where this is being used. except I faced privileges error when I haven’t marked registration desk location to visit location.


I guess case2 Angshuman was mentioning about patientrelationships not locations. I did not get your statement about case2.

Every setup must have a “visit location” defined. Please read here

Under a visit location (say a hospital), you can have “n” of login locations.

Thanks Angushuman, let me give a reading and will get back.

Thanks Angushuman.

I tried the same as suggested, but no luck, Might be I’m missing something else in this configuration. Please find the details below:

Tried to add “Assign consultant to patient” dropdown in second page (after clicking on “Enter Visit details”) using Concept dictionary and Form builder with below steps:

Define a concept “consultant” and set class as “misc” and datatype as “complex” and handler as “providerobshandler”. Lets assume that the defined concept_id is “101”.

Define a form (using form builder) and use this concept in the form and publish the form. assuming form name is “Consultant to see”.

Define an extension in “bahmni_config/openmrs/apps/registration/extension.json” and add one like below “sendTo”:{ “id”: “bahmni.registration.conceptSetGroup.consultantToSee”, “extensionPointId”: “org.bahmni.registration.conceptSetGroup.observations”, “type”: “forms”, “extensionParams”: { “formName”: “Consultant to see”, “required”:true, “showLatest”: true }, “order”: 2, “requiredPrivilege”: “Edit Visits” }

After doing this, I went to patient registration -> second page, but noticed below error.

“[Required List parameter ‘concept’ is not present]”

I’m not sure, what am I missing here. Could you please help me out of this issue.

Angshuman, any thoughts we tried to implement your suggestion as above on consultant to see, there seems to be some issue.