Use case: Managing a list of farmer beneficiaries

This article is accompanied by sample forms, dataset definitions and sample data saved in this folder.


In the agricultural sector, a common use of SurveyCTO is to keep track of farmers. A typical scenario is where an agricultural programme officer leads a training on an intervention aimed at training local farmers on how to implement a new farming technique. This usually involves holding a workshop with selected farmers in a locality. The programme officer would like to keep track of all the attendees and in due course follow up with them to check on how they are progressing with the lessons learnt. The officer will want to do the following:

  1. Register farmers.
  2. Record the presence of farmers at meetings.
  3. Update farmers' details.
  4. Delete a record of a farmer.

In this article, we will walk through a sample workflow for managing a list of farmer beneficiaries using SurveyCTO.

This workflow is broadly applicable, illustrating how to generate and maintain a list of many other things aside from farmers (e.g. schools, latrines, drugs, or clinics) in a server dataset through form submissions. If your use case is not agriculture, you can still learn something.

Workflow components

These are the files that you will need to deploy on your server to test this workflow:


  Component File name
baseline_description_black_18dp.png Form definition - Farmer management,
- Farmer attendance
baseline_power_black_18dp.png Field plug-ins -
excel_file.png Server dataset definition - farmer_list.xml


The sample forms, dataset definition and sample data are saved in this folder whilst the table-list field plug-in can be downloaded from here. Follow these instructions to deploy them on your server console.

Features that enable this workflow

This use case uses the following features of SurveyCTO:





  1. Using expressions in your forms: a reference for all operators and functions

Pre-loading using pulldata()

  1. Pre-loading data into a form
  2. Webinar

Pre-loading choice lists using search()

  1. Pre-loading: Searching and selecting from pre-loaded data

Server dataset publishing

  1. Publishing form data into server datasets
  2. Webinar

Field plug-ins

  1. Using field plug-ins
  2. Field plug-in catalog


Understanding the workflow

The workflow is built around two forms and one server dataset. You will understand this workflow best trying it in practice, once you've correctly deployed it to your SurveyCTO server. Each major action in the workflow is described below.

Farmer management form

This form is used to:

  1. Register a farmer
  2. Update farmers details
  3. Delete a record of a farmer

Registering a farmer

This form will be filled in at least once for each individual farmer. When filling in the form, select the “Register a new farmer” action and enter the farmers details. The information about the towns and wards is pre-loaded from an attached CSV file ("zambia_wards.csv").. The search() function is used to filter down to the relevant ward based on the selected town. Once the farmer details are completed, save and submit the form. Every time the form is submitted the farmers information is published to the “farmer_list” server dataset ("farmer_list.xml"). 

Updating the farmer

To update the details of a farmer on record, select the “Update records of a farmer” action. This loads the list of farmers from the “farmer_list” dataset and displays it in a table using the table-list field plug-in. Select the farmer and edit the required fields. Upon saving and submitting the form, the fields are published with the updated details.

Deleting a farmer

To delete or de-register a farmer, select the “De-register an existing farmer” action. A table of all the farmers is displayed from which a farmer can be selected. Once a form is submitted the farmer will not show up on lists any more. This is accomplished using the “include” calculate field in the Farmer management form which is set to 1 for registered active farmers and 0 for de-registered inactive farmers. Strictly, nothing is deleted by the "include" value is used to filter the list of farmers using the search() function, achieving the same result for form users.

Farmer attendance

This form is used for taking attendance at a meeting. It first collects some information about the meeting then presents a list of farmers using the table-list field plug-in, from which farmers present can be ticked off. THe plug-in allows for displaying multiple columns of information about each farmer, making it easier to identify and differentiate the farmers. 

It also provides an option for marking farmers that have communicated their absence at the meeting. 

Alternative designs and improvements

This use case has been purposefully kept as simple as possible, but in practice, you might have some slightly different needs to solve for. Here are just a few ideas on how to adapt this use case.

Working without an internet connection

It is possible that the meetings with farmers that you'll want to record will take place in internet-disconnected parts of the world. While SurveyCTO Collect works well for mobile data collection whether online or offline, some workflows depend on being able to exchange information with your server. For example, in this use case, farmers are registered in one form, and submitting data updates a list of forms stored on the server which is used as a choice list in another form. This requires an internet connection.

 However, there is no reason why you cannot register a new farmer and their attendance all inside the same form submission. It is a convenience to register attendance together in the same form submission, but if that's not possible, one can collate attendance data across new farmers collected offline, and new farmers.

Simply add a conditional question to the Farmer management form that asks whether the user would like to register that farmer's attendance at a meeting.

Recording meeting attendance at specific sites

It is likely that meetings will have limited reach, with farmers only travelling to the town nearest to them, or one town over. In such a scenario it may be useful to see a sublist of farmers from that specific area only rather than the full list of farmers. There a couple of ways in which this can be done:

  1. The easiest is to simply use the search box that is part of the table-list field plug-in. You can type the name of the area in the search box and the list of farmers will be filtered based on this name. You can then mark the farmers present from that list.
  2. Another option is to extend the search() function that is in the appearance of the "farmer_present" field to include a filter. You can add a question before this field that asks which area the meeting is taking place in and then use this filter what is shown in the table-list. The current form of the search is: 
search('farmer_list', 'matches', 'include', 1) 

which would change to

search('farmer_list', 'matches', 'include', 1, 
columnToFilter, filterText)

where columnToFilter is the column in the CSV file you want to filter by. If the area is a ward, this would be the ward column of the zambia_wards.csv whereas if you wanted to filter by a town, this would be the town column of the same file. 

filterText is the actual town or ward you want to filter by. Ideally this would be the answer to the question about the area in which the meeting is taking place.

Preventing duplicate registrations

A common question around registration workflows relates to duplicate entries. You have to think through how to avoid registering the same farmer more than once and be able to differentiate farmers with similar names which is not uncommon. 

One approach is to create an ID that is a combination of a number of characteristics of each individual farmer. You can combine the name, gender, age and other responses together using the concat() function to give a string that will be unique to a farmer and publish this string to the server dataset. When creating the farmer, you can preload this value into the form and compare the generated string with the preloaded string. If the two are the same, then there may be a duplicate farmer; otherwise you can go ahead and add the farmer. A similar setup is described in this article, particularly the section on Using server datasets.

Do you have thoughts on this guide? We'd love to hear them! Feel free to fill out this feedback form.


Article is closed for comments.