Understand a survey flow

Open Flow in the HTML report to see where each branch goes. Select a step to inspect its rules and questions, then follow a question link to the recorded answers. Definition-only questions still appear even if the CSV has no answer column for them.

Try the fictional flow first: three routes, a randomizer, and 24 fake responses.

Add flow information to a report

A QSF normally contains its survey flow. Build the entity files again with that definition, then generate the report:

uv run --extra cli --extra ui qualtrics build data/customer.csv \
  --qsf data/customer.qsf \
  --output output/customer/entities

uv run --extra cli --extra ui qualtrics report \
  --folder output/customer/entities \
  --output output/customer/report.html

An API survey-definition JSON can also be passed to --qsf. If your entity folder predates flow support, rebuild it from the original export and matching definition; regenerating HTML cannot restore missing flow or list-form block sections. Without a flow definition, the report says so rather than guessing from block order or responses.

Download the flow through the API

With API credentials configured, download the flow separately:

uv run --extra cli qualtrics api flow \
  --survey-id SV_EXAMPLE \
  --output data/customer-flow.json

uv run --extra cli --extra ui qualtrics build data/customer.csv \
  --qsf data/customer.qsf \
  --flow data/customer-flow.json \
  --output output/customer/entities

--flow supplies the flow for one CSV or response ZIP. Keep --qsf when available: it supplies block names, question wording, and choices. Use files from the same survey and definition revision. The API flow is a snapshot of the configured definition at download time; it may differ from the version used to collect older responses.

Use Python instead

import json
from pathlib import Path

from qualtrics import QualtricsClient, parse_survey, render_report

with QualtricsClient() as client:
    flow = client.survey_definitions.get_flow("SV_EXAMPLE")

Path("flow.json").write_text(json.dumps(flow), encoding="utf-8")
entities = parse_survey("responses.csv", "survey.qsf", flow_path="flow.json")
render_report(entities, "report.html")

The command uses Qualtrics' Get Flow endpoint and the client's existing read retries. It does not change the live survey.

Read the map

The canvas shows one survey at a time. Map and walkthrough survey chooses from the surveys in the report's current scope. Your selected card has a visible border; its details appear beside the map on a wide screen.

Control	Action
Drag the background or scroll over the canvas	Pan to another part of the route.
+ / −, or Ctrl/⌘ + scroll	Zoom in or out.
Fit	Show the entire route. Large surveys may need zooming back in to read individual cards.
Selected step	Return to the selected card at a readable scale.
Show outline	Read the configured steps as an expandable list. This is also the printing and no-JavaScript view.

Keyboard, touch, and map element details

You can Tab to a card and select it with the keyboard. With the canvas focused, arrow keys pan, +/− zoom, and Home fits the route. The report keeps survey content inside the HTML file; these controls work offline.

On a touch screen, swipe vertically to scroll the page. Select Move map to drag the route with your finger, then Done moving to return to page scrolling. Zoom buttons remain available in either mode.

Element	How to read it
Block	A set of questions encountered at this point in the survey.
Branch	Follow Condition met into its steps, or Condition not met past them. Routes rejoin before the next shared step unless the survey ended.
Group	Keep a set of steps together.
Randomizer	Choose the configured number of eligible children in a randomized order. Connections show alternatives; the walkthrough sets the actual order for your scenario.
Embedded data	Set a field used by later rules, or read a value supplied from outside the survey.
End of survey	Stop this route, including any later steps outside the current branch.
Advanced or unknown element	Its position remains visible; the walkthrough explains what cannot be evaluated locally.

Blocks can occur more than once. The map keeps each occurrence in place and shows source Flow IDs as secondary information. Search finds a block, question, condition, or embedded-data field and centers the matching card, switching surveys when necessary. Joining markers explain where a shared route continues; a survey ending has no outgoing connection.

Qualtrics documents branch continuation and randomizer behavior. In particular, randomizers selecting branches consider their conditions before selecting them.

Try a hypothetical walkthrough

Open What if, choose a survey and start the walkthrough. Enter hypothetical answers, continue through the blocks, and watch the map mark reached, skipped, and pending steps. The canvas follows the current step. Use Back to change an earlier answer or Reset to begin again. Changes replay the route and discard downstream answers that no longer belong to it. Select Step details to inspect a card without changing your hypothetical answers.

At a randomizer, explicitly choose the elements and their order for this scenario. This illustrates one possible outcome; it does not reproduce Qualtrics' allocation history or evenly-present counters.

This is an explanation of the supplied definition with hypothetical inputs. It is not an observed respondent path, a complete simulation of all Qualtrics behavior, or proof that a respondent saw a question. Response counts and the dashboard remain based on the recorded responses; walkthrough answers do not change them.

What the walkthrough can and cannot evaluate

The first version evaluates common selected/not-selected choice conditions, explicit AND/OR combinations, and embedded-data equality and numeric comparisons. It applies literal embedded-data assignments. Unsupported operators and missing values stay unknown. Advanced elements, quotas, authentication, web services, question display/skip logic, and loop settings may require an explicit scenario assumption before continuing. The report lists these assumptions. It never calls a web service or executes survey JavaScript.

Saved formats and sharing

The export folder's manifest.json stores each survey's flow definition under surveys[survey_id].flow_definition_json as a JSON object or null. Combined exports keep each flow under its own survey ID. The flow is not an entity table or a column in surveys or dim_surveys; entity and semantic exports in JSON, CSV, Parquet, and SQLite all write the same sidecar. The report runs offline and does not require a hosted service.

The flow adds survey wording, condition descriptions, and embedded-data values to the report. Share the HTML with the same care as the rest of the exported survey content.