Category Archives: Smap Hints

Hints for using Smap

Zarkman Mobile for Android, iPhone and iPad

Zarkman Mobile is now in the google play store and Apple App store (search for zarkman) .



An Android phone with Android 2.3.3 or greater.

You need a hosted Smap Server that has version 15.09 or later.

Getting Connected

By default ZM is configured to connect to the Zarkman application server.  To connect to a Smap server you need to:

  • Select the menu. This is the button with 3 horizontal lines at the top left of the app.
  • Select “Settings”
  • Enable diagnostic mode.  (I need to change this label, its not just for diagnostics, although this is how I switch to my development server for testing).
  • Enter the name of the server into the “Test Server” box.   To use sg, just enter “sg”
  • Select change server
  • You will then need to logon
  • If you don’t have a user account on the sg server you can use:
  •     user: zm_test
  •    password: zm_test

Synchronising with the server

Either drag down on the forms screen or press Menu | Refresh

This will get new forms from the server and submit finished results.

Other Actions

  •  Select a form to complete it.
  • Select the records tab to view completed forms
  • Swipe left on the records tab to make a completed form into a template

Managing School Enrolments with Smap

Sometimes your forms need to change quickly.  One such case was suggested by World Vision staff who are working in Syrian refugee camps.  They wanted to record school attendance however new children are arriving daily and hence the attendance roll would be also changing daily.

Putting choices in a CSV file separate from the form can be the answer.   The file name is specified in the “appearance” column.  In the example below the choices will come from the “children.csv” file.  The other parameters to the “search” function are filters so that only children in “class1” are included.


Select Question Getting its Options from a CSV File

Choices in external CSV files have been available for a while, however the January 2014 release of Smap will have the following enhancements:

  • Support for select_multiple.  Previously only select_one worked,
  • You can now analyse select questions with external choices in graphs, tables and maps on the analysis dashboard,
  • and, CSV files can be attached to a single form or shared by all forms in the organisation.


This demonstration shows information on new school enrolments being collected using a form and then being added to a CSV file.  This file is then used to record attendance in school and is also used by a separate form to record vaccinations given to the children.

The data can be used in multiple forms because it is loaded to the “Organisation” tab in the media page rather than the “Form” tab. If you loaded different files with the same name to “Form” and “Organisation” then the file at the “Form” level will take precedence.

The files for this example can be found here.


  1. A school teacher uses fieldTask and a form called “enrolments” to record school attendance.  Any new children arriving that day are recorded in a sub form.  (using “begin repeat”)
  2. The back office team copy the details on the new children and put them into the “children.csv” file.  They upload this file to the Smap server where it replaces the existing file.
  3. The next day, before recording attendance, the Teacher presses “refresh” in fieldTask to get the latest form. They can then mark off the attendance of all the children including those that arrived the day before.
  4. A medical specialist using a form called “vaccinate”, presses refresh in fieldTask before checking the children in a class.  This will load the latest vaccination details into their phone.

CSV File


Children CSV file

This process is shown in the following video

Automation (Future)

The video showed a back office worker manually copying the daily enrolment data into the children CSV file.  This task could be automated by implementing a custom web page.  Apart from saving some effort for the back office administrators this would also apply updates faster resulting in more current data.

Other Applications of CSV files with Smap

CSV files storing data can be used in other applications, not just for school enrolments and vaccinations.  For example asset management, managing workforce etc.

Moving a form to a different project (New in 14.08)

This is a new feature in version 14.08.  You may find that you have too many forms in a single project which is confusing to the data collectors as they may not be sure which form they need to download and complete.

You can create additional projects in the user management screen and then move some of the forms into one of the new projects.

1. First click on the form name in the template management screen.  This will take you into the form editor.


Settings page of form editor

2. Select the project that you want to move to

3. Click on the “Save Settings” button

This will change your default project to the new project so if you want to move another form you will need to select the old project again then repeat the process



Areas and lines on webforms in version 14.05

Version 14.05 of Smap Server, due at the end of May, will support the drawing of areas and lines on top of maps.


Completing a geoshape question in webforms


Completing a geotrace question in webforms

Specifying the questions

You can add these questions in xlsform editor.

  1. For an area set the question type to “geoshape”.
  2. For lines set the question type to “geotrace”
  3. Set the appearance to “map” if you want to allow the data collector to select coordinates on a map as well as record location from their current position

Here is a sample form

One form per location question!

Don’t forget to put each geopoint, geoshape or geotrace question in a separate form.  The reason for this is that GIS systems assume that each table has a single location column and that all of the other columns are attributes of that location.  In Smap, 1 form becomes 1 table.  For example if you were recording the location of a water point and a household in one survey you would collect the household data in one form and then the water point data in another form.  The household form would contain the location of the household as well as the “attributes” of that location which is the other data about the household. The same goes for the water point.  In Smap you specify a different form by enclosing the questions in “Begin repeat” – “End Repeat” question types.

Use of geolinestring and geopolygon

Smap has had the ability to record areas and lines for some time using the geolinestring and geopolygon features.  These are still available and are useful in the following circumstances:

  1. You are using fieldTask which doesn’t yet support geoshape and geotrace
  2. You want to record data on each point.  For example you may want to record a temperature or a take a picture at each point of a line that you are recording.  Geolinestring and geopolygon allow you to add arbitrary questions to each point that is recorded.

Setting the default language

One of the new features in version 13.12 of the Smap Server is the ability to set the default language.  Previously this was always the last language entered in the survey work sheet.

There are two ways of setting the default.

1. The xlsform standard way is to add a new worksheet “settings”.  Provide a single column with a heading of “default_language” enter the default language under that column.


Default Language in Xlsform

2. The other approach is to specify the default language directly in the smap server.  You can change the default here any time without having to reload the template.  You do this from the template management screen. Select “view/edit” next to the name of the survey you want to change.


Default language on Smap Server

Then select the default language from the drop down list.





Creating Time Series Graphs

With the release of version 13.12 of Smap Server you can create graphs, maps and tables that show data against a time axis. This post describes a series of steps that proceed from a very simple bar chart to a, still simple, time series graph.  You can of course create these time series graphs in one step however you might use this approach of progressively refining your settings in order to show progressively increasing details.

The data in the examples is artificial and is from a survey that collects water depth in a well from two different  locations.  The water depth question was of type “integer”, the location question was of type “select_one”.

1. Bar chart of water depth

First select “Add Panel” to create a new panel, select your survey, and your question then press the “save” button. You will see something like the following. This shows the average water height for all locations at all times.


Bar Chart

2. Bar chart of Water Depth by Location

Then specify the location as the “group by” question. This will show the average water height at each location for the entire time of the survey.


Bar chart with “group by”

3. Time Series Plot of Water Depth by Location and Day

Then select the date question to use as the x-axis. This settings field is just under the name of the survey. Also select a period for the time axis. In this example I selected “day”.  The settings panel will then look something like this:


Settings Dialog Configured for Time Series

The resultant graph shows average water height per day and per location. Note the gap in data between the 14th of January and the 5th of February.  No measurements were taken during this period.


Time series chart by location by day

 4. Time Series Plot of Water Depth by Location and Week

If you then open the settings and change the period to “week” the x-axis of the graph will be updated so that average water height per week and per location is shown.


Time series chart by location by week


Limits on the number of questions per form

Recently a Smap customer, who are conducting a hospital audit, encountered problems loading a survey that had just under 2,000 questions.  The problem was caused by a limit in the Postgres database. There can be no more than 1,600 columns per table.  In a survey you can reach this limit either by specifying:

  • 1,600 questions
  • or 160 multiple choice questions with 10 options in each, since a separate column is used for each option in a multiple choice question
  • or a combination of the above

The solution to the problem is to enclose some questions within a repeat group with a “repeat_count” of “1”.  These questions will be written to a separate table in the database.

While the data collector is filling in the survey they will not be aware of this repeat group as it is set to automatically repeat just once.

When you export the survey results, if you select the “pivot” option, then the records from this “begin repeat” subform will be combined with the records from the main form.  However you will also have the option of exporting the main form and its sub form(s) separately.  I’ve seen exports of surveys to spreadsheets with over 3,000 columns and I’m not aware of any constraints on this.

I was able to load the large hospital audit survey after adding this begin repeat, end repeat solution. A future release of Smap will check that the maximum number of questions per form is not exceeded. If it is an error message will be shown.

Assign a task and export the results to Openstreetmap

This article demonstrates how to assign a task that will tell a user what data to collect and where to collect it.  The data will replace previously collected data and will then be loaded into Openstreetmap. An ODK compatible tool called fieldTask will be used.

Step 1. Create one or more tasks for someone to go and update the previously collected data.  This is done with the “Create Task” function in Smap. In this case I selected the previous address survey as the starting point and checked “Update existing results” which means that the old results will be replaced by the new. After creating the tasks they show up as red lines on the map on the “Assign” page. Red meaning “not yet allocated to anyone”.

assign task

Step 2. Assign the task. I assigned the longer survey containing odd addresses to myself.

Step 3. Download the task to the phone. On my phone I selected Menu then “Refresh Task List” which downloads the task and displays it in the task list and task map.

Step 4. Collect the new data. When I got to the location shown on the map I opened the survey and proceeded to record the missing addresses.

complete odk type survey in fieldTask

Step 5. Upload the results. After submitting the results, the dashboard shows that there are still two “good” records of address data, record 1 having been replaced by record 3.

Survey Analysis - Existing Record Replaced by new Record

I then exported the results in OSM format. This time I did not select any “ways” to be generated as I just wanted the address points. In JOSM I deleted the old address points that include an interpolation way, slightly adjusted the locations using Bing imagery and uploaded to the server. Click here to view the new addresses in Openstreetmap.

This technique could be useful during a response to a rapid onset emergency although it is unlikely that odk type surveys would be used to collect data that is loaded unchanged into Openstreetmap as it was here.  Instead there might be a need to take a subset of a complex survey and load only the tags relevant to OSM.  This would either be quite intensive manual work in JOSM or a filtering and transformation function could be added to the OSM export.

Testing a long survey

When creating long surveys for fieldTask you may want to try out a newly created, or modified section, that is a long way from the start. Its time consuming having to swipe past a lot of early questions and even worse if these have been set as “required”.  To quickly get to the right section you can use the “Go To Prompt” feature. Figure 1.

Start the survey in fieldTask or, odkCollect, select “menu” then “Go To Prompt”. A list of questions will be displayed which you can scroll through to find the question you want.

If you have repeating groups in your survey then this list of questions will initially stop at the repeat group.  To go further press on the downward arrow at the left of the repeat group name. Figure 2.



Figure 3

Then press on the name that will appear at the bottom of the screen. The questions in the repeating group will be shown and you can continue to scroll down to find the section that you want to test.