The primary usage of this application is for other RapidSMS applications to have a common way to store and retrive patient/provider data even though each project which deploy the application may use different methods of actually storing the data.
Applications built with rapidsms-healtcare should use the functionality provided by healthcare.api. The client object in the module is primary entry point for accessing the healthcare data. It provides basic CRUD (Create/Update/Delete) operations for the patient and provider data:
from healthcare.api import client
patient = client.patients.create(name='Joe', sex='M')
Where this data is stored configured by the HEALTHCARE_STORAGE_BACKEND setting. Below are all of the available backends included in the rapidsms-healthcare distribution.
Path: 'healthcare.backends.djhealth.DjangoStorage'
This is the default storage backend. It stores the patient and provider information using the Django ORM. To use this backend you must include 'healthcare.backends.djhealth' in your INSTALLED_APPS setting to create the necessary tables.
Warning
Though the default storage backend uses the Django ORM, developers should resist all temptation to access the models directly (including creating FKs in additional models) as that will break the portability of the application.
Path: 'healthcare.backends.dummy.DummyStorage'
This backend stores the data in local memory. This backend is indended only for testing and should never be used in a production setting.
Operations on patient data are done through client.patients. Currently the backend supports create, get, update, filter, delete, link, and unlink:
from healthcare.api import client
# Create new patient
patient = client.patients.create(name='Joe', sex='M')
# Update the patient's name
client.patients.update(patient['id'], name='Jack')
# Refetch the patient record
patient = client.patients.get(patient['id'])
# Get patients with name containing 'Ja'
patients = client.patients.filter(name__like='Ja')
# Delete a patient record
client.patients.delete(patient['id'])
Patients currently store the following pieces of data [1]:
| Name | Type | Description |
|---|---|---|
| id | String | Globally unique identifier |
| name | String | A readable name/identifier |
| sex | String (M/F) | Patient’s sex |
| birth_date | Date | Date the patient was born |
| death_date | Date | Date the patient died |
| location | String | Identifier for the patient’s location |
| created_date | Datetime | Time when the record was created |
| updated_date | Datetime | Time when the record was last updated |
| status | String (A/I) | Flag to denote if the record is currently active |
| [1] | Required fields are bold and generated values are in italics. |
The location field might store the name of the location or an identifier for another location/facility registry.
patients.create adds a new patient record to the data store. The arguments for this function are passed to the backend to store on the record. The patient data is returned as a dictionary and contains additional fields which are generated by the backend: id, created_date and updated_date.
patients.update takes the id of the patient along with arguments to be passed to the backend to update. This returns a boolean to note whether a matching patient was found and updated.
patients.get returns a patient’s data as dictionary for the given id. If no matching patient was found this will raise a PatientNotFound exception.
Patients can also be associated with external ids using the link method. You can retrieve these users using get by passing the source name of the identifier.:
from healthcare.api import client
# Create new patient
patient = client.patients.create(name='Joe', sex='M')
# Associate patient with an external ID
client.patients.link(patient['id'], '123456789', 'NationalID')
# Refetch the patient record using national id
patient = client.patients.get('123456789', source='NationalID')
patients.filter returns a list of matched patient data dictionaries. If there are no matches then it will be an empty list. Additional details on filtering expressions is given below.
patients.delete takes the id of the patient and returns a boolean to note whether a matching patient was found and deleted.
The patient.id is generated by the backend and cannot be controlled by the application. patients.link and patients.unlink are used to manage associations between patients and additional identifiers used by the application. These might be identifiers created internally by application, assigned by health care facilities or national identifiers. To create a new association you need patient id, the additional id, and a name for the source of the id. The additional identifiers should be unique for their source.:
from healthcare.api import client
# Create new patient
patient = client.patients.create(name='Joe', sex='M')
# Associate patient with an external ID
client.patients.link(patient['id'], '123456789', 'NationalID')
patients.unlink is used to remove this association.:
# Continued from the above example...
# Remove patient's external ID
client.patients.unlink(patient['id'], '123456789', 'NationalID')
The patients.link and patients.unlink both return booleans to denote whether the association creation/deletion was successful.
Operations on patient data are done through client.providers. Currently the backend supports create, get, update, filter and delete:
from healthcare.api import client
# Create new provider
provider = client.providers.create(name='Joe')
# Update the providers's name
client.providers.update(provider['id'], name='Jack')
# Refetch the provider record
provider = client.providers.get(provider['id'])
# Get providers with name containing 'Ja'
providers = client.providers.filter(name__like='Ja')
# Delete a provider record
client.providers.delete(provider['id'])
Providers currently store the following pieces of data [2]:
| Name | Type | Description |
|---|---|---|
| id | String | Globally unique identifier |
| name | String | A readable name/identifier |
| location | String | Identifier for the provider’s location |
| created_date | Datetime | Time when the record was created |
| updated_date | Datetime | Time when the record was last updated |
| status | String (A/I) | Flag to denote if the record is currently active |
| [2] | Required fields are bold and generated values are in italics. |
As with patients, the location field might store the name of the location or an identifier for another location/facility registry.
providers.create adds a new provider record to the data store. The arguments for this function are passed to the backend to store on the record. The provider data is returned as a dictionary and contains additional fields which are generated by the backend: id, created_date and updated_date.
providers.update takes the id of the provider along with arguments to be passed to the backend to update. This returns a boolean to note whether a matching provider was found and updated.
providers.get returns a provider’s data as dictionary for the given id. If no matching provider was found this will raise a ProviderNotFound exception.
providers.filter returns a list of matched provider data dictionaries. If there are no matches then it will be an empty list. Additional details on filtering expressions is given below.
providers.delete takes the id of the provider and returns a boolean to note whether a matching provider was found and deleted.
Both the patient and provider APIs support filtering the data by the fields in their respective models. The lookup expressions are modeled after the lookup types in the ORM. Unlike the Django ORM, there is no support for join-like expressions in the lookups.
exact is the default lookup type. As the name implies it requires an exact match between the field and given value.:
patients = client.providers.filter(name='Joe')
providers = client.providers.filter(name__exact='Joe')
The like lookup is a containment expression for string-type fields. For instance, this would be used to find data with a partial name match.:
patients = client.providers.filter(name__like='J')
providers = client.providers.filter(name__like='J')
An in expression is an exact match for a list of values. This lookup might be used to find a set of patients where you know all of their names.:
patients = client.providers.filter(name__in=['Joe', 'Jane'])
providers = client.providers.filter(name__in=['Joe', 'Jane'])
Similar to the ORM, the lt and lte expressions are inequality expressions. These are used to find data either strictly less than or less than or equal to a given value respectively.:
import datetime
patients = client.providers.filter(updated_date__lt=datetime.datetime.now())
providers = client.providers.filter(updated_date__lte=datetime.datetime.now())
gt and gte expressions are inequality expressions. These are used to find data either strictly greater than or greater than or equal to a given value respectively.:
import datetime
patients = client.providers.filter(updated_date__lt=datetime.datetime.now())
providers = client.providers.filter(updated_date__lte=datetime.datetime.now())