Campaign Definition

• About
• Definition
  • Campaign
  • Survey Item
    • Message (currently not supported by ohmage mwf app)
    • Prompt
    • Repeatable Set (currently not supported by our Android app)
  • Prompt Types
  • Condition
  • Unused Elements
• Examples
• Notes

About

A campaign is a set of surveys. It is a high-level description of the overall data being collected. An example of a campaign would be a "Sleep Campaign" where someone is collecting information about users' sleep patterns. Another example would be of an "Fitness Campaign" where someone is collecting information about how frequently and/or intensely someone exercises.

A survey is a collection of survey items, which can either be a message, prompt, or repeatable set. It is a finer-grained assessment of a user regarding a specific event. In our "Sleep Campaign", an example survey could be the "Lay Down" survey that attempts to asses information about when a user laid down the night before, how long it took them to go to sleep, and/or what they did between laying down and going to sleep. In our "Fitness Campaign", an example survey could be the "Workout" survey that should be taken immediately after a workout, and would judge how long the workout took and/or what kind of exercises were performed.

A prompt is a single, specific inquiry about a user. A prompt is the finest-grained concept in the ohmage system and is used to determine a specific piece of information, the collection of which should fulfill the requirements of a survey, which, in turn, should fulfill the requirements of a campaign. Each prompt must have a specific type which defines how it is displayed to the user, what kind of data it collects, and how it is exported to be analyzed later. Example prompts from the "Lay Down" survey would be "What time do you remember laying down?" that would allow the user to input a specific time or "Select activities that you performed between laying down and going to sleep?" that would allow a user to choose between a series of predetermined activities and/or allow them to enter their own choices. Example prompts from the "Workout" survey would be "How long did the exercise last in minutes?" that would allow the user to enter a numeric value or "How did you feel after the workout?" that would allow the user to enter free-form text about their feelings after the workout. Prompts may be configured to be skippable, meaning that the user may skip the prompt and continue the survey.

A message is a brief chunk of text that is displayed to the user before a prompt. While messages can appear before other messages and/or after all prompts, it is discouraged to do so. There is a specific mechanism for displaying a message, such as a "Thank you" message, at the end of a survey and a series of messages may degrade the user experience.

A repeatable set is a collection of survey items and should be used when a series of prompts, with or without messages, may be displayed repeatedly. The last prompt in the series is the "escape" prompt which will determine if the set should be repeated again or should be terminated.

Any survey item whose condition is not met may be hidden, or "not displayed" in our terminology. Conditions are checked just before the survey item is displayed, and, if it is not satisfied, the survey item will not be displayed to the user.

Definition

A campaign is the container for the entire definition.

Campaign

A campaign is defined as the following:

Name	Description	Required
campaignUrn	Every campaign in the system must have a unique URN, and it is best practice to name this in such a way that it can easily be traced back to the creator, for example: "urn:campaign:text:describing:author:version"	Beginning with 2.16 it is now optional when creating a campaign if the `campaign_urn` parameter is given; however, when the definition is returned, this field will be present.
campaignName	A name to be displayed to the user for this campaign.	Yes.
surveys	This is a list of surveys where each survey is defined below. For XML, each survey must be surrounded by survey tags. Name Description Required id A unique identifier for this survey. Yes. title A name for the survey to be displayed to the user. Yes. description A user-friendly description of the survey. No. introText The text to be displayed when a survey is started. No. submitText The text to be displayed on the submit screen once a survey has been completed. Yes. anytime A boolean value indicating whether or not the survey may be taken at any time. If false, the survey may only be taken when a trigger has fired indicating that the user may now take the survey. Yes. contentList A list of survey items. Yes.	Yes.

Survey Item

A survey item can be any of the following.

Message

Name	Description	Required
id	A unique identifier for this message.	Yes.
messageText	The text to be displayed to the user.	Yes.
condition	The condition which determines if the message is displayed or not.	No.

Prompt

Name	Description	Required
id	A unique identifier for the prompt.	Yes.
displayLabel	The user-friendly name of this prompt used in visualizations.	Yes.
promptText	The text to display to the user when prompting them to respond.	Yes.
promptTextMarkdown	If provided this markdown will be rendered instead of the promptText. Markdown will only be parsed on 2.16.4 or later of the native android client. Only bold, italics and images are supported. If you use images, it is a good idea to test the campaign on multiple devices to make sure it is rendered correctly. Also images may look small on devices with a high dpi so using larger images is better (they will always be resized smaller so they fit in the width of the display).	No.
promptType	One of the prompt types.	Yes.
default	The default value for this prompt. This is type-dependent.	No.
condition	The condition which determines if the prompt is displayed or not.	No.
skippable	A boolean representing whether or not the prompt may be skipped.	Yes.
skipLabel	If skippable, this is the text of the button to use to skip the label.	Yes, if 'skippable' is true.
properties	A list of key, label, and, optionally, value duo/trios that define type-specific properties.	Yes.

Repeatable Set

Note that this feature is not supported in the native Android app.

Name	Description	Required
id	A unique identifier for the repeatable set.	Yes.
terminationQuestion	The text to be displayed to the user to allow them to choose to repeat the set.	Yes.
terminationTrueLabel	The text indicating that the user does not wish to repeat the set.	Yes.
terminationFalseLabel	The text indicating that the user does wish to repeat the set.	Yes.
terminationSkipEnabled	This determines whether or not the skip button will be shown on the termination prompt.	Yes.
terminationSkipLabel	The text for the termination button if it is enabled.	Yes, if 'terminationSkipEnabled' is true.
condition	The condition which determines if the repeatable set is displayed or not.	No.
prompts	A collection of survey items, except repeatable sets because there cannot be repeatable sets within repeatable sets.	Yes.

Prompt Types

Type name	Description	Output Format	Properties	Default
audio (only support in native ohmage)	An audio recording taken by the user at the time that the user was prompted.	A UUID that represents a distinct video clip. The video clip can be retrieve from the /app/audio/read URI.	key label maxMilliseconds Maximum number of milliseconds allowed for the video clip. maxFileSize Maximum file size allowed. Note: The maximum file size allowed is 300MB. If the audio clip exceeds the size limit, the prompt will fail and the app will ask the user to retake the audio. The failed audio clips will be saved in a local storage. Please note that uploading a large audio file may be slow and unreliable due to network outages or bad signal. Users may change their uploading configuration to use wifi only.	Not allowed.
file (2.17+)	A file attachment that is associated with survey response.	A UUID that represents a distinct file attachment. The file can be retrieve from the /app/media/read URI.	key label maxFileSize Maximum file size allowed.	Not allowed.
multi_choice	A multiple-choice answer from the user.	A JSONArray of keys representing the user's choices.	Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client. key label value A whole number value representing this choice's key. The label to show to the user for this choice. An arbitrarily assigned number representing the "value" of this choice.	A comma-separated list of keys where each key must be defined above.
multi_choice_custom	A multiple-choice answer from the user where the user may have created their own choice(s).	A JSONArray of keys representing the user's choices.	Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client. key label value A whole number value representing this choice's key. The label to show to the user for this choice. An arbitrarily assigned number representing the "value" of this choice.	A comma-separated list of keys where each key must be defined above. Because the keys for user-generated choices are random, it is not possible to make that a default choice.
number	A whole or decimal number.	A number value.	key label min The minimum value allowed for the prompt's response. max The maximum value allowed for the prompt's response. wholeNumber (optional) If set to false, decimal numbers will be allowed. This feature is only available in the native Android app version 2.16. By default, the value is set to true.	Any number that is greater than or equal to the min and less than or equal to the max.
photo	A photo taken by the user, generally at the time that the user was prompted.	A UUID that represents a distinct image. The contents of this image can then be retrieve from the /app/image/read URI.	key label maxDimension The maximum resolution of a single side of the image response. (The android client defaults to 800px if this is not defined). Setting this to `0` should result in clients not restricting size at all. maxFileSize Maximum file size allowed.	Not allowed.
remote_activity	This is used to call Android 'Activity's of applications that have already been installed. These activities must return a JSONObject with at least one key, 'score', whose value is a double. Other key-value pairs may be returned by the remote Activity. The result of this prompt should be a, possibly empty, JSONArray of these JSONObjects, where each JSONObject represents a single external call to the remote Activity.	The JSONArray of JSONObjects as generated by the prompt.	key label package The Android package to which the remote Activity belongs. activity The Android Activity within the package that should be called. action The action string to pass to that remote Activity. autolaunch A boolean representing whether or not the remote Activity should be launched the moment the prompt is displayed. True indicates that the Activity should be displayed as soon as the prompt is reached; false indicates that the prompt screen should be shown first, which contains a "Launch" button which can be used to launch the remote Activity. retries A positive, whole number that represents the number of times that the user can relaunch the Activity. They are always allowed to launch it once, so providing a 0 for this value will prevent them from launching it a second time. Likewise, providing a 1 for this value will allow the user to relaunch the remote Activity exactly once if they so choose. min_runs A positive, whole number that represents the minimum number of times that the user must launch the remote Activity. This value must be at least 1. input A string to pass to the remote Activity in its Bundle whose key is "input". This can be used to pass special parameters to the remote Activity in some serialized string format such as JSON. This property is optional and may be omitted.	Not allowed.
single_choice	A single-choice answer from the user.	An integer representing the key from the user's choice.	Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client. key label value A whole number value representing this choice's key. The label to show to the user for this choice. An arbitrarily assigned number representing the "value" of this choice.	A key from the list above.
single_choice_custom	A single-choice answer from the user where the user may have created their own choice(s).	An integer representing the key from the user's choice. If the choice was generated by the user, the key assigned to it will be random and will correlate with a dictionary sent along with the response when queried.	Each property should represent one choice, so there should be as many properties as their are choices. The label can be markdown, but it will only be parsed correctly on the 2.16.4 or later version of the native android client. key label value A whole number value representing this choice's key. The label to show to the user for this choice. An arbitrarily assigned number representing the "value" of this choice.	A key from the list above. Because the keys for user-generated choices are random, it is not possible to make that a default choice.
text	A free-form piece of text provided by the user.	A String.	key label min The minimum length of the text that is the prompt's response. max The maximum length of the text that is the prompt's response.	Any piece of text whose length is between the min and max value.
timestamp	A moment in time by a user down to the second granularity. the timestamp includes both date and time.	An ISO-8601 timestamp.	None.	Not allowed.
video (only support in native ohmage)	A video taken by the user at the time that the user was prompted.	A UUID that represents a distinct video clip. The video clip (mp4) can be retrieve from the /app/video/read URI.	key label maxSeconds Maximum length of the video clip. Android client defaults to: 180 seconds maxFileSize Maximum file size allowed. Note: If the video clip exceeds the size or time limit, the prompt will fail and the app will ask the user to retake the video. The failed video clips will be saved in a local storage. Please note that uploading a large video file may be slow and unreliable due to network outages or bad signal. Users may change their uploading configuration to use wifi only.	Not allowed.

Condition

A condition is defined as follows:

Object	Definition
condition	expression | "(" condition ")" | condition conjunction condition
conjunction	"and" | "or"
expression	id operator value
id	The ID of a prompt that is defined before this prompt in the same survey item container.
operator	== | != | &lt;(<) | &gt;(>) | &lt;=(<=) | &gt;=(>=)
value	Any combination of alphanumeric characters, the underscore "_" character, and the dash "-" character.

You may alter the grammar on your installation by editing the condition grammar, condition/condition-grammar.jj, and running the Ant build target "condition-grammar". This will generate the condition grammar with a small set of instructions on how to apply it to the existing code and why that is not done automatically.

Unused Elements

These are elements that the server allows to be uploaded as part of a campaign XML file, but they are not used in the "official" ohmage phone or front end applications. These elements are not included in the above documentation, but you may encounter example XML files with them (e.g., in the ohmageConfiguration repository).

• campaign/serverUrl
• survey/editSummary
• survey/showSummary
• repeatableSet
• prompt/displayType
• prompt/abbreviatedText

If you are writing your own ohmage client, you may add additional elements to the XML and the server will not reject the XML.

Examples

Here is an example XML for the "Sleep Campaign":

<?xml version="1.0" encoding="UTF-8"?>
<campaign>
  <campaignUrn>urn:campaign:example:Sleep:1</campaignUrn>
  <campaignName>Example Sleep Campaign</campaignName>
  
  <surveys>
    <survey>
      <id>LayDown</id>
      <title>Lay Down Survey</title>
      <description>This campaign assess when a user laid down for the night to go to bed.</description>
      <introText>Welcome to the Lay Down survey!</introText>
      <submitText>Thank you for taking the Lay Down survey!</submitText>
      <showSummary>true</showSummary>
      <summaryText>Here are the results from your survey.</summaryText>
      <editSummary>false</editSummary>
      <anytime>true</anytime>
      
      <contentList>
        <message>
          <id>BeforePromptsMessage</id>
          <messageText>This message should be the first thing you see in the survey.</messageText>
        </message>
        
        <prompt>
          <id>TimeUserLaidDown</id>
          <displayLabel>Time User Laid Down</displayLabel>
          <displayType>event</displayType>
          <promptText>Approximately, what time did you lay down last night?</promptText>
          <abbreviatedText>Time Laid Down</abbreviatedText>
          <promptType>timestamp</promptType>
          <skippable>true</skippable>
          <skipLabel>Skip</skipLabel>
        </prompt>
        
        <prompt>
          <id>ActivitiesPerformedBeforeSleep</id>
          <displayLabel>Activities Before Sleep</displayLabel>
          <displayType>measurement</displayType>
          <promptText>What activities did you perform before going to sleep?</promptText>
          <abbreviatedText>Activities Before Sleep</abbreviatedText>
          <promptType>multi_choice</promptType>
          <skippable>true</skippable>
          <skipLabel>Skip</skipLabel>
          
          <properties>
            <property>
              <key>0</key>
              <label>Read a book</label>
            </property>
            <property>
              <key>1</key>
              <label>Watched TV</label>
            </property>
            <property>
              <key>2</key>
              <label>Other</label>
            </property>
          </properties>
        </prompt>
      </contentList>
    </survey>
  </surveys>
</campaign>

Here is an example XML for the "Fitness Campaign":

<?xml version="1.0" encoding="UTF-8"?>
<campaign>
  <campaignUrn>urn:campaign:example:Fitness:1</campaignUrn>
  <campaignName>Example Fitness Campaign</campaignName>
  
  <surveys>
    <survey>
      <id>DailyExercise</id>
      <title>Daily Exercise</title>
      <description>This survey measures the amount of non-workout-specific exercise the user performed throughout the day.</description>
      <submitText>Keep at it!</submitText>
      <showSummary>false</showSummary>
      <!-- We only want the user to take this survey at the end of the day. -->
      <anytime>false</anytime>
      
      <contentList>
        <prompt>
          <id>NumHoursExercise</id>
          <displayLabel>Number of Hours Exercising</displayLabel>
          <displayType>count</displayType>
          <promptText>How many hours did you spend today performing any sort of exercise (walking, running, lifting, etc.)?</promptText>
          <abbreviatedText>Hours Exercising</abbreviatedText>
          <promptType>number</promptType>
          <default>2</default>
          <skippable>false</skippable>
          
          <properties>
            <property>
              <key>min</key>
              <label>0</label>
            </property>
            <property>
              <key>max</key>
              <label>24</label>
            </property>
          </properties>
        </prompt>
        
        <message>
          <id>NoExerciseMessage</id>
          <messageText>You should try your best to perform some level of casual activity throughout the day.</messageText>
          <condition>NumHoursExercise == 0</condition>
        </message>
        
        <prompt>
          <id>WithFriends</id>
          <displayLabel>With Friends</displayLabel>
          <displayType>category</displayType>
          <promptText>Did you do any of this exercise with friends?</promptText>
          <abbreviatedText>Exercise with Friends</abbreviatedText>
          <promptType>single_choice</promptType>
          <condition>NumHoursExercise &gt; 0</condition>
          <skippable>true</skippable>
          <skipLabel>Skip</skipLabel>
          
          <properties>
            <property>
              <key>0</key>
              <label>Yes</label>
            </property>
            <property>
              <key>1</key>
              <label>No</label>
            </property>
          </properties>
        </prompt>
        
        <prompt>
          <id>WhichFriends</id>
          <displayLabel>Which Friends</displayLabel>
          <displayType>category</displayType>
          <promptText>Which friends did you exercise with this time?</promptText>
          <abbreviatedText>Exercised With</abbreviatedText>
          <promptType>multi_choice_custom</promptType>
          <condition>(NumHoursExercise &gt; 0) and (WithFriends == 0)</condition>
          <skippable>true</skippable>
          <skipLabel>Skip</skipLabel>
          <!-- There are no properties because this is a custom-choice prompt,
               so the user is allowed to create their own responses which 
               should be retained each time this prompt is displayed. -->
        </prompt>
      </contentList>
    </survey>
    
    <survey>
      <id>Workout</id>
      <title>Intended Workout</title>
      <description>This survey measures a user's explicit workout.</description>
      <submitText>Great job!</submitText>
      <showSummary>false</showSummary>
      <!-- We want the user to take this right after a workout. -->
      <anytime>true</anytime>
      
      <contentList>
        <prompt>
          <id>TimeStarted</id>
          <displayLabel>Time Workout Began</displayLabel>
          <displayType>event</displayType>
          <promptText>Approximately what time did you begin working out?</promptText>
          <abbreviatedText>Time Workout Began</abbreviatedText>
          <promptType>timestamp</promptType>
          <skippable>false</skippable>
        </prompt>
        
        <message>
          <id>ExercisesPerformedMessage</id>
          <messageText>Now, add each of the exercises you performed one at a time.</messageText>
        </message>
        
        <repeatableSet>
          <id>ExercisesPerformedRepeatableSet</id>
          <terminationQuestion>Would you like to add another exercise?</terminationQuestion>
          <terminationTrueLabel>No</terminationTrueLabel>
          <terminationFalseLabel>Yes</terminationFalseLabel>
          <terminationSkipEnabled>false</terminationSkipEnabled>
          
          <prompts>
            <prompt>
              <id>ExercisesPerformed</id>
              <displayLabel>Exercise</displayLabel>
              <displayType>category</displayType>
              <promptText>Select an exercise that you performed.</promptText>
              <abbreviatedText>Exercise</abbreviatedText>
              <promptType>single_choice_custom</promptType>
              <skippable>false</skippable>
              
              <properties>
                <property>
                  <key>0</key>
                  <label>Pushups</label>
                </property>
                <property>
                  <key>1</key>
                  <label>Situps</label>
                </property>
                <property>
                  <key>2</key>
                  <label>Deadlifts</label>
                </property>
                <property>
                  <key>3</key>
                  <label>Curls</label>
                </property>
                <property>
                  <key>4</key>
                  <label>Squats</label>
                </property>
                <property>
                  <key>5</key>
                  <label>Jogging</label>
                </property>
                <property>
                  <key>6</key>
                  <label>Running</label>
                </property>
                <property>
                  <key>7</key>
                  <label>Aerobics</label>
                </property>
                <!-- Note that there is no other because this is a custom 
                     choice prompt, so the user may enter in their own. -->
              </properties>
            </prompt>
            
            <prompt>
              <id>NumReps</id>
              <displayLabel>Number of Repetitions</displayLabel>
              <displayType>count</displayType>
              <promptText>If applicable, how many repetitions did you perform?</promptText>
              <abbreviatedText>Number Repetitions</abbreviatedText>
              <promptType>number</promptType>
              <condition>
                (ExercisesPerformed != 5) and 
                (ExercisesPerformed != 6) and 
                (ExercisesPerformed != 7)
              </condition>
              <skippable>true</skippable>
              <skipLabel>N/A</skipLabel>
              
              <properties>
                <property>
                  <key>min</key>
                  <label>1</label>
                </property>
                <property>
                  <key>max</key>
                  <label>1000000</label>
                </property>
              </properties>
            </prompt>
            
            <prompt>
              <id>Distance</id>
              <displayLabel>Distance</displayLabel>
              <displayType>count</displayType>
              <promptText>If applicable, how far did you perform this exercise?</promptText>
              <abbreviatedText>Distance</abbreviatedText>
              <promptType>number</promptType>
              <condition>
                (ExercisesPerformed != 0) and 
                (ExercisesPerformed != 1) and 
                (ExercisesPerformed != 2) and 
                (ExercisesPerformed != 3) and 
                (ExercisesPerformed != 5)
              </condition>
              <skippable>true</skippable>
              <skipLabel>N/A</skipLabel>
              
              <properties>
                <property>
                  <key>min</key>
                  <label>0</label>
                </property>
                <property>
                  <key>max</key>
                  <label>1000000</label>
                </property>
              </properties>
            </prompt>
            
            <prompt>
              <id>DistanceUnit</id>
              <displayLabel>Distance Unit</displayLabel>
              <displayType>metadata</displayType>
              <promptText>What unit was that distance?</promptText>
              <abbreviatedText>Distance Unit</abbreviatedText>
              <promptType>multi_choice</promptType>
              <default>0</default>
              <condition>
                (Distance != NOT_DISPLAYED) and 
                (Distance != SKIPPED)
              </condition>
              <skippable>false</skippable>
              
              <properties>
                <property>
                  <key>0</key>
                  <label>Feet</label>
                  <value>1</value>
                </property>
                <property>
                  <key>1</key>
                  <label>Meters</label>
                  <value>3.2808399</value>
                </property>
                <property>
                  <key>2</key>
                  <label>Kilometers</label>
                  <value>3280.8399</value>
                </property>
                <property>
                  <key>3</key>
                  <label>Miles</label>
                  <value>5280</value>
                </property>
              </properties>
            </prompt>
          </prompts>
        </repeatableSet>
      </contentList>
    </survey>
  </surveys>
</campaign>

Notes

There are a few special consideration which are detailed below:

• While this specification is not bound by any language or format, we currently only support XML. This means that each item in the definition must be the tag name and its value must be the value of that tag. Examples should best illustrate this.
• No two surveys or prompts may have the same identifier, even if the two prompts are part of separate surveys. This includes a prompt and survey with the same ID.
• Identifiers may contain only alphanumeric characters and underscores "_".