JarCasting
Table of Contents
Introduction
OpenSRP Client Core App/Module basically provides basic functionality such as networking, security, database access, common widgets, utilities, domain objects, service layer, broadcast receivers and syncing.
Features
It provides:
- Domain objects for forms and database.
- Mappers between the different domains
- Basic and advanced networking capabilities to securely and efficiently connect to an OpenSRP backend
- Sync abilities that handle and maintain data consistency between the client and backend
- Data creation, edit, retrieval and deletion capabilities on the client device
- Security services that maintain global data and application security
- Utilities used for file storage, caching, image rendering, logging, session management and number conversions
- Access to tailored android views/widgets for OpenSRP
- Device-to-device sharing of application data - This includes events, clients and profile images
Why OpenSRP?
- It provides client access on Android phones which are easily available and acquirable
- It can work with minimal or no internet connection
- It provides enhanced security
- It primarily integrates with OpenMRS
- It is tailored to be used by health workers who regularly provide outreach services
- It generates custom reports eg. HIA 2
- It manages stock levels for stock provided to the health workers
- It implements the WHO-recommended z-score for child growth monitoring
- It provides device-to-device sharing of medical records in areas without an internet connection.
Website
If you are looking for more information regarding OpenSRP as a platform checkout the OpenSRP Site
Developer Documentation
This section will provide a brief description on how to build and install the application from the repository source code.
Pre-requisites
- Make sure you have Java 1.7 to 1.8 installed
- Make sure you have Android Studio installed or download it from here
Installation Devices
- Use a physical Android device to run the app
- Use the Android Emulator that comes with the Android Studio installation (Slow & not advisable)
- Use Genymotion Android Emulator
- Go here and register for genymotion account if none. Free accounts have limitations which are not counter-productive
- Download your OS Version of VirtualBox at here
- Install VirtualBox
- Download Genymotion & Install it
- Sign in to the genymotion app
- Create a new Genymotion Virtual Device
- Preferrable & Stable Choice - API 22(Android 5.1.0), Screen size of around 800 X 1280, 1024 MB Memory --> eg. Google Nexus 7, Google Nexus 5
How to install
- Import the project into Android Studio by: Import a gradle project option All the plugins required are explicitly stated, therefore it can work with any Android Studio version - Just enable it to download any packages not available offline
- Open Genymotion and Run the Virtual Device created previously.
- Run the app on Android Studio and chose the Genymotion Emulator as the
Deployment Target
Developer Guides
If you want to contribute please refer to these resources:
- Getting started with OpenSRP
- Setup Instructions
- Complete OpenSRP Developer's Guide
- Peer-to-Peer Library Guide
Wiki
If you are looking for detailed guides on how to install, configure, contribute and extend OpenSRP visit OpenSRP Wiki
Uses
OpenSRP Client core has been used in several modules and applications:
- OpenSRP Path application
- OpenSRP KIP application
- OpenSRP Growth monitoring library
- OpenSRP Immunization library
- OpenSRP Native Form library
Main Functions
1. Security
Security is provided in the following:
- Network - It supports SSL certificates from Let's Encrypt CA
- Data access - Only registered providers are able to view and manipulate records
- Data encryption - The database on the android client is encrypted with 256-bit AES encryption using SQLCipher.
The security classes can be found in org.smartregister.ssl
Under the cryptography package we have CryptographicHelper class whose instance exposes methods
byte[] encrypt(byte[] input, String keyAlias) For encryption of a byte array input with key
byte[] decrypt(byte[] encrypted, String keyAlias) For decryption of encrypted byte array with key
Key getKey(String keyAlias) For retrieving a generated key stored in the Android keystore
void generateKey(String keyAlias) For key generation using a Key Alias parameter for use by Android keystore
- NB: * This class depends on
AndroidLegacyCryptographyclass and theAndroidMCryptographyclass which both implement the above in different ways depending on the SDK version.AndroidLegacyCryptographyhas method implementation that are used when the SDK version is less than API level 23
2. Data management
This app provides data management.
It implements both plain and secure data storage. Classes implementing secure storage extend SQLiteOpenHelper, Repository or BaseRepository.
The rest use the SQLite helpers provided in the Android SDK.
For this reason, there are multiple implementations for storing the same model(s).
| Class | Represents |
|---|---|
EventClientRepository |
Events |
AlertRepository |
Alerts |
ChildRepository |
Children |
ClientRepository |
Clients/Patients |
DetailsRepository |
Details |
EligibleCoupleRepository |
Eligible couples |
EventRepository |
Events |
FormDataRepository |
Form data |
FormsVersionRepository |
Form version |
ImageRepository |
Image locations |
MotherRepository |
Mothers |
ServiceProvidedRepository |
Provided service to the patient |
SettingsRepository |
App settings eg. connection configurations |
TimelineEventRepository |
Timeline events |
The data management classes can be found in org.smartregister.repository
3. Networking
This app provides the following networking capabilities:
| Class | Represents |
|---|---|
OpensrpSSLHelper |
SSL Connection helper |
OpenSRPImageLoader |
Asynchronous image downloader |
HttpAgent |
Synchronous networking class with username\password (Basic Auth) access support |
ConnectivityChangeReceiver |
Network status detection by a broadcast receiver |
GZipEncodingHttpClient |
GZip encoding and decoding capabilities |
Session |
Session management |
UserService |
User authentication & client-server time synchronization |
The networking classes can be found in:
org.smartregister.serviceorg.smartregister.utilorg.smartregister.clientorg.smartregister.sslorg.smartregister.view.receiver
4. Domain Objects
This app provides the following domain objects:
| Class | Represents |
|---|---|
Address |
Location address containing map coordinates |
BaseDataObject |
Data object with datestamps, void flag, related void details and server version |
BaseEntity |
Extends BaseDataObject to include the baseEntityId, identifiers, addresses and attributes that are common in OpenSRP models |
Client |
Represents a patient in OpenSRP eg. a child. It contains relevant patient details and extends BaseEntity |
ColumnAttribute |
Represents a column using the type, is-primary-key and is-index properties. It is used in the EventClientRepository class to define and access columns in the appropriate table |
Event |
It represents an event in OpenSRP which are mainly encounters eg. Birth Registration, Death. It extends the BaseDataObject and provides other properties |
Obs |
It represents an observation in an Event above |
Query |
It represents a data query and enables creation of queries using an OOP approach |
FormData |
It represents form fields, their inputs and any sub-forms |
FormField |
It represents a single form question/field with a name, value and source |
FormInstance |
It represents a FormData of a specific definition version |
FormSubmission |
It represents the status of a form before or after submission. It therefore contains other metadata such as client version and server verion. |
SubForm |
It represents a form inside another form |
Alert |
It represents a notification about an encounter which is due or overdue the expected time |
ANM |
It represents a health services provider |
Child |
It represents a child |
EligibleCouple |
It represents an eligible couple |
FormDefinitionVersion |
It represents a form version |
Mother |
It represents a mother |
Photo |
It represents a photo by storing the file path & resource id |
ProfileImage |
It represents the photo of an entity |
Report |
It represents a report |
MontlyReport |
It represents a monthly report |
Response |
It represents an HTTP response with status & payload |
ServiceProvided |
It represents a service that was provided to a patient |
TimelineEvent |
It represents an event within a patient's life eg. birth |
The domain object classes can be found in org.smartregister.domain. There are several domains namely: global domain, form and database domain.
5. Sync
This app provides the following sync capabilities:
- Periodic syncing based on network connection
- Updating views with updated information
The sync classes can be found in org.smartregister.sync
6. Utilities
This app provides the following utilities:
| Class | Provides |
|---|---|
BitmapImageCache |
Improved image caching |
Cache |
Data caching and modifications listener |
FileUtilities |
File storage utility |
FloatUtil |
Float conversion utility |
FormSubmissionBuilder |
Form submission builders |
FormUtils |
Form generation and manipulation utility |
IntegerUtil |
Integer conversion utility |
JsonFormUtils |
JSON form data extractor and injector |
OpenSRPImageLoader |
Asynchronous image downloader with thread-safe image caching |
Session |
Session manager |
StringUtil |
String manipulation utility |
TimelineEventComparator |
Timeline event comparator |
Utils |
Date conversion, android preference manipulator, view generator, metrics humanizer among other basic utility functions. |
AppExecutors |
Provides implementation of the executor interface that allows grouping request. Grouping tasks like this avoids the effects of task starvation (e.g. disk reads don't wait behind webservice requests) |
The utility classes can be found under org.smartregister.util
7. Services
This app provides business logic for operations as follows:
| Class | Business logic related to |
|---|---|
ActionService |
Actions |
AlertService |
Alerts |
AllFormVersionSyncService |
Form versions |
ANMService |
Health service providers |
BeneficiaryService |
Beneficiaries |
ChildService |
Children |
Drishti |
Form submissions |
MotherService |
Mothers |
ServiceProvidedService |
Services provided |
The service classes can be found in org.smartregister.service
8. App Localization
This app provides capability to support multiple languages.
Check out the sample app to see how to implement language switching.
Ensure each class in your app extends (directly or indirectly) a class in client-core. If it doesn't then extend MultiLanguageActivity instead of AppCompatActivity.
9. Data Compression
The package compression contains an interface ICompression whose methods are Implemented using the GZIPCompression class (which uses a GZIP implementation) Other compression Algorithms can be used by adding a new class implementing the interface methods.
Methods in the ICompression interface are
byte[] compress(String rawString) Compress the given string input
String decompress(byte[] compressedBytes) Decompress a byte array of compressed data
void compress(String inputFilePath, String compressedOutputFilepath) Compress file in file path inputFilePath and output to location compressedOutputFilepath
void decompress(String compressedInputFilePath, String decompressedOutputFilePath) Decompress file in file path compressedInputFilePath and output to location decompressedOutputFilePath
10. Bootstrap View Generation
You can quickly bootstrap view generation that take the format of a Register or Profile using the package org.smartregister.view. Views that render a Register can extend the BaseRegisterFragment that implements basic register functionality such as searching, listing, sorting and counting number of records on the generic base view whilst reading a cursor object.
For views that display a generic List of items but require heavier customization, using the org.smartregister.view.fragment.BaseListFragment<T> allows you to render any generic list while providing a context aware background executor and error handling that only requires provisioning or Callable function to act as a data source. Check the Sample app's ReportFragment that consumes a Retrofit response and renders a list of objects.
Configurability
By placing a file named app.properties in your implementation assets folder (See sample app) , one can configure certain aspects of the app
Configurable Settings
| Configuration | Type | Default | Description |
|---|---|---|---|
system.toaster.centered |
Boolean | false | Position toaster(s) at the center of the view(s) |
disable.location.picker.view |
Boolean | false | Disables LocationPicker View |
location.picker.tag.shown |
Boolean | false | Hides/Shows the location tag in the location picker tree view |
encrypt.shared.preferences |
Boolean | false | Enable/disables encrypting SharedPreferences |
