Surveys: Question Actions

Question Actions Help Guide

Question Actions are automated tasks that execute when a participant answers a survey question. They allow you to save data, manage storylines, send notifications, and control participant flow based on responses.

Overview

Question Actions execute in the order you specify (use the up/down arrows to reorder). Multiple actions can be configured for a single question, and they will all execute after the participant submits their answer.

---

Available Actions

1. Save Answer

What it does: Saves the participant's answer to the current question as a variable that can be used later in surveys or storylines.

Parameters:

• Variable Name: The name you want to give this saved answer (e.g., "favorite_color", "baseline_weight")

Use cases:

• Store a participant's name, phone number, or other identifying information for later use
• Save baseline measurements to compare with follow-up responses
• Capture preference data to personalize future messages

Example: If Question 3 asks "What is your name?", you can save their answer as a variable called "participant_name" and then use %participant_name% in future messages.

Notes:

• The answer is saved after emoji decoding
• Variables are stored per participant and per microboard
• Use the variable in future messages with the syntax: %variable_name%

---

2. Increment Variable

What it does: Increases the value of an existing numeric variable by 1.

Parameters:

• Variable Name: The name of the variable to increment

Use cases:

• Track the number of times a participant has completed a survey
• Count how many times a specific answer has been given
• Maintain visit or session counters

Example: Create a variable called "survey_count" and increment it each time a participant completes a survey to track total completions.

Notes:

• If the variable doesn't exist or is empty, it will be treated as 0 and incremented to 1
• The variable must contain a numeric value to work properly
• Great for tracking engagement metrics

---

3. Save Variable

What it does: Saves a specific value (not the participant's answer) as a variable.

Parameters:

• Variable Name: The name for this variable
• Variable Value: The value to save (can include message markers like %user_id%, %phone%, etc.)

Use cases:

• Set flag variables to track participant status (e.g., "consent_given" = "yes")
• Store calculated values or fixed data points
• Set enrollment dates or milestone markers

Example: After a consent question, save a variable "enrollment_date" with value "today" to mark when the participant enrolled.

Notes:

• Unlike "Save Answer," this saves a value you specify, not the participant's response
• You can use message markers in the value field for dynamic content
• Perfect for setting status flags or configuration values

---

4. Save Date/Time

What it does: Saves a formatted date/time value as a variable, useful for storing timestamps in specific formats.

Parameters:

• Variable Name: The name for the date variable
• Date Value: The date/time to save (can use message markers or relative dates)
• Date Format: PHP date format string (e.g., "Y-m-d" for 2025-01-15, "m/d/Y" for 01/15/2025)

Use cases:

• Store enrollment dates in a specific format
• Calculate and save future appointment dates
• Track when specific milestones were reached

Example: Save the current date as "enrollment_date" using format "Y-m-d H:i:s" to get "2025-01-15 14:30:00"

Common Date Formats:

• Y-m-d → 2025-01-15
• m/d/Y → 01/15/2025
• Y-m-d H:i:s → 2025-01-15 14:30:00
• l, F j, Y → Monday, January 15, 2025

Notes:

• Uses PHP date() formatting conventions
• The date value can include message markers that will be replaced before formatting
• Timezone is based on the microboard's configured timezone

---

5. Email

What it does: Sends an email notification with custom subject and body content.

Parameters:

• EmailTo: Recipient email address(es) - use commas to separate multiple addresses
• Subject: Email subject line (can include message markers)
• Body: Email body text (can include message markers)

Use cases:

• Alert staff when a participant gives a critical answer
• Send notification emails to research coordinators
• Trigger alerts based on specific responses

Example: Send an email to "[e-mail]" with subject "New Enrollment" and body "Participant %firstname% %lastname% (ID: %ppt_id%) has enrolled on %enrollment_date%"

Available Message Markers:

• %user_id% - Participant's user ID
• %survey% - Survey name
• %question% - Question number
• %answer% - Participant's answer to this question
• Plus all standard user markers: %firstname%, %lastname%, %phone%, %ppt_id%, etc.

Notes:

• Multiple email addresses should be comma-separated
• Emails are sent from: Mosio Notification [e-mail]
• All email sends are logged in the system

---

6. Storyline Add/Update

What it does: Either adds a participant to a storyline (if not already enrolled) OR reactivates and updates the start date for an existing participant.

Parameters:

• Storyline Name: Select the storyline from the dropdown
• Start Date: The date to start (or restart) the storyline (use message markers or date strings)

Use cases:

• Enroll participants in a storyline based on survey answers
• Restart a storyline with a new start date
• Reactivate participants who previously completed a storyline

Example: After a consent question, add the participant to the "Daily Check-In" storyline starting "today"

Notes:

• This is a "smart" action that handles both new enrollments and updates
• If the participant is already in the storyline, they will be reactivated (state changed to ACTIVE) and the start date will be updated
• If they're not in the storyline, they will be added
• Use this when you want to ensure enrollment regardless of current status

---

7. Storyline Add

What it does: Adds a participant to a storyline ONLY if they are not already enrolled.

Parameters:

• Storyline Name: Select the storyline from the dropdown
• Start Date: The date to start the storyline

Use cases:

• Initial enrollment in a storyline
• Prevent duplicate enrollments
• One-time storyline additions based on survey responses

Example: Add a participant to "Onboarding Messages" storyline starting "tomorrow" after they complete registration.

Notes:

• Will NOT update or reactivate if the participant is already in the storyline
• Use "Storyline Add/Update" if you want to handle both new and existing participants
• More restrictive than Add/Update - prevents accidental re-enrollment

---

8. Storyline Complete

What it does: Marks a participant as "COMPLETE" in the specified storyline.

Parameters:

• Storyline Name: Select the storyline to mark complete

Use cases:

• Mark a participant as finished with a program based on survey response
• Graduate participants from one phase to another
• Complete storylines early based on participant answers

Example: If a participant answers "I want to stop daily messages," mark them complete in the "Daily Check-In" storyline.

Notes:

• Changes the participant's state to COMPLETE in the storyline
• The participant will no longer receive messages from this storyline
• Does not remove them from the storyline (use "Storyline Remove" for that)
• Completion status is tracked for reporting purposes

---

9. Storyline OptOut

What it does: Opts a participant out of the specified storyline.

Parameters:

• Storyline Name: Select the storyline to opt out from

Use cases:

• Allow participants to opt out of specific messaging programs
• Handle "STOP" or "unsubscribe" responses within surveys
• Remove participants from optional content streams

Example: If a participant answers "No" to "Do you want to continue receiving tips?", opt them out of the "Health Tips" storyline.

Notes:

• If the participant is not already in the storyline, they will be added first and then opted out (to maintain opt-out record)
• Different from "Complete" - OptOut indicates the participant chose to leave
• Opt-out status is tracked separately from completion for compliance and reporting

---

10. Storyline Remove

What it does: Completely removes (invalidates) a participant from a storyline.

Parameters:

• Storyline Name: Select the storyline to remove from

Use cases:

• Remove participants who should not have been enrolled
• Clean up test or erroneous enrollments
• Hard removal when complete/opt-out is not appropriate

Example: Remove a participant from a storyline if they indicate they were enrolled by mistake.

Notes:

• This invalidates the participant's state in the storyline
• More severe than Complete or OptOut - use sparingly
• The participant's historical data in the storyline may be affected
• Consider using Complete or OptOut instead for most use cases

---

11. Stop Participant

What it does: Completely stops all texting to a participant and opts them out of ALL storylines.

Parameters: None

Use cases:

• Handle global "STOP" requests
• Completely remove a participant from all messaging
• Compliance with opt-out requirements

Example: If a participant answers "STOP ALL" to a preferences question, use this action to stop all communication.

Notes:

• This is a GLOBAL action - it affects ALL storylines and messaging
• The participant will be opted out of every storyline they're enrolled in
• Use with caution - this cannot be easily undone
• This is the nuclear option for participant removal

---

12. Post To Text Chat

What it does: Posts a participant's answer to a specific question into the Text Chat system (Microboard).

Parameters:

• Answer to Question: Select which question's answer should be posted (by question number)

Use cases:

• Forward survey responses to staff for live chat follow-up
• Create tickets or questions in the Microboard system from survey answers
• Enable staff to respond to specific survey responses

Example: Post the answer from Question 5 (open-ended feedback) to Text Chat so staff can review and respond.

Notes:

• The answer is posted as if the participant sent it via Text Chat
• Staff can respond to the posted message in the Microboard interface
• Only posts if the answer is not empty
• Response type is marked as 'QuestionAction' in the system
• Useful for creating a bridge between automated surveys and live staff support

---

Best Practices

1. Order Matters: Actions execute in the order you specify. If Action B depends on data from Action A, make sure Action A is ordered first.

2. Use Descriptive Variable Names: Choose clear, meaningful names like "enrollment_date" or "baseline_weight" rather than "var1" or "x".

3. Test Your Actions: Use the "Send Survey" feature to test your question actions with sample data before deploying to participants.

4. Message Markers: Many fields support message markers like %firstname%, %lastname%, %phone%, %ppt_id%, %answer%, etc. Use these to personalize and automate your actions.

5. Personal Storylines: You can use "personal" as a storyline name to create participant-specific storylines that are automatically created as needed.

6. Combine Actions: You can use multiple actions on one question - for example, save the answer AND send an email AND add to a storyline.

7. Error Handling: Check your logs if actions aren't working as expected - the system logs all action execution with detailed debug information.