RapidPro is an open-source platform that allows users to build and manage interactive mobile messaging services. It is primarily used by non-governmental organizations (NGOs), government agencies, and social enterprises to communicate with and engage with their beneficiaries and front-line workers. RapidPro is particularly well-suited for working in low-resource settings where internet connectivity may be limited or unreliable. This article presents a comprehensive guide on how to use the RapidPro surveyor for offline handling of RapidPro flows in a mobile app.

To seamlessly integrate RapidPro into your project, follow the insightful instructions outlined at RapidPro Setup for setting up a development instance of RapidPro.

What is RapidPro Surveyor?

RapidPro Surveyor is an open-source powerful flow engine that allows users to collect and submit data offline using RapidPro flows. Therefore, this makes it a valuable tool for collecting data in areas with limited or no internet connectivity.

Key features of RapidPro Surveyor

  • Offline data collection: Users can collect data and multimedia content (audio, images, video, and GPS) without an internet connection.
  • Flow execution: Users can execute RapidPro flows, which are sequences of instructions that guide the data collection process.
  • Data submission: Once connected to the internet, users can submit their collected data back to RapidPro for analysis and reporting.

Benefits of using RapidPro Surveyor

  • Improved data collection efficiency: Users can collect data in remote areas without worrying about internet connectivity.
  • Increased data quality: Users can capture multimedia content to supplement their responses, providing more context for the data.
  • Reduced data loss: Stores collected data locally on the user’s device, minimizing the risk of data loss due to internet outages.

Use cases for RapidPro Surveyor

  • Surveys and questionnaires: Collecting data from respondents in remote areas.
  • Monitoring and evaluation: Tracking program performance and outcomes in under-served communities.
  • Research and data collection: Conducting field research and capturing data on social issues.

Challenges in Offline Surveyor Integration with Mobile App

  • Caching a large amount of data from the RapidPro server.
  • Handling large media files (audio, video, etc.) in the background can pose challenges.
  • Real-time offline surveyor data synchronization.
  • Offline surveyor data validation and error handling.
  • Offline surveyor data submission reliability.

GoFlow, which is an open-source library based on Go language, contains necessary tools to overcome these obstacles. Additionally, convert GoFlow library to goflow.aar in order to handle with Java library.

What is GoFlow?

GoFlow is a Golang library that serves as the core flow engine for RapidPro. It is responsible for validating, migrating, and executing RapidPro flows. These are essentially automated workflows that define how interactions with users are handled in RapidPro applications. Moreover, GoFlow comes embedded within Mailroom, a high-performance Golang application that handles messages that Courier receives, and executes flows, generating new messages or events as needed.

What is goflow.aar?

It consists of Java wrapper functions that bridge the gap between the GoFlow Go library and the Android Archive file (.aar) for Android platform. Thus, these wrapper functions will expose GoFlow’s functionalities to the Java code in your Android application.

Prerequisites for goflow.aar

  • Android Studio v4.1.0 or higher
  • Java SDK 8 or higher
  • Minimum SDK v21
  • Gradle version 5.0

Setting up goflow.aar

  • Create a new  Android project
  • Open the project to android studio
  • Download goflow.aar
  • Import goflow.aar file to root directory
  • Add this file to the app Gradle dependencies.
  • Sync your Gradle file

Caching Data from RapidPro Server to Mobile App

In this guide section, there are technical steps and explanation of the code that allows the RapidPro Surveyor to carry out its offline flow handling capabilities through a mobile application.

TembaAPI Interface Declaration

This defines a publicly accessible interface that encompasses the entire RapidPro server API declaration.

// TembaAPI example code here
public interface TembaAPI {
  Call<PaginatedResults<Flow>> getFlows(
      @Header("Authorization") String token,
      @Query("type") String type, @Query("archived") Boolean archived,
      @Query("cursor") String cursor);

Here we have used the GET method which is an annotation of a retrofit library. By employing the Retrofit library, we establish a link between the mobile network and the server, allowing us to retrieve the necessary data. Additionally, the code provided above fetches the flow list from the server.

Create Temba Service Class

The Temba service class is responsible for providing an interface to the Temba API.

// Temba service example code here
public class TembaService {
  public List<Flow> getFlows(final String token) throws TembaException {
    return fetchAllPages(new PageCaller<Flow>() {
      public Call<PaginatedResults<Flow>> createCall(String cursor) {
        return api.getFlows(asAuth(token), "survey", false, cursor);

It implements the TembaAPI interface and provides methods for creating, retrieving, updating, and deleting Temba objects. The Temba service class is typically a singleton object that is responsible for managing all interactions with the Temba API. Basically, it provides a centralized location for all Temba-related operations and ensures that all interactions with the Temba API are consistent and reliable.

Persisting all data to a local database Using GoFlow library

Use the Org instance to manage access to the mobile app REST API. The environment is used to create and manage sessions. On the other hand, the assets reference stores and retrieves assets, such as reports and data sources.

// Create new Org instance of parse rest data to json data
Org org = Org();
// Create new an environment using goFlow engine for mobile session management
Environment environment Engine.createEnvironment(org);
// Create assets reference from SessionAssets
SessionAssets assets = Engine.createSessionAssets(

Here is a more detailed explanation of the code: 

Org org = Org(); 

This line creates a new Org instance. The Org class is used to manage access to the Ureport REST API. 

Environment environment = Engine.createEnvironment(org);

This line creates a new environment. The environment is used to create and manage sessions. 

SessionAssets assets = Engine.createSessionAssets(environment, Engine.loadAssets(org.getAssets()));

The “createSessionAssets” functionality, embedded within the goFlow “Engine” structure, has enabled us to effectively implement a session management mechanism.

Retrieve all flows stored in the local cache

Upon completion of storing all data in the device’s local cache, we will provide an example code snippet illustrating the retrieval of all flows from the local cache.

So, here is a more detailed explanation of the code:

// Retrieve flows from local cache using GoFlow
static List<Flow> getFlows(File directory) throws IOException {
  if (!directory.exists() || !directory.isDirectory()) {
    throw new RuntimeException(
        directory.getPath() + " is not a valid org directory");
  // read flows.json
  String flowsJson = FileUtils.readFileToString(new File(directory, FLOWS_FILE));

  TypeToken type = new TypeToken<List<Flow>>() {};
  return JsonUtils.unmarshal(flowsJson, type);

The method takes a File object named directory as a parameter. The first two lines of the method check if the directory exists and is indeed a directory (not a file). If either condition fails, a RuntimeException is thrown with an appropriate error message.

Assuming the directory is valid, the method reads the contents of a file named flows.json located within the directory. The FileUtils class provides a static method readFileToString() that reads the contents of a file and returns them as a String.

The method then uses the JsonUtils class to convert the JSON data from the flows.json string into a list of Flow objects. Moreover, the TypeToken class is used to specify the type of the list, which is List<Flow>.

Finally, the method returns the list of Flow objects. This list contains all the defined flows in the flows.json file.


By following these initial steps in this guide, we have integrated goflow.aar to enable Rapidpro offline surveyor functionality in the  U-Report BD mobile app to UNICEF. Hence, you will effectively enable offline survey management within your Android application using the goFlow.aar library. This includes storing data locally, synchronizing with the server, and presenting surveys to users.

This page was last edited on 14 December 2023, at 10:48 am