Rapidpro Sidekick¶

Sidekick is a Django application which provides additional functionality to RapidPro through RapidPro’s webhooks within flow, as well as using RP’s REST API to initiate flows, update contact fields etc. In some respects it functions much like setting up serverless functions to handle webhooks and return responses. However there are some additional benefits to using a Django application, primarily User authentication and management, as well as management of RapidPro Orgs.

Local installation¶

To set up and run rp-sidekick locally, do the following:

$ git clone git@github.com:praekeltfoundation/rp-sidekick.git
$ cd rp-sidekick
$ virtualenv ve
$ source ve/bin/activate
$ pip install -e .
$ pip install -r requirements-dev.txt
$ pre-commit install

RP-Sidekick does not work with SQLite because it uses JSONFields. This means that you will need to set up PostgreSQL locally. You can spin up a local db with docker, using the following command:

$ docker run -d -p 5432:5432 --name=sidekick_db -e POSTGRES_DB=rp_sidekick postgres:9.6

Tools¶

black - this repository uses an opinionated python code formatter. See pyproject.toml for config.
pre-commit - lints staged code as a git pre-commit check. Will prevent commits if linting fails. Currently runs black, flake8 and yamllint.

Contributing¶

See our ways of working for a guide on how to contribute to rp-sidekick.

VERSIONS¶

Next Release¶

1.2.1¶

Reformat with updated black package

1.2.0¶

Sidekick: Added a check contact endpoint for WhatsApp

1.1.0¶

Sidekick: Fixed document structure and updated docs
Sidekick: updated WA templated message endpoint to accept multiple localizable params
BREAKING: any flows that call the /send_template/ endpoints must change the param message= to 0=

1.0.17¶

TransferTo: Added error code to responses where TransferToClient returns an error

1.0.16¶

ASOS: Fixed notification for empty screening record.

1.0.15¶

TransferTo: added hacky fallback method for product purchase and take action task

1.0.14¶

TransferTo: refactored task functionality into to take_action function - updates RapidPro fields and/or starts another flow
TransferTo: add endpoint which purchases airtime, then updates RapidPro state with new take_action function
Sidekick: add email functionality in settings
TransferTo: send email on TransferTo failure task; buy_product_take_action

1.0.13¶

TransferTo: default to using cached msisdn number in views
TransferTo: add endpoint which purchases product then updates fields and/or starts another flow

1.0.12¶

TransferTo: store data on number in database

TransferTo: use cached msisdn number in tasks

TransferTo: refactored tests for tasks

Redcap: Allow blank Nomination url

Redcap: Send names when starting patient reminder flow

1.0.11¶

Install PyCap from Github commit until they make a release(temporary)

Add Hospital and PatientRecord to admin site

1.0.10¶

Added function to do WhatsApp contact check

Added function to update Rapidpro Contact with WhatsApp ID

Redcap: Added tasks to send patient data collection reminders

Redcap: Fixed updated_at field for values

1.0.9¶

Django version bump

1.0.8¶

Clean message before sending to Engage

1.0.7¶

Endpoint to send templated WhatsApp messages to Engage.

Rapidpro Sidekick¶

Sidekick is a Django application which provides additional functionality to RapidPro through RapidPro’s webhooks within flow, as well as using RP’s REST API to initiate flows, update contact fields etc. In some respects it functions much like setting up serverless functions to handle webhooks and return responses. However there are some additional benefits to using a Django application, primarily User authentication and management, as well as management of RapidPro Orgs.

Local installation¶

To set up and run rp-sidekick locally, do the following:

$ git clone git@github.com:praekeltfoundation/rp-sidekick.git
$ cd rp-sidekick
$ virtualenv ve
$ source ve/bin/activate
$ pip install -e .
$ pip install -r requirements-dev.txt
$ pre-commit install

RP-Sidekick does not work with SQLite because it uses JSONFields. This means that you will need to set up PostgreSQL locally. You can spin up a local db with docker, using the following command:

$ docker run -d -p 5432:5432 --name=sidekick_db -e POSTGRES_DB=rp_sidekick postgres:9.6

Tools¶

black - this repository uses an opinionated python code formatter. See pyproject.toml for config.
pre-commit - lints staged code as a git pre-commit check. Will prevent commits if linting fails. Currently runs black, flake8 and yamllint.

Contributing¶

See our ways of working for a guide on how to contribute to rp-sidekick.

RP Sidekick¶

The default Sidekick Module exists to provide shareable components across the various django applications, in particular the Org and User management. It also provides some miscellaneous functionality, in particular, the ability to send WhatsApp templated messages

Check WhatsApp Endpoint¶

This endpoint, served at /check_contact/<org_id>/<msisdn>/ serves as a wrapper for a single request to the Turn contact check endpoint.

WhatsApp Template Endpoint¶

RapidPro does not yet provide first-class support for WhatsApp templates, which means that they need to be sent via Sidekick, using a Webhook within RapidPro.

Required Parameters¶

org_id: this refers to the Organisation created within Sidekick. You can find this in the Admin page. There is a 1-to-1 mapping between the Org and a Turn account. Make sure you have added the necessary credentials to your Org.
wa_id: this will be the number of the individual you wish to contact. In RapidPro flows, this can be accessed using @contact.whatsapp
element_name: the name of the template that you are using. You will have created this when submitting it to WhatsApp for approval.
namespace: this argument will likely be fixed across your organisation. Check previous uses or check with whoever set up your WA account.

Localized Parameters¶

Templated messages allow you to pass in variables. See the Turn documentation for more details. These can be passed to the endpoint by numbering your param arguments. e.g. 0=R25&1=24 will pass the parameters R25 and 24 to the template, in that order. Note that this endpoint only orders the arguments, it does not attempt to skip over arguments. Thus 0=R25&1=24, 1=R25&2=24 and 1=R25&99=24 will all be treated in an identical manner.

RP ASOS¶

PatientDataCheck Task¶

This task compares the patient records to the screening records for each day, and sends notifications to hospital leads and one more nominated person.

The hospital lead will captured a screening record for each week, the date is set to the Monday, this record is updated daily with the number of eligible cases that needs to be captured. This task will run daily and check if the patients captured on the previous day matches the number in the screening record for that day.

Each project will represent a country, with hospital split up by Data Access Groups on Redcap.

The task is started by doing a POST request on the /asos/start-patient-check/<project-id> endpoint.

The task will keep track of the changes being made to the patient records.

The number of days included in the check is configured by the ASOS_HISTORICAL_DAYS environment variable, the default is 3.

Configuration¶

Hospital:

name The name of the hospital send to the RapidPro Flow.
data_access_group Used to filter records from Redcap.
rapidpro_flow UUID of the reminder flow that will get started in Rapidpro
hospital_lead_name Name of the hospital lead.
hospital_lead_urn URN where reminder will be sent.
nomination_name Name of second nominated person to receive reminder(Optional).
nomination_urn URN where second reminder will be sent(Optional).

RP REDCAP¶

ProjectCheck Task¶

This task checks for incomplete surveys and notifies the survey participant by starting a flow in Rapidpro.

The task is started by doing a POST request on the /redcap/start-project-check/<project-id> endpoint.

The task will keep track of the values being changed by the survey participant.

RP TransferTo¶

While RapidPro does provide an integration with TransferTo to release airtime, it does not allow for the remuneration of data. This application more faithfully represents the REST API that TransferTo makes available and abstracts away the authentication.

Synchronous Endpoints¶

Ping: check that our authentication to TransferTo is working
MsisdnInfo: get information about an MSISDN
ReserveId: get ID for a purchase transaction in the future
GetCountries: get the countries that a particular account can
GetOperators: get mobile network operators (MNO) for a country
GetOperatorAirtimeProducts: get products list and prices (wholesale and retail) specific to your account
GetOperatorProducts: get products offered by a particular MNO
GetCountryServices: get services available in a particular country
TopUpData: an endpoint that immediately returns a 200 status code and then starts a Celery task to get information about a number, send the reward and update the necessary fields in RapidPro.

Asyncronous Endpoints¶

These endpoints will queue the request to TransferTo using celery. They will immediately respond with a 200 response code once the task is queued, preventing any timeouts on RapidPro. Use the flow_uuid_key arg to get the tasks to start the participant on a new flow, assuming that it works according to plan.

BuyProductTakeAction: this endpoint allows the user to
- purchase a product for a particular msisdn
- [optional] update a rapidpro contact’s fields based on the response
- [optional] start the participant on another rapidpro flow, once the task has been completed.
BuyAirtimeTakeAction: this endpoint allows the user to
- purchase airtime for a particular msisdn
- [optional] update a rapidpro contact’s fields based on the response
- [optional] start the participant on another rapidpro flow, once the task has been completed.

Ways of Working¶

There are particular ways that this team is attempting to develop rp-sidekick. This section documents those processes.

Rebasing¶

In this code base, we enforce rebasing on GH instead of merging your commits. This document does not attempt to explain rebasing. Please see here for an explanation. In brief, however, if no additional commits have been added to the develop branch while you have been working on a feature, this should not be an issue for you, and Github will simply offer you the option to Rebase and Merge within the PR. However, if it detects merge conflicts, you will need to make sure that your branch is rebased manually and deal with the merge conflicts before merging it in to the develop branch (i.e. as though you made your changes on top of the latest changes in the develop branch).

Locally, you can do this with:

$ git rebase develop

Then solve the merge conflicts and other nastiness and run:

$ git rebase --continue

Please feel free to reach out to the maintainers of this project to help you through this if you’re not comfortable.

Once you’re satsfied with local changes, you can overwrite your PR branch with the following:

git push --force-with-lease