Note: Integration is currently in beta. If you are interesting in using the SurveyCTO-to-DevResults integration, email us at firstname.lastname@example.org.
We are pleased to announce that SurveyCTO is now able to integrate with DevResults! DevResults is a web-based monitoring and evaluation (M&E) tool for organizing and visualizing your data. You can create graphs, reports, and even dashboards based on your data. For more details about DevResults and what this integration can do for you, see this blog post announcement.
To get started with DevResults, go through the self-guided tutorial. Also, check out their documentation on how to Import Data From SurveyCTO. This article will give you an overview of how to import SurveyCTO data into DevResults, what data can be imported, and a few more tips. For information on how to work with that data, check out the DevResults knowledge base.
Creating forms for DevResults
Depending on what you want to do in DevResults, here are some ways you can optimize your form design for the best results.
- You cannot delete rows of data from a SurveyCTO-sourced table in DevResults, even if you delete the source form submission from the SurveyCTO server console.
- If the review and correction workflow is turned on, only approved submissions will be sent to DevResults.
- DevResults does a good job assigning types to each column, but it is not perfect, so be sure to double-check each type, since it CANNOT be changed later.
- If you are encrypting your form, only fields that are explicitly marked as publishable can be exported to DevResults. When designing your form, it is a good idea to make sure that fields that do not contain personally identifiable information (PII) have a “yes” value for publishable.
Form design considerations by field type
Full, unabridged text will be exported from text fields. For example, if you entered the entire text of the first book of The Odyssey into a text field, the column in DevResults will have the full text from the first book of The Odyssey (tried and tested!). Of course, it is not recommended to enter TOO much text, since it will be displayed in DevResults all in one row, which can create very wide columns.
Tip: If you anticipate long text inputs, you can instead publish a calculate field that stores only the first X characters using the substr() function, or disallow very long string inputs in the first place by using a constraint expression that uses the string-length() function.
A phone number will often be read as a type “Number”, subtype “Whole” (even if it contains hyphens), so it is a good idea to change it to type “Other Text”. Otherwise, it will not accept later submissions that have non-number characters (such as hyphens) in the phone number.
It is also a good idea to set the other numeric identifiers to either “Unique ID” or “Other Text”, since if they are set to “Number”, then DevResults will display the number with unnecessary commas. For example, form version 1912121154 would be displayed as 1,912,121,154.
Other numbers will typically be recognized correctly, but it is still a good idea to double-check them. For example, make sure that decimal fields are not being classified as “Whole” (DevResults may determine the data type from what appears in the first row, and if that first row is a whole number, then it may assume the others are also whole numbers).
Date and time
When creating indicators in DevResults (see below), you need to have at least one “Date” type column (further reading: Data Source: Populate from a data table). For date and time values, DevResults only truly understands the “date” part when classifying data along the X-axis. When you import SurveyCTO data into DevResults, and set columns to be the “Date” type, it will actually drop the “time” part, leaving only the date in dd Mon yyyy format (e.g. 11 Dec 2019) (the time part will be dropped soon after you click “Create Data Table”). The "SubmissionDate", "starttime", and/or "endtime" fields make great “Date” type columns.
If you would still like to have a “time” column, go to your SurveyCTO form design, add a calculate field, and use an expression like this:
(Don’t use the "endtime" field for the time, since it is not calculated until after you exit the form; the "starttime" field would work, though.) When importing your data into DevResults, have that time column be imported as an “Other Text” data type.
Select_one and select_multiple fields
Only field values will be imported into DevResults, not select_one or select_multiple field choice labels. If you would like an actual label for a select_one field to be imported, create a separate calculate field that uses the jr:choice-name() function to get the label.
Select_multiple fields are a bit trickier, but the best option is usually to have a separate field for each select_multiple choice, and use the selected() function to give each field a value of 1 if the choice was selected, and 0 if it was not. That way, you have a separate column for each choice, and it is easy to create indicators for each choice.
GPS points, maps, and geography
As of writing this, GPS coordinates collected in SurveyCTO forms cannot be used for the “Geography” data type. However, you can certainly use the NAME of the location to pair with a location already in DevResults.
Attach SurveyCTO fields to DevResults Geographic locations
- In DevResults, define each location you need for your data. You can bulk-add a massive number of locations at once using an Excel spreadsheet. Check out the documentation on how to Define a Location to learn more.
- In your form, create a field whose value will be a location you defined in DevResults. For example, if one of the locations you defined in DevResults is “Cambridge”, make it so the value of the location field in your SurveyCTO form will be “Cambridge” when appropriate.
- When you import your data from SurveyCTO to DevResults, for the field with the location name, set its type to “Geography” and its subtype to “Location”.
- Define the rest of the table, and complete the import.
Set a location in a SurveyCTO form
You will want to make sure all possible locations in your SurveyCTO form are also in DevResults. A great way to do this is to create an Excel file to bulk-define locations in DevResults, and then save that file as a CSV file, and use it as an attached pre-load source for your SurveyCTO form. Since the data in both files will be the same, you do not have to worry about copying and pasting and confirming possibly dozens or even hundreds of locations.
Once the CSV file is attached to your form, you can add a select_one field that uses a search() expression to pull the locations as choices for the enumerator to select. You can even use a series of cascading select_one fields to have the enumerator pick the region, then the location. You can also have a text field where the enumerator enters the name of the location (or the first few letters), and then the next field uses the text entered as searchText to narrow down the list of locations in the select_one field.
You can also use a geopoint field and a series of repeated distance-between() expressions to automatically determine which location is closer. This method is far more complex and resource-intensive for your form, but if you greatly prefer this method, check out this sample form and this CSV file.
Pictures and other media
Media itself will not export to DevResults, but the columns for those media fields will have the URL to access that media. You can simply go to that URL to access the media file. It can only be accessed while logged into your server (if you are not logged in, it will prompt you for credentials).
Add them as “Other Text” type in DevResults.
Data in DevResults
Here, we will walk you through how to make your first dashboard tiles in DevResults. Be sure to check out the DevResults knowledge base for more complete documentation. We will go over three major steps:
- Add data to a data table
- Create an indicator
- Add a tile
Add data to a data table
Full documentation: Import Data From SurveyCTO
- On the top left, hover over Data, and click In Data Tables.
- On the bottom-right, click New Data Table.
- Enter a name for the table, select Import from SurveyCTO for the source, and click Create Data Table.
- You should be prompted to login to your SurveyCTO server. Enter the server’s name, the form ID you would like to use, and the other info.
- Confirm the data types are correct, and complete importing the data.
|Important: Data types and imported columns CANNOT be changed later without starting over. Be extra careful before confirming.|
Add an indicator
Full documentation: Define an Indicator
- Go to Data > Per Indicator.
- On the bottom-right, click New Indicator.
- Give the indicator a code and a name. The code is usually a short word, an abbreviation/initialism with numbers, numbers with dots, or just numbers.
- With the indicator created, on the Definition tab, in the Data Source module, for Data Source, select Populate from a data table.
- For the Data Table dropdown, select the table made up of SurveyCTO data.
- Complete other required info about the indicator, and allow the changes to save (it should save automatically, but you can also click the green Done button on the bottom-right).
Indicator minimum requirements:
This is what you need at the very least to create an indicator that can be used as a dashboard tile. There may be alerts about other missing info, but they are not necessarily required to create a basic tile.
- Data Source (select Populate from a data table, and select the table with the SurveyCTO form data)
- Calculation (including selecting at least one column from your data)
- Date Column
- Activities (fine to uncheck both boxes)
Other tips on completing an indicator:
- Most indicators require information on the geographic location, but you can get around this by setting the Calculation to Count Unique Sets.
- You can change the name and code of an indicator, but it may take a minute or so for the change to show up everywhere on your DevResults server.
- Changing the name of an indicator will not change the name of the tile, so that will have to be changed separately.
- Codes must be unique, but names do not have to be. Still, it is a good idea to have different names for different indicators.
Adding a tile
Full documentation: Define a Dashboard
- Go to Data > Dashboard.
- Go to the dashboard you would like to add a tile to.
- On the bottom-right, click the blue Add Tile button.
- Select the tile type, then the indicator. You can change the Title and the Color.
- When done, click the green Add Tile button.
- If there is no data, go to the settings of the tile (button is the small gear on the top-left of the tile), and under Display, for Reporting period, select Open now.
- If there is still no data, go back to the indicator, and open the Reports tab. Click the blue Recalculate button. When a graph appears on the right, it means the tile should start working as well.
- If there is still no data, check the indicator, and make sure all needed fields have been completed.
Updating an indicator/tile
Since DevResults does not store your password, you will need to send the command to update the data with new submissions.
- Go back to the data table with the SurveyCTO data.
- On the right, click the gear button.
- Click Refresh data.
- Re-enter the password to the SurveyCTO server and click Next.
- Confirm the new data is correct, and click the green Import data button.
Updating after a form update
You cannot add additional columns/fields to a SurveyCTO table in DevResults after it has first been created. If you add an additional field to your SurveyCTO form that you would like to use in DevResults, you have two choices:
- Select an existing column to put that data into. For example, if you change the name of a field from "field1" to "field2", you can set the data in the "field2" field to go to the 'field1' column.
- Start over with a new data table.
Do you have thoughts on this support article? We'd love to hear them! Feel free to fill out this feedback form.