Skip to main content

Define Participant Variables

This guide explains how to assign custom data, or variables, to individual participants in your Avicenna study.

The Situation​

You need to store specific information for each participant that isn't collected through regular surveys. This information, set by you (the researcher), can then customize the participant's experience.

Common use cases include:

  • Assigning participants to different study arms (e.g., Control, Intervention).
  • Showing different content in surveys based on participant data.
  • Importing existing participant data from other sources into Avicenna.

Avicenna uses Researcher-Responded Surveys to manage these participant variables.

What to Do?​

Follow this recipe to define, set, and use participant variables:

  1. Create a new survey solely for variables. Name it clearly, e.g., Participant Variables.

    • Delete any default questions and triggering logics.
    • Do not add any triggering logic. This survey is only for researcher input.

    Survey for defining participant variables

  2. Add one question for each variable you need.

    • For variables with a single value (like study arm), use a single-answer question.
    • Example: Label the question Arm. Set the content to Participant's study arm?.
    • Define answer options (e.g., Control, Intervention). Consider making it Mandatory.
    • (For variables holding multiple values, you might use section loops. See Survey Flow Control.)

    "Participant Variables" survey's arm question

  3. Save and Publish the Participant Variables survey.

    • Ignore warnings about missing triggering logic. This is expected.

    Publishing the "Participant Variables" survey

  4. (Optional) Set up notifications for Participant Joined events.

    • This helps you promptly set variables for new participants.

    Notification template for "Participant Joined"

  5. Navigate to Activity Sessions when ready to set variables for a participant.

    • Click Submit New Session.
    • Select the Participant Variables survey and the target participant.
    • Click Next.

    Create a new session for the "Participant Variables" survey

  6. Fill out the survey with the correct variable values for that participant.

    • Submit the session.

    Respond to the "Participant Variables" survey

  7. Use the variables in your study design.

    • Reference them in activity Criteria to control logic.
    • Display them using Placeholders in surveys or notifications.

Pro Tips​

Editing Variables​

You have two options. Choose one and use it consistently.

  1. (Recommended) Find the participant's original Participant Variables session in Activity Sessions. Use filters or the Go to Join Time button. Click the session, then Edit Responses, modify, and submit. Edit the responses to the "Participant Variables" survey
  2. Submit a new Participant Variables session for the same participant. Avicenna always uses the latest session's data for criteria and placeholders. Older sessions remain but are inactive.

Bulk Setting​

For many participants, setting variables manually is slow. Contact support about bulk updates (e.g., via CSV). Fees may apply. Ensure the Participant Variables survey structure is defined first.