Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
344 lines (222 sloc) 11.7 KB

Basic Usage

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')

Available Backends

Where this data is stored configured by the :ref:`HEALTHCARE_STORAGE_BACKEND` setting. Below are all of the available backends included in the rapidsms-healthcare distribution.

DjangoStorage

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.

DummyStorage

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.

Patient Information

Operations on patient data are done through client.patients. Currently the backend supports :ref:`create <patients.create>`, :ref:`get <patients.get>`, :ref:`update <patients.update>`, :ref:`filter <patients.filter>`, :ref:`delete <patients.delete>`, :ref:`link <patients.link>`, and :ref:`unlink <patients.link>`:

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'])

Patient Data Model

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

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

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

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 :ref:`link <patients.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

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

patients.delete takes the id of the patient and returns a boolean to note whether a matching patient was found and deleted.

patients.link and patients.unlink

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.

Provider Information

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'])

Provider Data Model

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

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

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

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

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

providers.delete takes the id of the provider and returns a boolean to note whether a matching provider was found and deleted.

Filter Expressions

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

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')

like

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')

in

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'])

lt and lte

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

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())