14. Creating and Uploading an Options List for Cascading Selects Questions

Introduction

TaroWorks provides the Cascading Selects question type to give user a much easier way to handle situations such as the selection of a country, state/province and city where choices narrows down as you go down the levels. The choices are restricted to save field officers’ time and reduce errors. For more information on adding the question type, see here.

To take advantage of this new question type, the user must first import a comma separated value (.csv) file that define all the levels and possible choices. This document will describe the steps.

• Organizing Choices in the Levels
• How to create an Option List
• How to upload an Option List
• Troubleshooting

Organizing Choices in the Levels

First you must consider your use case in order to organize the choices in a simple and efficient manner. Here, we will use the example where we want to enter the country, state/province and city of a visitor and it is clear that creating the levels in this order narrows down the choices logically. (See image below.)

 

Therefore the first level is Country, second level is State/Province and third level is City. You are now ready to create an Options List.

 

How to Create an Options List

1. Open a spreadsheet program of your choice. (Microsoft Excel, Open Office Calc, Google Docs, etc.)
2. On the first row, starting from the leftmost cell, enter the labels for your levels across the row. (green box) Be sure to review notes on Tips and Tricks below.
   
3. In the following rows, enter the options. Make sure you enter a values for the levels (columns). See the picture below to see how the list should be constructed for the example above. Be sure to review notes on Tips and Tricks below.
4. Save this source file.
5. Then save again in comma separated value (.csv) format.
• NOTE: If possible, select UTF-8 encoding to preserve special characters and to avoid introducing errors. Please refer to your software’s documentation on how to do this.

Tips and Tricks

• The maximum number of columns is six.
• There must be a minimum of 2 rows in the csv file.
• Do NOT leave any cells blank.
• No two rows may be the same.
• Maximum 255 characters in a cell
• Duplicate rows will result in an error in the uploading step. You can use Excel’s Remove Duplicate button found in the Data tab. However this method does not tell you which rows have been removed so you could be missing a row that you want due to typos. We recommend you to double check.
• Avoid using commas in the cells as that is used to separate the values in the file unless you have experience in formatting csv.
• The maximum number of unique cells is 48,000. In the this example, there are 3 countries, 7 states/provinces and 15 cities - it totals to 25 unique cells.
• Text should be encoded in UTF-8 for multilingual support
  • Supported languages in CSV header: English, Spanish, French, Vietnamese, Portuguese, Indonesian, Swahili/Kiswahili
  • Unsupported languages in CSV header: Hindi, Khmer, Bengali
• If you plan to have multiple cascading select questions in the same form, the number of cells should be less than 10,000 to stay under salesforce.com processing limits. You may need to break up the form into multiple forms.
• Unexpected spaces can have undesirable effects, so use the TRIM function in excel to remove these prior to upload

 

How to Upload an Options List

1. In the Forms tab, click Cascading Select Manager.
   
2. You will see an unnamed list as shown below. Click New (red box).
   
3. You will then see the New Cascade Select screen shown below. In the Title field, enter a name for this Option List. You may also add a Description.
4. Click Choose File (green arrow) to open your computer’s file explorer. Select the file you have built as shown above. 
   
5. Click Save. You will be returned to the Cascading Select Manager screen, and your entry will be added with the Status of “Processing”. (red box)
   
6. Refresh the list after 5 to 30 seconds. If the file is formatted correctly, the status should be “Ready”. You can then use it in a Cascading Selects question.
• NOTE: If there is a formatting error, the status be set to “Invalid” and an email will be sent to you explaining the reason.
• NOTE: Clicking Edit will allow you to change the Title and Description. You should not manually change the status for any reason.
• NOTE: Clicking Del will allow you to delete an options list as long as its status is “Invalid” or “Ready” but used only in Closed forms.

Troubleshooting

• I received an error message, “The file is not in UTF-8 format and contains special characters. It must be converted to be able upload it.”
• Please see this article.
• If you are using a Mac computer, try to save the csv file as CSV for Windows.
• I received an error message, “Row 2 is a duplicate of row 1.”
• This means that in the csv you have uploaded, all the values in the first level (first column) are the same. This is not permitted, please edit your csv file and try again
• I received an error message, “There can only be 6 levels in a cascading select. The uploaded file has 7” (or more).
• Check to ensure you only have at most 6 columns maximum and there are no commas in the cells of your file.