RapidPro Flow Toolkit

Toolkit for using spreadsheets to create and modify RapidPro flows.

Quickstart

pip install rpft
rpft --help

Command Line Interface (CLI)

The CLI supports the following subcommands:

• create_flows: create RapidPro flows (in JSON format) from spreadsheets using content index
• flows_to_sheets: convert RapidPro flows (in JSON format) into spreadsheets
• convert: save input spreadsheets as JSON
• save_data_sheets: save input spreadsheets as nested JSON using content index - an experimental feature that is likely to change.

Full details of the available options for each can be found via the help feature:

rpft <subcommand> --help

Examples

Below is a concrete example of a valid execution of the command line tool using create_flows to convert a set of spreadsheets into RapidPro flows. The line breaks are merely for improving readability; the command would also be valid on a single line.

cd tests/input/example1
PYTHONPATH=. rpft create_flows \
  --output flows.json \
  --datamodels=nestedmodel \
  --format=csv \
  csv_workbook

The following is an example of the flows_to_sheets operation, essentially the reverse of create_flows.

mkdir output
rpft flows_to_sheets tests/output/all_test_flows.json output --strip_uuids

Using the toolkit in other Python projects

1. Add the package rpft as a dependency of your project e.g. in requirements.txt or pyproject.toml
2. Import the create_flows function
3. Call create_flows to convert spreadsheets to flows

from rpft.converters import create_flows

sources = ["workbook.xlsx", "csv_workbook"]
create_flows(
    sources, "flows.json", "csv", data_models="your_project.models"
)

It should be noted that this project is still considered beta software that may change significantly at any time.

RapidPro flow spreadsheet format

The expected contents of the input spreadsheets is documented separately:

• RapidPro sheet specification
• New features documentation

Processing Google Sheets

It is possible to read in spreadsheets via the Google Sheets API by specifying --format=google_sheets on the command line. Spreadsheets must be in the Google Sheets format rather than XLSX, CSV, etc.

Instead of specifying paths to individual spreadsheets on your local filesystem, you must supply the IDs of the Sheets you want to process. The ID can be extracted from the URL of the Sheet i.e. docs.google.com/spreadsheets/d/ID/edit.

The toolkit will need to authenticate with the Google Sheets API and be authorized to access your spreadsheets. Two methods for doing this are supported.

• OAuth 2.0 for installed applications: for cases where human interaction is possible e.g. when using the CLI
• Service accounts: for cases where interaction is not possible or desired e.g. in automated pipelines

Installed applications

Follow the steps in the setup your environment section of the Google Sheets quickstart for Python.

Once you have a credentials.json file in your current working directory, the toolkit will automatically use it to authenticate whenever you use the toolkit. The refresh token (token.json) will be saved automatically in the current working directory so that it is not necessary to go through the full authentication process every time.

Service accounts

Follow the steps in the creating a service account section to obtain a service account key. The toolkit will accept the key as an environment variable called CREDENTIALS.

export CREDENTIALS=$(cat service-account-key.json)
rpft ...

Development

For instructions on how to set up your development environment for developing the toolkit, see the development page.