Creating Surveys for CareSuite

Survey building is a foundational requirement for operationalizing both the Contact and Care applications. Caresuite works with Kobotoolbox as a plug-in form builder to allow users

Caresuite Survey Building Guide

This guide provides comprehensive best practices and anti-patterns for building surveys in Caresuite

Survey Types in Caresuite

Caresuite supports four main types of surveys:

1. Intake Survey

Purpose: Data collection for case creation in a project
Scope: Project-level (each project has one intake survey)
Usage: Used when creating or updating cases
Storage: Survey responses are stored on the Case entity
Key Features: Required for all projects, used for case creation

2. Demographic Survey

Purpose: Profile-level demographic information collection
Scope: Organization-level (each organization has one demographic survey)
Usage: Used to collect and update profile demographics
Storage: Survey responses are stored on the Profile entity (profile.survey)
Key Features: Used for global profile search and demographic data collection

3. Follow-Up Survey

Purpose: Post-referral follow-up data collection
Scope: Project-level (optional, each project can have one follow-up survey)
Usage: Completed by case managers post service delivery
Storage: Survey responses stored as follow-up survey responses per referral

4. Additional Surveys

Purpose: Custom supplemental data collection
Scope: Project-level (multiple additional surveys per project are allowed)
Usage: Custom surveys for specific data collection needs
Storage: Survey responses stored in additionalSurveyResponse table
Key Features: Supports single and multiple responses per case per survey

Survey Format Requirements

File Format

File Type: XML (.xml extension)
MIME Type: text/xml
Maximum File Size: 10 MB (MAX_SURVEY_FILESIZE = 10 * 1024 * 1024)
Format Standard: XForms/ODK (Open Data Kit) format
Compatibility: Must be compatible with Kobo Toolbox format

XML Structure Requirements

Surveys must follow the XForms/ODK XML structure:

<?xml version="1.0"?>
<h:html xmlns="http://www.w3.org/2002/xforms" 
        xmlns:ev="http://www.w3.org/2001/xml-events" 
        xmlns:h="http://www.w3.org/1999/xhtml" 
        xmlns:jr="http://openrosa.org/javarosa" 
        xmlns:odk="http://www.opendatakit.org/xforms" 
        xmlns:orx="http://openrosa.org/xforms" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <h:head>
    <h:title>Survey Title</h:title>
    <model odk:xforms-version="1.0.0">
      <itext>
        <translation default="true()" lang="English (en)">
          <!-- Text translations for labels, hints, and option labels -->
        </translation>
      </itext>
      <instance>
        <!-- Form data structure -->
      </instance>
      <bind>
        <!-- Field bindings with types and validation -->
      </bind>
    </model>
  </h:head>
  <h:body>
    <!-- Form body with input fields -->
  </h:body>
</h:html>

Required Namespaces

http://www.w3.org/2002/xforms
http://www.w3.org/2001/xml-events
http://www.w3.org/1999/xhtml
http://openrosa.org/javarosa
http://www.opendatakit.org/xforms
http://openrosa.org/xforms
http://www.w3.org/2001/XMLSchema

Supported Data Types

For a more detailed breakdown of stat types see Supported Data Types

✅ Fully Supported Types

1. string (Text)

XML Type: type="string"
Usage: Text input fields, names, descriptions, notes
Query Operators: Equals, Not equals, Begins with, Ends with, Contains, Doesn't contain, Is empty, Is not empty, In, Not in

Example:

<bind nodeset="/form/field_name" type="string"/>
<input ref="/form/field_name">
  <label>Field Label</label>
</input>

2. int (Integer)

XML Type: type="int"
Usage: Whole numbers (age, counts, scores)
Query Operators: Equals, Not equals, Greater than, Less than

Example:

<bind nodeset="/form/caller_age" type="int"/>
<input ref="/form/caller_age">
  <label>Age</label>
</input>

3. date (Date)

XML Type: type="date"
Usage: Date fields (no time component)
Query Operators: Equals to, After, Before, Between
Format: ISO date format (YYYY-MM-DD)

Example:

<bind nodeset="/form/BTS_Date" type="date"/>
<input ref="/form/BTS_Date">
  <label>Date</label>
</input>

4. select1 (Single Select)

XML Type: type="string" with <select1> input
Usage: Single-choice dropdown/radio buttons
Query Operators: Equals, Not equals, Is empty, Is not empty

Example:

<bind nodeset="/form/gender" type="string"/>
<select1 ref="/form/gender">
  <label>What is your gender?</label>
  <item>
    <label>Female</label>
    <value>female</value>
  </item>
  <item>
    <label>Male</label>
    <value>male</value>
  </item>
</select1>

5. select (Multi-Select)

XML Type: type="string" with <select> input
Usage: Multiple-choice checkboxes/lists
Storage: Values stored as space-separated string (e.g., "value1 value2 value3")
Query Operators: Equals, Not equals, Is empty, Is not empty

Example:

<bind nodeset="/form/race" type="string"/>
<select ref="/form/race">
  <label>Select all that apply</label>
  <item>
    <label>Hispanic or Latino</label>
    <value>hispanic_or_latino</value>
  </item>
  <item>
    <label>White</label>
    <value>white</value>
  </item>
</select>

❌ Not Supported Types

The following data types are NOT supported and should be avoided:

time - Time-only fields (use string or separate date field)
dateTime - Date and time combined (use date type and store time separately if needed)
decimal - Decimal numbers (may work as int, but not explicitly supported)
boolean - Boolean values (use select1 with "yes"/"no" options instead)
geopoint - Geographic coordinates (store as separate lat/lng string or int fields)
geotrace - Geographic paths
geoshape - Geographic shapes/polygons
binary - File uploads (not supported in surveys)
barcode - Barcode scanning
intent - External application intents

Best Practices

1. Field Naming

✅ DO:

Use descriptive, lowercase field names with underscores: caller_age, first_time_caller, hear_about_211
Use consistent naming conventions throughout the survey
Keep field names concise but meaningful
Use snake_case for multi-word field names

❌ DON'T:

Use spaces in field names
Use special characters (except underscores)
Use camelCase (use snake_case instead)
Use extremely long field names

Example:

<!-- Good -->
<bind nodeset="/form/caller_frequency" type="string"/>

<!-- Bad -->
<bind nodeset="/form/CallerFrequency" type="string"/>
<bind nodeset="/form/caller frequency" type="string"/>

2. Field Organization with Groups

✅ DO:

Organize related fields using <group> elements
Use descriptive group names: group_AARP_careprovider, group_kick_it
Nest groups when necessary to create logical hierarchies

Example:

<bind nodeset="/form/group_callback_contact" relevant="..." required="false()"/>
<bind nodeset="/form/group_callback_contact/given_familyName" required="false()" type="string"/>
<bind nodeset="/form/group_callback_contact/telephone_001" required="false()" type="string"/>

3. Use itext for All Text Content

✅ DO:

Always use <itext> translations for labels, hints, and option labels
Reference text using jr:itext() function
Keep actual text content in the itext section, not inline

Example:

<itext>
  <translation default="true()" lang="English (en)">
    <text id="/form/gender:label">
      <value>What is your gender?</value>
    </text>
    <text id="/form/gender/hint">
      <value>Only ask if unsure</value>
    </text>
    <text id="/form/gender/female:label">
      <value>Female</value>
    </text>
  </translation>
</itext>

<select1 ref="/form/gender">
  <label ref="jr:itext('/form/gender:label')"/>
  <hint ref="jr:itext('/form/gender:hint')"/>
  <item>
    <label ref="jr:itext('/form/gender/female:label')"/>
    <value>female</value>
  </item>
</select1>

4. Conditional Logic (Relevant Attributes)

✅ DO:

Use relevant attributes for conditional field display
Use clear, readable XPath expressions
Test all conditional logic paths

Example:

<bind nodeset="/form/smoke_cigarettes" type="string"/>
<bind nodeset="/form/group_kick_it" 
      relevant="/form/smoke_cigarettes = 'yes'" 
      required="false()"/>

5. Required Fields

✅ DO:

Use required attributes with clear XPath conditions
Consider using conditional required logic when appropriate
Allow fields to be optional when data may not be available

Example:

<!-- Required when another field is empty -->
<bind nodeset="/form/gender" 
      required="/form/Incomplete_General_Screener = ''" 
      type="string"/>

<!-- Always optional -->
<bind nodeset="/form/other_race" 
      relevant="/form/race = 'other'" 
      required="false()" 
      type="string"/>

6. Validation and Constraints

✅ DO:

Use regex constraints for format validation (phone numbers, emails, etc.)
Provide clear constraint messages using jr:constraintMsg
Validate data at the field level when possible

Example:

<!-- Phone number validation -->
<bind nodeset="/form/telephone" 
      constraint="regex(.,'^[0-9]{10}$')" 
      jr:constraintMsg="Format: xxxxxxxxxx (Please do not add any formatting characters)" 
      required="false()" 
      type="string"/>

<!-- Email validation -->
<bind nodeset="/form/email" 
      constraint="regex(., '^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+[.][A-Za-z.]{2,}$')" 
      required="false()" 
      type="string"/>

7. Calculated Fields

✅ DO:

Use calculate attributes for computed values
Mark calculated fields as readonly="true()"
Include constraints that prevent manual modification if needed

Example:

<bind nodeset="/form/isolation_score" 
      calculate="/form/group_xe5xh95/score_calc" 
      constraint="regex(., /form/group_xe5xh95/score_calc)" 
      jr:constraintMsg="Please do not modify" 
      readonly="true()" 
      type="int"/>

8. Pre-loaded Values

✅ DO:

Use jr:preload for auto-populated values (timestamps, instance IDs)
Use appropriate preload parameters

Example:

<!-- Start timestamp -->
<bind jr:preload="timestamp" 
      jr:preloadParams="start" 
      nodeset="/form/start" 
      type="dateTime"/>

<!-- End timestamp -->
<bind jr:preload="timestamp" 
      jr:preloadParams="end" 
      nodeset="/form/end" 
      type="dateTime"/>

<!-- Instance ID -->
<bind jr:preload="uid" 
      nodeset="/form/meta/instanceID" 
      readonly="true()" 
      type="string"/>

9. Date Handling

✅ DO:

Use date() function for default date values
Set default dates using <setvalue> events when appropriate
Use date constraints for validation

Example:

<bind nodeset="/form/BTS_Date" 
      constraint=". = date('today()')" 
      relevant="..." 
      required="false()" 
      type="date"/>
<setvalue event="odk-instance-first-load" 
          ref="/form/BTS_Date" 
          value="today()"/>

10. Incomplete Data Handling

✅ DO:

Include options for handling incomplete data collection
Provide standard options: "Did Not Ask", "Declined to Answer", "Call Terminated Early", "Crisis Call - Did not ask"
Make fields conditionally required based on completion status

Example:

<select ref="/form/Incomplete_General_Screener">
  <label>Incomplete data collection</label>
  <item>
    <label>Did Not Ask</label>
    <value>did_not_ask</value>
  </item>
  <item>
    <label>Declined to Answer</label>
    <value>declined_to_answer</value>
  </item>
  <item>
    <label>Call Terminated Early</label>
    <value>call_terminated_early</value>
  </item>
</select>

<!-- Make other fields required only when not incomplete -->
<bind nodeset="/form/gender" 
      required="/form/Incomplete_General_Screener = ''" 
      type="string"/>

Common Anti-Patterns and Things to Avoid

1. ❌ Using Unsupported Data Types

Problem: Using data types that are not supported (dateTime, time, binary, etc.) will cause issues with data storage, querying, and display.

Solution:

Use date instead of dateTime (store time separately if needed)
Use string for boolean values with select1 options
Use string or separate int fields for geographic coordinates

2. ❌ Inconsistent Field Naming

Problem: Inconsistent naming (mixing camelCase, snake_case, spaces) makes surveys harder to maintain and query.

Solution:

Always use snake_case for field names
Establish and follow a naming convention document
Use descriptive names that indicate the field's purpose

3. ❌ Inline Text Instead of itext

Problem: Hardcoding text directly in field definitions makes translations difficult and maintenance harder.

Solution:

Always use <itext> translations
Reference text using jr:itext()
Keep all user-facing text in the itext section

4. ❌ Missing or Incorrect XML Namespaces

Problem: Missing or incorrect namespaces can cause parsing errors.

Solution:

Include all required namespaces in the <h:html> root element
Use the exact namespace URIs specified in the format requirements

5. ❌ Overly Complex Conditional Logic

Problem: Very complex relevant or required expressions are hard to maintain and debug.

Solution:

Break complex conditions into simpler, testable expressions
Use intermediate calculated fields when necessary
Document complex logic with comments (if XML comments are supported)

6. ❌ Missing Field Bindings

Problem: Fields defined in the body without corresponding <bind> statements may not work correctly.

Solution:

Always create a <bind> element for each field in the form body
Ensure nodeset paths match exactly between bind and input elements
Include appropriate type, required, and relevant attributes

7. ❌ Incorrect Multi-Select Value Storage

Problem: Expecting multi-select values to be stored as arrays when they're actually space-separated strings.

Solution:

Remember that <select> (multi-select) values are stored as space-separated strings
When querying, use appropriate string operators
When displaying, split the string to get individual values

Example:

// Multi-select value: "value1 value2 value3"
const selections = value.split(' '); // Split into array

8. ❌ File Size Exceeding Limits

Problem: Surveys exceeding 10 MB will be rejected during upload.

Solution:

Keep surveys focused and avoid unnecessary fields
Optimize itext content (avoid duplicate text)
Remove unused fields and groups
Consider splitting very large surveys into multiple additional surveys

9. ❌ Missing Validation for Critical Fields

Problem: Critical fields (phone numbers, emails, etc.) without validation can lead to poor data quality.

Solution:

Always add regex constraints for phone numbers, emails, postal codes
Provide clear, helpful constraint messages
Test validation with various valid and invalid inputs

10. ❌ Using dateTime Type for Dates

Problem: Using dateTime type is not supported and may cause errors.

Solution:

Always use type="date" for date fields
If time is needed, store it in a separate string field
Note: The system may accept dateTime in bind statements for metadata fields (like start/end timestamps), but use date for user-entered dates

11. ❌ Missing Incomplete Data Options

Problem: Not providing options for incomplete data collection makes it difficult to track why surveys are incomplete.

Solution:

Include an "Incomplete General Screener" or similar field at the beginning
Provide standard options for incomplete scenarios
Make other fields conditionally required based on completion status

12. ❌ Hardcoding Option Values

Problem: Using option labels as values makes data analysis difficult and error-prone.

Solution:

Always use lowercase, underscore-separated values
Keep labels human-readable but values consistent
Example: label="Female", value="female" (not "Female" as the value)

Problem: Flat field structures make surveys harder to navigate and understand.

Solution:

Group related fields using <group> elements
Create logical hierarchies (e.g., group_callback_contact/telephone_001)
Use descriptive group names

14. ❌ Missing Meta Instance ID

Problem: Not including a meta/instanceID field makes it difficult to track survey instances.

Solution:

Always include a meta section with instanceID
Use jr:preload="uid" to auto-generate unique IDs
Keep it readonly

Example:

<bind jr:preload="uid" 
      nodeset="/form/meta/instanceID" 
      readonly="true()" 
      type="string"/>

Field Naming Conventions

Recommended Naming Patterns

Use snake_case: caller_age, first_time_caller, hear_about_211
Be descriptive: caller_frequency not freq
Use prefixes for groups: group_AARP_careprovider, group_kick_it
Use suffixes for related fields: telephone_001, email_001, givenName, familyName
Keep names concise: Avoid extremely long names, but prioritize clarity

Examples from Production Surveys

✅ Good Examples:

Incomplete_General_Screener
caller_frequency
caller_age
BTS_Date
group_kick_it
group_callback_contact

❌ Avoid:

Mixed case without separation: callerAge, CallerFrequency
Spaces: caller age, first time caller
Special characters: caller-age, caller.age
Too generic: field1, data, value

Survey Structure Guidelines

1. Logical Flow

Start with screener/incomplete data options
Group related questions together
Use conditional logic to show/hide sections
End with optional metadata fields

2. Required vs Optional Fields

Make fields required only when absolutely necessary
Use conditional required logic when appropriate
Consider data collection scenarios (incomplete calls, declined answers)

3. Group Organization

Use groups to organize related fields
Create nested groups for sub-sections
Name groups descriptively

4. Field Ordering

Order fields logically (general to specific, required to optional)
Keep conditional fields near their parent fields
Group similar field types together when possible

Testing and Validation

Before Uploading

Validate XML Structure
- Check for well-formed XML
- Verify all namespaces are present
- Ensure all fields have corresponding bind statements
Test in Kobo Toolbox (Required)
- Build/test surveys in Kobo Toolbox first
- Verify all conditional logic works correctly
- Test with various data inputs
Review Field Names
- Ensure consistent naming convention
- Check for typos in nodeset paths
- Verify bind paths match input ref paths
Test Conditional Logic
- Test all relevant/required conditions
- Verify calculated fields work correctly
- Check pre-loaded values populate
Check File Size
- Ensure file is under 10 MB
- Optimize if necessary

After Uploading

Test Survey Flow
- Complete a test survey response
- Verify all fields appear/disappear correctly
- Check validation messages
Verify Data Storage
- Submit a test response
- Check that data is stored correctly
- Verify multi-select values are stored properly
Test Querying
- Test advanced search with survey fields
- Verify date queries work correctly
- Check select field filtering

Troubleshooting

Common Errors

1. "Only xml file is allowed"

Cause: File is not recognized as XML
Solution: Ensure file has .xml extension and correct MIME type (text/xml)

2. "Survey file must be provided"

Cause: No file was uploaded
Solution: Ensure file input has a valid file selected

3. "File size exceeds limit"

Cause: File is larger than 10 MB
Solution: Reduce file size by removing unused fields, optimizing text content, or splitting into multiple surveys

4. Survey fields not appearing in search

Cause: Field type may not be supported, or metadata not parsed correctly
Solution: Verify field uses supported type (string, int, date, select1, select)

5. Multi-select values not displaying correctly

Cause: Expecting array when values are space-separated strings
Solution: Split space-separated string when processing: value.split(' ')

6. Date fields not queryable

Cause: Using dateTime type instead of date
Solution: Change to type="date" in bind statement

Debugging Tips

Download Existing Survey
- Use the "Download Survey" button to see the current survey XML
- Compare with your new survey to identify differences
Check Survey Metadata
- View survey metadata in the project settings
- Verify all fields are listed with correct types
Test Incrementally
- Start with a simple survey and add complexity gradually
- Test after each major change
Review Logs
- Check server logs for XML parsing errors
- Look for specific field or namespace errors

Additional Resources

Kobo Toolbox: https://kobotoolbox.org (Recommended tool for building and testing surveys)
ODK XForms Specification: https://getodk.github.io/xforms-spec/
XForms Documentation: https://www.w3.org/TR/xforms/

Summary Checklist

When building a survey, ensure:

PreviousData Collection Surveys NextSupported Data Types

Last updated 1 month ago

Was this helpful?

Good evening

hashtagCaresuite Survey Building Guide

hashtagSurvey Types in Caresuite

hashtag1. Intake Survey

hashtag2. Demographic Survey

hashtag3. Follow-Up Survey

hashtag4. Additional Surveys

hashtagSurvey Format Requirements

hashtagFile Format

hashtagXML Structure Requirements

hashtagRequired Namespaces

hashtagSupported Data Types

hashtag✅ Fully Supported Types

hashtag❌ Not Supported Types

hashtagBest Practices

hashtag1. Field Naming

hashtag2. Field Organization with Groups

hashtag3. Use itext for All Text Content

hashtag4. Conditional Logic (Relevant Attributes)

hashtag5. Required Fields

hashtag6. Validation and Constraints

hashtag7. Calculated Fields

hashtag8. Pre-loaded Values

hashtag9. Date Handling

hashtag10. Incomplete Data Handling

hashtagCommon Anti-Patterns and Things to Avoid

hashtag1. ❌ Using Unsupported Data Types

hashtag2. ❌ Inconsistent Field Naming

hashtag3. ❌ Inline Text Instead of itext

hashtag4. ❌ Missing or Incorrect XML Namespaces

hashtag5. ❌ Overly Complex Conditional Logic

hashtag6. ❌ Missing Field Bindings

hashtag7. ❌ Incorrect Multi-Select Value Storage

hashtag8. ❌ File Size Exceeding Limits

hashtag9. ❌ Missing Validation for Critical Fields

hashtag10. ❌ Using dateTime Type for Dates

hashtag11. ❌ Missing Incomplete Data Options

hashtag12. ❌ Hardcoding Option Values

hashtag13. ❌ Not Using Groups for Related Fields

hashtag14. ❌ Missing Meta Instance ID

hashtagField Naming Conventions

hashtagRecommended Naming Patterns

hashtagExamples from Production Surveys

hashtagSurvey Structure Guidelines

hashtag1. Logical Flow

hashtag2. Required vs Optional Fields

hashtag3. Group Organization

hashtag4. Field Ordering

hashtagTesting and Validation

hashtagBefore Uploading

hashtagAfter Uploading

hashtagTroubleshooting

hashtagCommon Errors

hashtagDebugging Tips

hashtagAdditional Resources

hashtagSummary Checklist

Caresuite Survey Building Guide

Survey Types in Caresuite

1. Intake Survey

2. Demographic Survey

3. Follow-Up Survey

4. Additional Surveys

Survey Format Requirements

File Format

XML Structure Requirements

Required Namespaces

Supported Data Types

✅ Fully Supported Types

❌ Not Supported Types

Best Practices

1. Field Naming

2. Field Organization with Groups

3. Use itext for All Text Content

4. Conditional Logic (Relevant Attributes)

5. Required Fields

6. Validation and Constraints

7. Calculated Fields

8. Pre-loaded Values

9. Date Handling

10. Incomplete Data Handling

Common Anti-Patterns and Things to Avoid

1. ❌ Using Unsupported Data Types

2. ❌ Inconsistent Field Naming

3. ❌ Inline Text Instead of itext

4. ❌ Missing or Incorrect XML Namespaces

5. ❌ Overly Complex Conditional Logic

6. ❌ Missing Field Bindings

7. ❌ Incorrect Multi-Select Value Storage

8. ❌ File Size Exceeding Limits

9. ❌ Missing Validation for Critical Fields

10. ❌ Using dateTime Type for Dates

11. ❌ Missing Incomplete Data Options

12. ❌ Hardcoding Option Values

13. ❌ Not Using Groups for Related Fields

14. ❌ Missing Meta Instance ID

Field Naming Conventions

Recommended Naming Patterns

Examples from Production Surveys

Survey Structure Guidelines

1. Logical Flow

2. Required vs Optional Fields

3. Group Organization

4. Field Ordering

Testing and Validation

Before Uploading

After Uploading

Troubleshooting

Common Errors

Debugging Tips

Additional Resources

Summary Checklist