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: 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: 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 `, :ref:`get `, :ref:`update `, :ref:`filter `, :ref:`delete `, :ref:`link `, and :ref:`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']) .. _PATIENT_DATA_MODEL: Patient Data Model ____________________________________ Patients currently store the following pieces of data [#f1]_: ============== ============== ============== 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 ============== ============== ============== .. [#f1] 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`` ____________________________________ ``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`` ______________________________________________ ``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`` ______________________________________________ ``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 ` 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`` ______________________________________________ ``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`` ______________________________________________ ``patients.delete`` takes the id of the patient and returns a boolean to note whether a matching patient was found and deleted. .. _patients.link: ``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: Provider Data Model ____________________________________ Providers currently store the following pieces of data [#f2]_: ============== ============== ============== 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 ============== ============== ============== .. [#f2] 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())