Provider Management Advanced Setup

Other Settings

The Manage Other Settings page (accessed from the Administration page) allows for the configuration of other setting including:

Set person attributes to display on provider dashboard: configures the person attributes to display in the demographics section of the provider dashboard; unlike provider attributes, these currently can be configured only on an all-or-nothing basis, and cannot be customized depending on provider role
Set the person attribute type to include on the advanced search page: configures the person attribute type you'd like to be able to use as a search parameter on the advanced search page; currently you are limited to only one attribute
Select whether or not to restrict search results to providers with a defined provide role: set this if you want the search results to only display providers who have a provider role (ie, provider.provider_role != null); this is useful if there is only a subset of providers you want to manage using the module
Select the address widget to use: allows the use of Rwanda Address Hierarchy address widget instead of the standard address widget when editing provider demographic information; requires that the Rwanda Address Hierarchy module is installed; hopefully future additions to the module will allow the use of the standard Address Hierarchy module address widget as well

Customizing display fields

The Manage Other Settings page also contains a series of settings that allow for the customization of the fields that are displayed in provider, patient, and person lists and search results. The fields are specified in pipe-delimited list of label/field name pairs where field names are referenced by standard dot notation. For instance:


Identifier:provider.identifier|Given Name:provider.person.personName.givenName|Family Name:provider.person.personName.familyName|Role:provider.providerRole|Gender:provider.person.gender|Start Date:relationship.startDate

The standard Provider object is accessible via dot notation when displaying provider lists and search results, and the Patient and Person objects are accessible when display patient and person list/search results. Besides these objects, access to a few other fields are available in the display context:

In provider and patient lists, you also have access to the associated relationship via the token "relationship" (see the above example, which shows how to display the start date of the associated relationship)
In patient lists, you also have access to the patient programs for that patient via the token "patientPrograms"; a custom util method which provides a comma-separated list of program names is also available via the token "patientProgramNames"

Privileges and Roles

The provider module provides a set of new privileges hat can be used to customize the experience for various users/roles. The privileges are broken down into high level API privileges, as well as privileges that control what access at the web layer:

API

Provider Management API - Read-only: any user of the module should have this privilege
Provider Management API: any user that will use this module to edit/update information should have this privilege

Web

Provider Management Dashboard - View Providers: basic privilege that a user needs to be able to view the provider dashboard
Provider Management Dashboard - Edit Providers: privilege to allow a user to edit providers via the provider dashboard; the edit button on the provider pane will not be available to users who don't have this privilege
Provider Management Dashboard - View Patients: privilege to allow user to view the list of patients associated with a provider; users without this privilege will only see a count of the number of patients associated with provider
Provider Management Dashboard - Edit Patients: privilege to allow users to edit the list of patients associated with a provider; users without this privilege will not be able to add and remove patients from providers
Provider Management Dashboard - View Historical: privilege to allow users to view historical patient and supervisee information from a provider; the Historical Patients and Historical Supervisees lists will be hidden from users that don't have this privilege

(TODO: document the OpenMRS general privileges that a user must have in order to use the module properly)

Suggestions

When assigning supervisees to supervisors, certain supervisees can be suggested as potential supervisees for the provider. These suggestion are set up by creating suggestion rules. By default, no rules are configured, but, after a rule has been configured, a Suggest button will be added to the action buttons that appear in the Supervisee pane of the Provider Dashboard. Clicking the suggest button will list the providers that match the suggestion rule.

Suggestions can be configured by going to the Manage Suggestions page, accessible from the Administration page. A suggestion has the following fields:

Name: the name of a suggestion; simply used for reference
Provider Role: the provider role that this suggestion applies to
Suggestion Type: the type of suggestion; currently only supervisee suggestions are supported
Evaluator: the evaluator to use to evaluate this suggestion; currently only Groovy suggestions are supported
Criteria: the criteria (written in Groovy) to use to determine which providers should be suggested

The criteria should be a Groovy script that returns a set of persons (the set of suggested supervisees). In the Groovy context, the Person object (not the Provider object) associated with the supervisor we are evaluating the suggestion for is bound to the variable "provider". The core Openmrs services are accessible via variables in the format "providerService", and the provider management service API is available via the variable "providerManagementService".

For instance, here is an example of a suggestion that suggests all providers with the same cityVillage as the supervisee. Note that the result will still be filtered to exclude any providers who do not have a role that the selected provider is able to supervise.


// the supervisor is bound to the provider variable
def supervisor = provider    

// get all providers in the system, excluding retired providers
List providers = providerService.getAllProviders(false)

// initialize the set we are going to pass back as a result
// (note that it is a list of persons, not providers)
Set results = new HashSet<org.openmrs.Person>()

// iterate through the list of providers we have fetched
for (org.openmrs.Provider p : providers) {

	// if the provider has the same city/village as the supervisor, add the *person* associated with this provider to the results list
	if (p.getPerson() && p.getPerson().getPersonAddress()?.getCityVillage().equals(supervisor.getPersonAddress()?.getCityVillage())) {
    		results.add(p.getPerson())
	}


}

// return the results
return results