Skip to content

Surveys

2.1 Survey List

The survey list is the main screen of the application, accessible via the menu Surveys > My Surveys. It displays all surveys belonging to the current user.

Default ordering: the list is sorted by last activity first (most recently edited or pipeline-advanced surveys at the top), with the creation date as a fallback for surveys that have not been touched since they were created. This way the surveys you are actively working on bubble to the top without needing manual reordering.

Status filter buttons: The toolbar at the top includes filter buttons to show surveys by status: - All: Shows all surveys regardless of status. - Draft: Shows only surveys in programming/draft status. - Open: Shows active and paused surveys. This is the default filter. - Closed: Shows finished surveys.

To work with a survey, select it by clicking the radio button next to its name. The selected survey becomes the 'Working Survey' and all subsequent operations are executed against it.

Actions available from the toolbar:

The top navigation bar provides quick-access buttons organized into groups. These buttons operate on the currently selected (working) survey:

  • Home (house icon): Returns to the survey list.
  • New Survey (clipboard icon): Creates a new survey.
  • Edit Survey (pencil icon): Opens the settings page for the selected survey. Equivalent to clicking the survey name in the breadcrumb.
  • List Questions (question mark icon): Opens the question list for the selected survey.
  • New Question (plus icon): Opens the form to add a new question to the selected survey.
  • Edit Question (pencil icon): Opens the configuration form for the currently selected question.
  • Preview (play icon): Tests the survey as a respondent would see it, in admin mode. No response data is saved. A confirmation dialog appears before opening the preview in a new window.
  • Preview All (list icon): Displays all survey questions on a single page. Useful for reviewing the complete survey at a glance.
  • Export to PDF (file icon): Provides instructions for exporting the survey to PDF using a browser extension (PDF Mage) or the browser's built-in print function. Opens the "Preview All" view for printing.
  • Delete (trash icon): Deletes the selected survey and all associated data. A confirmation dialog is shown before deletion.

Additionally, the left-side menu under Surveys provides access to: - Duplicate: Creates a copy of the selected survey, including all questions, steps, rules, and configuration. Two notes on the duplicate's lifecycle: (a) the pipeline state is reset to Brief, so the copy walks the lifecycle from scratch — review, audit, validation and history from the parent are not inherited; (b) every share grant from the parent is cloned, so the same collaborators automatically get access to the duplicate. Useful for creating language variants, backup copies, or templates based on an existing survey. - Detail: Displays detailed information about the selected survey. - Reset Counters: Resets the response counters for the selected survey.

2.2 Creating a Survey

To create a new survey, click the New button in the toolbar (Section 2 shortcuts). Enter the survey name, select the language, and click Save. The survey will be created in Draft status and you can immediately begin adding questions.

2.3 Configuration of Survey

This section allows you to configure important features of the survey. Once the survey has been selected, you can access this page through the "Edit" button in Section 2 (shortcut buttons) or by clicking the survey title in the breadcrumb.

The settings page is organized into the following sections:

2.3.1 Survey Name

  • Name: The name of the survey as it appears in the survey list.
  • Survey type: Displays the type of survey (normal, game, etc.). Read-only.

2.3.2 Objective

  • Title: The title or objective of the survey (internal use, not shown to respondents).
  • Description: A description of the survey (internal use).

2.3.3 Properties

  • Select language: The language of the survey interface (Spanish, English, French, Portuguese, Italian, German, Swedish, Polish, Catalan, Galician, Basque, Greek, Croatian, Montenegrin). The Translate automatically button uses Google AI to translate all survey content to the selected language.
  • Select style: The visual theme of the survey (Orange, Green, Blue). Determines colors for buttons, borders, and highlights.
  • Apply filters: Whether to apply personalized quota filters. Options: "Do not apply" or "Personalized filters." See Section 4 - Filters and Quotas for details.
  • Minimum time (seconds): Minimum time required to complete the survey. Respondents finishing faster are quality-terminated. Set to 0 to disable.
  • Maximum time (seconds): Maximum time allowed to complete the survey. Respondents exceeding this limit are removed on their next step. Set to 0 to disable.

2.3.4 Hybrid Surveys

  • Interviewer telephones: Phone numbers of interviewers for hybrid (paper + digital) surveys. Separate multiple numbers with commas. Include the country code (e.g., +34).

2.3.5 Options

  • Same computer control (cookies): Prevents the same browser from completing the survey more than once using a cookie. Acts as a first-line deterrent against repeat submissions from the same device. For stricter enforcement across devices or research panels, use Cross-Panel Deduplication (fingerprint) instead — the two options are mutually exclusive.
  • Progress bar: Displays a progress bar at the top of the survey showing the respondent's progress through the steps.
  • Back button: Controls the "Back" button that allows respondents to return to the previous step. This setting acts as a bulk toggle: when enabled, all steps are set to show the back button; when disabled, all steps are set to hide it. After toggling, you can fine-tune which individual steps show the back button in the Survey Structure form (see section 2.4.5).
  • Save & Resume Later: Allows respondents to save their progress and return later to complete the survey. Requires a tree structure. Based on a browser cookie.
  • Show banner: Displays the survey logo/banner at the top of each page.
  • Visualize question identifier: Displays the question identifier (e.g., P1, P2) alongside each question. Useful during survey development and testing.
  • Quality Survey: Enables quality checks for the survey, tracking response quality metrics.
  • Force edit (admin override): Visible to tickStat staff (superadmin) only. Editing is normally derived automatically from the pipeline stage and the user's role — see 2.12.10 Edit Permissions by Stage. This toggle is an emergency override that re-enables editing for tickStat staff in the locked-down stages (Pilot, Validation, Field, Closed) when a fix has to be made on a survey that is already in the field. Use it sparingly: changing an open survey can invalidate respondents already in flight. The override has no effect for researchers — their permissions are governed solely by the matrix.
  • Survey Status: The current status of the survey: Programming (Draft), Open, Paused, or Closed. See Section 2.6 - Survey Status Management for details.
  • Change Administrator (superadmin only): Transfer survey ownership to a different investigator.
  • Email subject: The subject line used for survey-related emails (e.g., save & resume notifications).
  • Scenario: Link the survey to a specific game scenario (for game experiments).
  • Location: Link the survey to a geographic location.
  • Target people (quota): Maximum number of completed responses. When reached, the survey closes automatically and no new respondents are accepted. Set to 0 for unlimited.
  • Honorarium: The compensation amount for respondents (informational, displayed in the survey list).
  • Average survey time (minutes): Expected average completion time (informational, displayed in the survey list).

2.3.6 Exit URLs

These URLs determine where respondents are redirected when they exit the survey for various reasons:

  • Quota Full: Redirects respondents when all quotas are filled and no more completions are needed.
  • Early Screen Out: Redirects respondents who do not meet the screening criteria.
  • Quality Terminate: Redirects respondents who fail quality checks (minimum time, maximum time, careless responses).
  • Complete (Done): Redirects respondents after successfully completing the survey.
  • Already Done: Redirects respondents who have already completed the survey and attempt to access it again.
  • URL Frame: URL used when the survey is embedded in an iframe on a client website.

Default TickStat redirect URLs are provided, but when distributing through research panels (Netquest, Cint, etc.), replace them with the panel's redirect URLs.

2.3.7 Entrance Filter Settings

  • Websocket: Enables WebSocket communication for real-time features (required for game experiments).
  • Allow access from mobile devices: Permits respondents to access the survey from mobile phones.
  • Allow access to tablets: Permits respondents to access the survey from tablets.
  • Geolocation: Requests the respondent's geographic location when they access the survey.
  • Token request by email: Enables email-based token verification. Used with the Auth Filter question type to verify respondent identity and prevent cross-panel fraud. See Section 3.14 - AntiSpam.
  • Customized Groovy Scripts: Enables Groovy script execution in survey steps for advanced validation and custom conditions. This flag is auto-activated when you save a Groovy script (via Edit · Validate step) and acts as a runtime guard; the code never turns it off, so only an administrator should switch it off manually here. See Section 7.1 - Including Java Code.
  • Cross-Panel Deduplication (Browser Fingerprint): Detects respondents attempting the survey from multiple research panels using browser fingerprinting. See Section 8.2 - Cross-Panel Deduplication. Mutually exclusive with Same Computer Control.

2.3.8 Pre-Survey Verification

2.4 Survey Structure

2.4.1 Linear

In the linear structure, all questions are presented in sequential order. The user progresses through all questions one by one or in groups (steps).

To configure the linear structure, go to the menu Edit::Steps. Here you define the steps that compose the survey. Each step can contain one or more questions.

The configuration is done through a text area where you enter the steps. Each line represents a step, and questions within a step are separated by commas. For example:

P1
P2,P3
P4,P5,P6

This means: - Step 1: Question P1 - Step 2: Questions P2 and P3 - Step 3: Questions P4, P5, and P6

2.4.2 Tree Structure

In the tree structure, the survey flow is determined by the user's answers. Depending on their responses, the user is directed to different steps.

To configure the tree structure, first define the steps (as in the linear structure) and then define the rules that determine the flow.

The rules are configured in the menu Edit::Rules. Each rule has:

  • Origin step: The step from which the rule originates.
  • Destination step: The step the user is directed to if the condition is met.
  • Condition: The condition that must be satisfied to proceed from the origin to the destination.

2.4.2.1 Definition of Conditions

Conditions follow a specific syntax. Below are the available condition types:

  • $P1_1: The user selected option 1 of question P1 (for radio/single-option questions).
  • $P1_2: The user selected option 2 of question P1.
  • $P1_1_1: In a matrix question, the user selected option 1 for the first row of question P1.
  • $P1_check_1: In a checkbox/multiple-selection question, the user selected option 1.
  • $P1_check_1_Sel: In a checkbox/multiple-selection question, the user selected option 1 (alternative syntax).
  • $P1_check_1_NoSel: In a checkbox/multiple-selection question, the user did NOT select option 1.
  • $P42_statusQuo: In a multiple choice question, the user answered Status Quo for all presented questions. P42 refers to the parent question.
  • $P42_0statusQuo: In a multiple choice / simple choice question, the user answered Status Quo for NONE of the presented questions. P42 refers to the parent question.
  • $P42_noAnswer: The user did not answer an optional question.
  • $P42_Answer: The user answered a question.
  • $PX_HayPrograma: In a "Multiple continuous choice" question, the user did not click the "No hay programa" button.
  • $PX_Val_0: In a "Line input" question, the user entered the value 0. The "Type of data" setting must be set to numeric.
  • $PX_Val_NA: The user did not answer an optional question. Currently implemented only for line input questions, but it can be extended to other question types. Please contact us if you need this condition for a different question type.
  • $Juego_Finished: The game associated with the survey did not finish correctly.
  • Logical operators:
  • || for logical OR
  • && for logical AND

Random Paths in Survey Structure

Note the origin and destination of the rules. As shown, there are two rules: one goes from screen 1 to screen 2, and the other goes from screen 1 to screen 3.

2.4.3 Visualization in Two Columns

To display questions in a two-column layout, follow these rules:

  • In the steps configuration, define the questions that should appear in two columns. For example, if a step has three questions and the first two should be displayed in two columns while the third occupies the full width, configure them as P1, P2, P3.
  • Then, edit the configuration of the first question (the one in the left column) and set its width to 30%, 50%, or 66%. Do not change the configuration of the second question.

2.4.4 Upload Steps and Rules from Excel

For complex survey structures, it may be easier to define the steps and rules in Excel and then upload them through the user interface.

Steps to follow: An example Excel file with a tree structure is available at this link.

  1. Create an Excel file with the format shown in the link, containing 2 tabs: one for steps and one for rules.
  2. Populate the steps tab with Column A and Column B. Column C is a formula based on the first two columns and contains the information to paste into the TickStat platform.
  3. Populate the rules tab:
  4. Column A: Step ID (an incremental formula).
  5. Column B: Initial step, using the step identifier from the first tab.
  6. Column C: Final step, using the step identifier from the first tab.
  7. Column D: Condition to apply for the transition from the initial step to the final step.
  8. Column E: Formula that builds the information to paste into the TickStat platform, based on the previous columns.

We recommend drawing the tree structure on paper based on the steps tab before populating the rules tab.

Next step:

Copy the information from Column C in the steps tab and paste it into the form in the TickStat platform via the menu Edit::Pasos Manual.

Copy the information from Column E in the rules tab and paste it into the form in the TickStat platform via the menu Edit::Reglas Manual.

After testing the survey navigation, if any rules were not applied correctly, return to the Excel file, add new rules as needed, and paste the updated rules information again.

2.4.5 Per-Step Back Button

By default, when the "Back button" option is enabled in the survey settings (see section 2.3.5), the back button is shown on every step (except the first one). However, you can control the back button visibility on a per-step basis.

In the Survey Structure form (Edit::Steps), each step row has a Back checkbox column. When checked, the back button will be displayed on that step; when unchecked, it will be hidden.

How the global setting and per-step setting work together:

  • When you enable the global "Back button" in the survey settings, all steps are set to show the back button. You can then uncheck specific steps where you want to hide it.
  • When you disable the global "Back button", all steps are set to hide the back button. You can then check specific steps where you still want to show it.
  • The global setting only affects the steps when its value changes. Once set, each step's back button can be individually configured without being overridden by saving the survey settings again.

This is useful when certain steps contain irreversible actions or time-sensitive content where going back would be inappropriate, while still allowing navigation on other steps.

2.5 Survey Sharing Between Investigators

Surveys can be shared between investigators to enable collaborative work.

2.5.1 How to Share

Go to menu Edit > Share Survey. Enter the email address of the investigator you want to share the survey with.

2.5.2 Roles

  • Builder: The original creator of the survey. Has full editing permissions.
  • Admin: An investigator who received a shared survey. Can manage the survey but cannot transfer ownership.

2.5.3 Concurrent Edit Protection (Optimistic Locking)

When two investigators edit the same survey simultaneously, the system detects the conflict. The second person to save will see a warning indicating that the survey was modified by another user. They can then reload the survey and re-apply their changes.

2.6 Survey Status Management

2.6.1 Extended Survey Statuses

Surveys have four statuses:

Status Description
Draft (programacion) Survey is being built. Not accessible to respondents.
Open (abierta) Survey is active and accepting responses.
Paused (pausada) Survey is temporarily stopped. No new responses accepted.
Closed (cerrada) Survey is finished.

Status is managed from Settings > Options section.

For a finer-grained view of where the experiment is in its lifecycle (brief, design, audit, pilot, validation, field, closure), see 2.12 Experiment Pipeline. The pipeline is layered on top of these statuses: it does not replace them, and it automatically flips the status to Open when entering the Pilot stage (so respondents can access the survey) and to Closed when entering the Closed stage.

2.6.2 Survey List Filters

The survey listing page includes filter buttons: All, Draft, Open, Closed. The default filter is "Open," which shows active and paused surveys.

2.6.3 Edit Permissions

Whether a survey can be edited is derived automatically from the pipeline stage and the user's role — there is no manual lock toggle. Researchers can edit during the design phases (Brief through Review); tickStat staff can edit through Final; once the survey enters Pilot, Validation, Field or Closed, editing is locked for everyone except tickStat staff acting through the Force edit override in Settings.

The full matrix and the override are documented in 2.12.10 Edit Permissions by Stage.

2.7 Survey Version History and Restore

Every time a survey is saved, a version is automatically created. Researchers can view the change history, restore any previous version, and compare any two versions side by side with an AI-generated explanation in plain English of what changed.

2.7.1 Accessing Version History

Open the Detail screen for the selected survey and scroll to the Version History panel. The table lists, from newest to oldest:

  • Current (live) — the XML currently in production for this survey, tagged with a blue Live badge. This synthetic row lets you compare any historical snapshot against the version respondents are seeing right now.
  • Daily snapshots — one row per day, taken automatically. The most recent snapshot carries a Latest backup badge.
  • VISTO baseline — the snapshot taken at the moment the researcher signed off the design during the Review pipeline stage. Marked with a green VISTO baseline badge so it is easy to spot the "approved" version and check what has changed against it.

Each row shows the version date, the pipeline stage the survey was in at the time, and an action column with the Restore button.

2.7.2 Restoring a Version

Click Restore on any snapshot row. A backup of the current version is taken first, so the restore is reversible — the current state is never lost. The Restore button is disabled when the survey is locked for editing (pipeline stages Pilot, Validation, Field or Closed); tickStat staff can still restore via the Force edit override (see Section 2.12.10).

2.7.3 Comparing Two Versions (AI-generated change explanation)

Tick the Pick checkbox on exactly two rows of the version table and click Compare selected versions. The system computes a normalised diff between the two XML definitions (semantically equivalent reorderings are collapsed so they are not reported as changes) and asks the AI model to produce a markdown explanation of what changed, written in natural language with bullets and bold leads — for example:

  • Added question P12 (radio). New screening question on consumption frequency, placed in Step 3 just before the choice block.
  • Modified question P4. Option list extended from 5 to 7 levels; minimum/maximum labels updated.
  • Removed step 6. Demographic block was moved into step 7; rules updated accordingly.

This is much easier to scan than reading a raw XML diff and answers the typical reviewer question — "what's different between the version we approved and what is in field right now?" — in seconds.

Defaults and shortcuts:

  • When the survey has a recorded VISTO sign-off, that snapshot is pre-selected as the left anchor. One click on the live row plus Compare is enough to see "what has happened since researcher approval".
  • The Compare button is only enabled when exactly two snapshots are selected.
  • Identical XMLs (no real changes between the two versions) are detected before calling the AI — the explanation reads "no substantive changes" and no model tokens are spent.
  • Snapshot-vs-snapshot comparisons are cached: opening the same pair again returns instantly. Live-version comparisons are not cached, because the live XML can change between calls.

What the AI sees. Only the unified diff of the two survey definitions is sent to the model — never the responses, the respondent data, or any personal information. The original XMLs on disk are not modified by the comparison.

2.8 Survey Distribution

2.8.1 QR

The survey can be distributed through a QR code generated from the platform.

The survey can be distributed through a link that can be embedded on any web page.

2.8.3 Redirects

By default, every survey has the following redirect URLs, which can be configured in the survey settings:

  • Quality Check: The user is removed due to poor quality (e.g., completing the survey below the minimum time).
  • Early Screen Out: The user does not meet the criteria to participate in the survey.
  • Quota complete: The quota is full and no additional completions are needed for the given criteria.
  • Done: The survey was completed successfully.

By default, TickStat redirects are used. However, when respondents are invited through a panel, the panel's redirect URLs should be used instead. To revert to the default TickStat redirects, configure the following URLs:

  • Quality Check: https://app.tickstat.com/surveys/resources/messages/qualityTerminate
  • Early Screen Out: https://app.tickstat.com/surveys/resources/messages/earlyScreenOut
  • Quota complete: https://app.tickstat.com/surveys/resources/messages/quotaFull
  • Done: https://app.tickstat.com/surveys/resources/messages/complete

Important — review your redirect URLs. Surveys are now hosted on app.tickstat.com. The host must match the host respondents enter through, otherwise the browser blocks the final redirect as a cross-origin request and the respondent sees an error instead of the completion page. If your survey was configured before this change and still points to www.tickstat.com/surveys/..., edit each of the four redirect URLs above and replace www.tickstat.com with app.tickstat.com. The same applies to any custom redirect URL you provide (e.g. a panel callback URL): it must use app.tickstat.com, not www.tickstat.com.

2.9 Save Survey Functionality

This functionality allows respondents to abandon a survey and resume it later. The admin user activates the "Save & Resume Later" checkbox in the survey edit form.

This functionality requires a tree structure. If the survey does not have a tree structure, the application will not allow this feature to be enabled.

Important considerations when using this functionality in admin mode:

  1. When previewing the survey in admin mode, the save and resume functionality is not active, as admin mode is used for testing the survey before launch.
  2. This functionality relies on a cookie sent to the user's browser, which is removed upon survey completion. This means the feature only works from the same browser where the user started the survey.

2.10 Style

In the Style menu section, you can upload a logo image and specify its URL. The logo height must be 80px; the width can be adjusted by the researcher as needed.

You can also configure the URL that opens when the user clicks the logo. The URL will open in a new browser tab.

2.11 How to Translate the Survey

In some cases, a single survey may need to be available in multiple languages. TickStat facilitates translation through the following manual process:

  • Download an Excel report of the original survey configuration.
  • Translate the items in the Excel file.
  • Duplicate the survey.
  • Upload the Excel report with the translated items to the duplicated survey.

Additionally, TickStat now provides automatic translation to the 14 languages supported by the platform.

Each of these steps is explained in detail below.

2.11.1 Download an Excel Report of the Configuration for the Original Survey

To download the report containing all question text for the survey, go to the menu option Results::Reports and click the option to download this report.

The report contains 4 columns. The first 3 columns are tags that allow the application to identify the translated text. Column 4 contains the text that needs to be translated.

2.11.2 Translation of the Items in the Excel

The translator must translate the text in Column 4 (LiteralToTranslate) into Column 5 (LiteralTranslated).

In some cases, the text to translate contains code that must not be modified. For example:

Abundance (count per hectare/catches per unit effort) of SP 1
$encuesta.getPregunta("P118").getAnswerFromUserMatrixNumeric(1)

The translator must leave $encuesta.getPregunta("P118").getAnswerFromUserMatrixNumeric(1) unchanged, as it is a configuration expression that must not be translated.

Similarly, text may contain HTML code. Only the visible text should be translated; the HTML markup must remain unchanged. For example:

Original (English):

<div class="intro">
    <p>This survey has been developed in the frame of</p>
    <p>We estimate</p>
    <p>All information collected</p>
    <ul>
        <li>By default, it will be confidential</li>
        <li>If you agree and confirm</li>
    </ul>
    <p>Thank you</p>
    <p>If you have any further questions</p>
</div>

Translated (Spanish):

<div class="intro">
    <p>Esta encuesta ha sido desarrollada en el marco de</p>
    <p>Estimamos</p>
    <p>Toda la informacion obtenida</p>
    <ul>
        <li>Por defecto sera confidencial</li>
        <li>Si estas de acuerdo y confirmas</li>
    </ul>
    <p>Gracias</p>
    <p>Si tienes alguna pregunta adicional</p>
</div>

2.11.3 Upload the Excel Report with the Items Translated to the New Language

Once all items in the "LiteralTranslated" column are complete, upload the Excel file to the duplicated survey via the menu option "Style:: Upload translation."

Finally, set the survey language in the survey settings (click "Edit survey" and use the "Select language" field).

2.11.4 Automatic Translation

To translate automatically using the Google AI Translation model, duplicate the survey, then edit the duplicate and go to the "Choose language" setting. Select the target language and click "Translate automatically." After a brief wait, the entire survey will be translated. Some adjustments may be needed for Choice questions.

2.12 Experiment Pipeline

The pipeline is a Salesforce-Opportunity-style tracker that makes the lifecycle of an experiment explicit. It replaces email-based coordination ("whose turn is it now?") with a visible, auditable progression through 14 stages, each one owned by a single role. The stepper is shown at the top of the survey detail screen and takes advantage of the full desktop width.

Above each stepper bubble a small time hint (e.g. 4d, 4h, 45m) shows how long the survey has spent in that stage — cumulative for stages already passed, and the running time for the current stage. This lets you spot at a glance where a survey is spending the most time (the likely bottleneck) without opening the history table. Stages not reached yet show no time.

The pipeline runs in parallel to the existing survey status (Draft / Open / Paused / Closed). It does not change how the runtime delivers the survey to respondents — only how the team tracks progress. Two stages have automatic side effects on the status: entering Pilot sets the survey to Open (so respondents can access it from the pilot wave onwards), and entering Closed sets it to Closed.

2.12.1 The 14 Stages

# Label Role What happens
1 Brief tickStat Investigator delivers the documentation out of band (email, drive). tickStat advances the pipeline once the brief is sufficient to start designing.
2 Questions tickStat tickStat creates the questions and previews each widget.
3 Workflow tickStat tickStat constructs the step tree and the routing rules.
4 Audit tickStat Run the Survey Design Review Agent and resolve any findings, manually walk the most important paths, and simulate 20 completed respondents to verify the captured results are correct. The Advance button is gated by 0 error-level findings on the latest run plus every manual check ticked.
5 Review Researcher Researcher confirms that the design matches the original brief.
6 Quotas tickStat tickStat defines the sampling quotas (or marks the survey as quota-free).
7 Confirmation Researcher Researcher confirms the quota plan.
8 Pre-pilot tickStat Internal checklist and final tests before the pilot wave (re-run Design Review, manual checks).
9 Pilot tickStat Pilot wave is launched and respondents are collected. Side effect on entry: estadoEncuesta = 'abierta'.
10 QA tickStat Pilot Review Agent runs and the team reviews findings.
11 Validation Researcher Researcher accepts the pilot data and authorises full field.
12 Final tickStat Final go-no-go check from tickStat before opening to the full audience.
13 Field tickStat Survey is open to the full audience. tickStat advances to Closed when fieldwork is finished, either because the global quota is full or because the team decides to close (e.g. when a final cell turns out to be impossible to fill).
14 Closed System Field is finished. Side effect on entry: estadoEncuesta = 'cerrada'. The researcher gets the "results ready" email; tickStat staff get an internal reminder to upload the final report to Google Cloud Storage.

2.12.2 Roles

Each stage has one responsible role. When the work is genuinely collaborative, the pipeline splits it into two adjacent stages so that the stepper always shows a single bottleneck (e.g. tickStat configures quotas → researcher confirms them):

  • Researcher (Investigador) — the survey owner (the user listed in encuesta.administrador) or any user with whom the survey has been shared via Edit · Share Survey. Signs off on the three review gates: Review, Confirmation, Validation.
  • tickStat — superadmin only. Owns every other human-driven stage: Brief, Questions, Workflow, Audit, Quotas, Pre-pilot, Pilot, QA, Final, Field. tickStat does the design work, runs the QA agents, and decides when to launch and when to close the field.
  • System — automated. Only the terminal Closed stage is system-owned; entering it triggers the side effects (status flip, notifications) automatically. There is no Advance button for system stages.

The role badge under each segment in the stepper shows the responsible role at a glance. The Advance button is rendered when the logged-in user matches the role required by the current stage. If a researcher prefers to self-build their own survey, simply share the survey with their account from Edit · Share Survey — they will then be allowed to advance the researcher gates as well.

tickStat acting on behalf of the researcher: tickStat staff (superadmin) can advance ANY stage, including the three researcher gates (Review, Confirmation, Validation). This is the on-behalf-of escape hatch for cases where the researcher is unreachable, unable to log in, or simply too slow and the experiment cannot wait. The audit trail still records who clicked Advance, so the trace is preserved — if tickStat moves through a researcher gate, the history row will show the tickStat username and (recommended) a comment explaining why the gate was advanced without the researcher's direct sign-off.

2.12.3 Required Actions and Advancing

The panel under the stepper lists the required actions for the current stage. Some actions are checked automatically against the live database state; others are manual checkpoints that the responsible role acknowledges by clicking Advance:

  • Workflow auto-launches two AI agents when the survey enters the stage: the Variable Generator ("AI - Generate question variables") and the Syntactic Reviewer ("AI - Run syntactic review of question literals"). Both checks auto-resolve against the live state, and each carries a small Run button so tickStat staff can re-launch the agent on demand from the pipeline panel; the run is asynchronous, so refresh the panel after a few seconds to see the result. The "Review all syntax suggestions" check is a human step (no Run button).
  • Audit auto-resolves "Design Review Agent run with 0 errors" against the latest run; the Advance button is enabled only when this is satisfied. The Design Review Agent is launched automatically when the survey enters Audit (the same way the Variable Generator and Syntactic Reviewer fire on entering Workflow), so the check is normally already resolving by the time you open the stage — no manual click needed. To re-run it on demand, the "AI - Run Survey Design Review Agent" check carries a small Run button right in the pipeline panel (visible to tickStat staff): click it and the agent re-runs and the checks refresh with the fresh result. The same "Run Survey Design Review" button on the Design Review tab is also still available. If the survey has customized Groovy step scripts (added via Edit · Validate step), Audit also shows a "Customized Groovy Scripts flag" check: the flag is auto-activated the moment a Groovy script is saved, so this check is normally already green by the time the survey reaches Audit. The check (and the flag) only appear for surveys that actually contain Groovy scripts — see Section 7.1 - Including Java Code for how the flag protects the survey at runtime.
  • Pre-pilot treats the Design Review exactly like Audit: the agent is auto-launched when the survey enters Pre-pilot (to pick up any design drift introduced by changes after Review), the "AI - Re-run Survey Design Review Agent and resolve findings" check auto-resolves against the latest run, and it carries the same Run button to re-run it on demand. It also lists manual pre-field quality-control checkpoints that the operator ticks before launching: survey minimum and maximum completion time set (Quality Control), per-step minimum time to screen out speeders added, panel redirects implemented (Panel section), and field manager email set (the email of the person running the field, in the Panel section) — plus the internal tickStat checklist and final test runs. The speeder-time and panel checkpoints carry a "mark it anyway" note for studies where they do not apply. Editing is no longer gated by a manual toggle at this stage — once the pipeline crosses into Pilot, editing is locked automatically for both roles (see 2.12.10).
  • QA treats the Pilot Review Agent the same way: it is auto-launched when the survey enters QA (it analyses the pilot's Done respondents), the "AI - Run Pilot Review Agent" check auto-resolves against the latest run, and it carries a Run button to re-run it on demand. Because it is a heavier LLM job, the run is asynchronous: after launching (auto or via Run) the check turns green once the agent finishes (refresh the panel after a few seconds). If the survey reaches QA with no Done respondents yet, the run is skipped and the check stays pending until there is pilot data. The "Review the agent findings" and "send the report PDF" checks remain human steps.
  • All other stages list manual checkpoints. They are informational — clicking Advance is the formal sign-off and is recorded in the audit trail with the user, timestamp, and an optional comment.

To move forward, click the Advance to button. A modal asks for an optional free-text comment (highly recommended on the researcher gates, mandatory on reverts). The transition is recorded in the history table at the bottom of the panel together with who advanced it and when.

The Advance button is suppressed for the system-owned Closed stage and for any stage whose role does not match the logged-in user. If the button is missing for a stage you expected to own, double-check who is the survey administrator and whether you need the survey shared with your account.

2.12.4 Reverting

Only tickStat staff (superadmin) can move the pipeline backwards. Reverting requires a written reason and is recorded in the history with a REVERT tag, so the audit trail always shows why a stage was re-opened (for example, "Audit found new errors — back to Workflow"). The reason is captured through a Bootstrap modal with required validation; the action cannot be confirmed without a comment.

The pipeline is forward-only in the database: a revert appends a new row to the history with is_revert = 1. Earlier rows are never deleted, so the full sequence of forward and backward moves is preserved. Email notifications do not fire on revert — only on forward advances.

2.12.5 Pipeline and Survey Status

The pipeline only mutates estadoEncuesta (the legacy survey status) at two points, so the rest of the platform's runtime gating keeps working without changes:

  • Entering Pilot sets estadoEncuesta = 'abierta' so respondents can access the survey from the pilot wave onwards. The status stays Open through QA, Validation, Final and Field — there is no second flip when the pipeline progresses through those stages.
  • Entering Closed sets estadoEncuesta = 'cerrada'.

Any other status change (manual pause, manual close before reaching Closed, re-opening a paused survey) is left to the survey administrator via Settings · Survey Status. If the survey is paused while in the Field stage, the pipeline stays in Field — pause is treated as a sub-state of Field, not as a separate pipeline stage.

2.12.6 Email Notifications

Every forward advance fires automatic email notifications. Reverts never trigger emails.

To the researcher (the survey administrator, plus collaborators in encuesta_share):

When the pipeline enters Subject Purpose
Review "Action required — review design" Asks the researcher to walk through the design review checklist (routing paths, validations, end-to-end test, mandatory questions, logbook, mobile rendering, choice coding, multiple-choice assignment, workflow tree).
Confirmation "Action required — confirm quotas" Asks the researcher to verify the quota configuration (target audience, cell sizes, nested quotas, screen-out).
Validation "Action required — validate pilot data" Asks the researcher to review the pilot data (Done counts, drop-off, completion times, agent findings) and authorise full field.
Closed "Field closed — results ready" Tells the researcher fieldwork is over and lists the reports they can download.

CC on every researcher email: in addition to the recipients above, every researcher-facing pipeline email is sent with tickstat@tickstat.com and soporte@tickstat.com in CC. tickStat operations have live visibility from the moment the call to action goes out, without needing to wait for the separate internal notification listed below.

"Note from tickStat" block: when tickStat staff type a comment in the Advance modal at any of the four researcher-facing transitions (Review, Confirmation, Validation, Closed), that comment is rendered as a highlighted "Note from tickStat" box right below the survey identifier in the email body. Useful for surfacing context-specific guidance ("please pay special attention to questions P5–P8", "quotas adjusted as discussed in our call yesterday", etc.). When the comment is empty the block is not rendered.

Internal notifications (to tickstat@tickstat.com, with soporte@tickstat.com added to the same TO header for the Validation and Closed transitions because field operations are about to start or end):

When the pipeline leaves / enters Recipients Purpose
Leaving Review (researcher signed off design) tickstat@ tickStat can start configuring the quotas.
Leaving Confirmation (researcher confirmed quotas) tickstat@ tickStat can start the pre-pilot checklist.
Leaving Validation (researcher authorised field) tickstat@ + soporte@ Heads-up that the survey is going to full field; support should make sure the infrastructure is healthy.
Entering Closed tickstat@ + soporte@ Reminder of the manual closure checklist, with a highlighted bullet on uploading the final report to Google Cloud Storage.

All emails share the same visual style as the rest of the platform's transactional emails (gradient header card, identifier box for the survey, callout boxes for tips and next steps, button CTA back to TickStat).

2.12.7 Reviewing Past Stages

Click any green (completed) segment of the stepper to open a read-only inspect view of that stage. The actions panel switches to a striped grey background and shows:

  • The list of checks for the past stage, with their current pass/fail state for the auto-resolved ones (so you can see whether conditions still hold today).
  • An amber banner with the audit trail entry that records leaving that stage: when it was advanced, by whom, and with what comment.
  • A Back to current stage button that returns to the live view.

The Advance and Revert buttons are hidden in inspect mode — it is purely for auditing what happened. The stepper also has a Refresh icon in the panel header to reload the current state without leaving the survey detail screen (useful after re-running an agent in another tab or after a stage transition that happened from a different session).

2.12.8 Stage Column in the Survey List

The survey listing (Surveys menu) has a Stage column that shows the current pipeline stage as a colour-coded badge. This makes it possible to see the portfolio of experiments at a glance and to spot which ones are bottlenecked at the same stage without opening each survey.

Existing surveys created before the pipeline feature receive a stage automatically when the database is migrated:

  • Surveys with status Closed are mapped to Closed.
  • Surveys with status Open or Paused are mapped to Field.
  • Everything else is mapped to Brief.

The default mapping is intentionally conservative — if the actual stage is later in the pipeline, the responsible role can advance it manually from the survey detail screen (or tickStat staff can revert from a wrong starting point).

The three researcher gates (Review, Confirmation, Validation) are highlighted in the stepper with an amber border and a small user-check icon overlay so the three checkpoints are visible at a glance regardless of where the survey currently sits. When the logged-in user is the researcher for that survey and the active stage is one of the three gates, the active circle pulses in amber to act as a personal call-to-action.

2.12.9 Pipeline Kanban (portfolio view)

A Salesforce-Opportunity-style board that shows the whole portfolio at a glance — one column per pipeline stage, one card per non-deleted survey. Useful for tickStat staff to scan where every experiment is currently parked and who is blocking it, without bouncing between detail screens.

Where to find it: Admin menu (left nav) → Pipeline Kanban. tickStat staff only — investigators do not see the entry. Their visibility into their own surveys is already covered by the per-survey stepper and the Stage column on the survey listing.

What each column shows:

  • The stage name (Brief, Questions, Workflow, …) and a count badge with the number of cards in that stage.
  • A small role letter (T = tickStat, R = Researcher, S = System) coloured the same way as the per-survey stepper, so you can tell at a glance who blocks each column.

What each card shows:

  • The survey name (truncated; hover for the full text).
  • The administrator (researcher who owns the survey).
  • Time-in-stage — "today", "1 day", or "N days". Turns amber at ≥ 7 days as a low-key staleness signal, the same threshold used by the per-survey stepper.
  • A small estado badge (Open / Closed / Paused / Draft) bottom-right for legacy context.

Filters and controls:

  • Search by name — live client-side filter, no re-fetch.
  • Refresh — re-fetches the portfolio. Useful after someone else has advanced a survey in another tab.

Active portfolio only: the Kanban shows only surveys whose legacy estado is Open, Paused or Draft. Closed surveys never appear — the board is meant to highlight what's currently in-flight. To inspect a closed survey use the regular survey listing instead.

Read-only in v1: clicking a card opens the per-survey pipeline stepper (the same screen you reach from Survey detail), where you advance or revert through the existing buttons. Drag-and-drop between columns is deliberately deferred — we will add it once the volume of active surveys justifies the extra UX surface.

Backwards compatibility: the Kanban is a separate read-only screen. It does not change the survey listing, the stepper, or any pipeline transition behaviour.

2.12.10 Edit Permissions by Stage

Editing rights are derived from a (role × pipeline stage) matrix. There is no manual "lock" toggle anymore: as the survey advances through the pipeline, editing automatically tightens; reverting to an earlier stage automatically re-opens it. This guarantees that the design freezes once a researcher has signed off and that nobody can silently mutate a survey that is already collecting respondents.

The matrix:

Stage Researcher can edit tickStat can edit
Brief Yes Yes
Questions Yes Yes
Workflow Yes Yes
Audit Yes Yes
Review Yes Yes
Quotas No Yes
Confirmation No Yes
Pre-pilot No Yes
Pilot No Override only
QA No Yes
Validation No Override only
Final No Yes
Field No Override only
Closed No Override only

"Editing" covers everything that mutates the survey definition: changing settings in Survey Settings, adding / editing / deleting questions, modifying the step tree, modifying routing rules, and the equivalent operations through the Agent API. Read-only operations (viewing results, exporting data, running analyses, browsing the version history) are not affected by the matrix.

Researcher gates explained. A researcher edits freely during the design phases (Brief through Review). The moment the pipeline crosses into Quotas, the researcher's edit rights end — by design, because the next four stages (Quotas, Confirmation, Pre-pilot, Pilot) are owned by tickStat and any further design change must go through a tickStat-driven revert to an earlier stage. This keeps the audit trail honest: there is no way for a researcher to silently rework a survey after they have signed off on Review.

tickStat's lockdown stages. Even tickStat staff are locked out of direct editing once the survey enters Pilot, Validation, Field or Closed. These are the stages where respondents are actively answering (Pilot, Field) or where the data has already been validated and closed (Validation, Closed). To edit a survey at one of these stages, tickStat must enable the Force edit (admin override) toggle in Survey Settings (see 2.3.5). The override is intended for emergency fixes — typo corrections, broken routing rules discovered after launch, etc. — and should be turned off again immediately after the fix.

What happens when an edit is blocked. Attempting to save a forbidden change produces an explicit error rather than a silent failure:

  • In the admin panel (JSPs): the save action returns an error and the editor stays open with the unsaved changes still on screen, so nothing is lost.
  • Through the Agent API (and therefore the LLM-driven flows in the panel-web Survey Admin): the endpoint responds with HTTP 409 Conflict and a SurveyLockedException payload identifying the blocking stage.

Reverting to re-open editing. If a genuine design change is needed at a locked stage, the correct path is to revert the pipeline to a stage where editing is allowed (see 2.12.4 Reverting) rather than reaching for the override. Reverts are recorded in the audit trail with the reason; override-driven edits are not. tickStat staff are the only role that can revert, so a researcher who needs a post-Review change should request a revert from tickStat rather than asking for the override to be enabled.

Sharing surveys. Adding a researcher via Edit · Share Survey (see 2.5) gives them the same researcher-tier permissions on the matrix — they can edit during Brief…Review and are locked out from Quotas onwards. The override has no effect on shared researchers: it only re-enables editing for tickStat staff.