Fieldwork: Participants and Runs

Fieldwork connects a reviewed Script version to an activity and its responses. Use the human UI to prepare and change Runs. The optional MCP connection reads aggregate progress; the local MCP candidate also reads quota configuration, current targets/counts and original setup history with paid operator access. The candidate Workbench can enable these same four reads with explicit consent in your own assistant session; see Survey MCP. The public ODIN extension 0.7.12 does not include this bridge, and Workbench 0.8.5 remains unpublished.

During the invitation-only beta, use invented participants and answers. Production fieldwork is outside the permitted beta use. Hosted quotas are not enabled in the deployed beta. Locally tested canonical quota/lifecycle work and the bounded ODIN verification foundations do not change that deployed scope.

The objects you work with

The Script owns question wording, routing, validation and study decisions. The platform owns who may access a Run, version pins, shared counts, service authorization and recorded responses. An uploaded script does not grant access to private records or external services.

Prepare Participants and a Group

1. Open Participants from the product bar and choose the owning Account. Use People, access and billing if the Account or controls are missing.
2. Choose Create group, enter its name and optional description, then open it.
3. Choose Import sample and select a CSV, TSV or XLSX file of invented people. Choose the identifier column. If a sample schema is configured, review its stable field keys, column mapping, required values and types.
4. Preview the import. Review accepted, duplicate and rejected rows before importing; a preview is not a saved participant cohort.
5. Inspect the members and the import audit. Use Participant data to review or correct a member’s identifier, name and supported sample attributes.

A Group is reusable across Runs. Removing a member is different from erasing their data. Participant erasure removes identity/contact data under the product’s erasure path; it is not a promise that every answer or previously downloaded file is anonymous. Questions may themselves collect identifying information.

An open survey does not require importing a Group first.

Prepare a Run

1. Open Runs, keep the intended Account selected and choose the create-Run action. Select the Script and immutable Version you already tested.
2. Choose Activity Type: CAWI survey, Practice quiz, or Timed activity (participant-visible services). An activity type does not create a scoring model or confidential exam delivery automatically.
3. Choose Access using the table below. Personal invitations and signed-in assignments require a Target Group; an open survey does not use one.
4. For a timed activity, review the optional time limit. Choose the respondent progress display; it estimates questionnaire progress, not score or time left.
5. Choose Create draft run. Creating the draft does not open response access.
6. Open Settings. For QSS, configure Interview outcomes: choose each ending’s meaning and Retain answers, then Save outcomes. Complete always retains answers. Other terminal endings can retain or discard them. Review services if the script calls them; see Services. In the local candidate, an unused open-link QSS draft can also configure quotas before activation; follow the quota setup steps below.
7. Choose Activate run, review the current cohort/access and confirm. Activation allocates attempts for the current Group, or opens the shared link. Test the respondent path yourself before sending invitations.

Activation and invitation sending are different actions. The Messages section has its own preparation, approval and send controls where enabled. Do not assume that activating a Run sends email. Invitation sending has separate beta limits.

Start, resume and change a version

Open the respondent link or Portal assignment. Opening an allocated activity is not a Start. Read its entry page, then explicitly choose Start. A timed attempt’s clock starts there; its source version and supported launch settings are pinned. Reopening resumes the existing attempt when current access permits it.

Uploading a Script version does not change a started attempt. To change future starts, open Run Settings, select Script version for new interviews, then Use this version. Review the outcomes again and test the change. Started interviews keep their original version; compatibility between versions is the author’s responsibility.

A Run with selected quota configuration keeps its selected Script version and opening dates. Create a new Run for another version or quota definition.

Use the practice quiz for visible, self-paced feedback. Calculated values shown by that recipe are not stored grade columns. A later try needs another permitted attempt; a script cannot reset a finished one.

Pause, resume or close

In Run Settings, use the Run status controls and review the confirmation.

• Pause run stops new starts, online reopening and fresh submissions until resumed. Already open interviews may continue offline on the device; pausing does not delete or expire those attempts.
• Resume run permits online access and submissions within the opening dates. Started attempts retain their original source and saved history.
• Close run cannot be undone. It stops new starts and fresh submissions permanently. Existing accepted history and retained answers remain. An open offline interview may have answers that can no longer be submitted.

Review started-attempt counts before closing. If another operator changes the Run while your confirmation is open, reload the current state before trying again.

Configure quotas in the candidate build

The local candidate supports quota setup in Run Settings. This is not enabled in the deployed beta. Setup requires current paid editor access and an open-link Qube Script draft with no Group and no attempts, including allocated attempts. Existing active Runs and ODIN Runs do not use this setup path.

1. Open Settings on the draft, then Configure quotas. Review the selected immutable Script version and opening dates.
2. Enter Quota binding name, matching the name in your script’s quota allocation call. Enter Initial overall target and Reservation lease in seconds. The lease sets how long admission reserves a place.
3. Choose Add quota cell for each answer-based cell. Give it a stable ID, label, initial target and Hard or Soft mode. Choose source questions and exact answer values, or an inclusive range for an integer question. Multiple conditions in a cell use AND; values within One of use OR.
4. Choose Review quota configuration. Check the binding, targets, modes, predicates and selected Script, then explicitly choose Configure quotas. Opening Settings or reviewing a form does not select a configuration.
5. Configure and save Interview outcomes, then separately choose Activate run. Test Start, admission, completion and the response dataset before using the Run.

For example, a script using environment.allocate("campaign-quota", "screening") needs the quota binding name screening. The call records a boolean admission result; the script routes on that result. It does not supply counts, targets or authoritative membership. Define the cell conditions from the source questions already answered before the call, and map the script’s full-quota ending to Quota full in outcomes.

Cell conditions, modes, binding, lease and selected Script become fixed once configuration is selected. Targets can change later. An overall-only quota needs no cells; cells can overlap and their targets need not sum to the total. Choice conditions use the script’s typed values, not interchangeable labels.

An unacknowledged setup keeps its exact reviewed command on the device. Retry quota setup confirms that original command. If another operator needs to finish selected setup, Review quota recovery shows its original actor and configuration before explicit recovery. Recovery can confirm history after activation or closure; it does not reset targets or reopen the Run. A saved activation likewise has Retry Run activation. Resolve unsaved quota changes or pending commands before changing Run status or Script version.

Inspect and change quota targets

After confirmed setup, Quotas shows the current targets and counts. An unavailable or uninitialized message is not an empty quota table.

The table shows the overall target and each named cell, its Hard or Soft mode, completed contributions, active reservations and remaining places. Open Conditions to inspect the cell’s source-question predicates. Cells can overlap, so their counts and targets need not add up to the overall total. Counts are a loaded snapshot; Refresh quotas reads current state.

Hard limits govern new quota admission. A reservation protects an admitted place for its configured lease. Soft cells track targets without blocking admission. Successful final answers determine completed contributions, including answers changed after Back or resume. Those contributions can exceed a target; the original admission decision stays in history. Lowering a target preserves existing reservations and accepted answers.

To change targets, choose Edit targets, enter non-negative whole numbers and a Reason for changing targets, then Save target changes. The full target set is saved against the loaded revision. Conditions, modes and lease remain fixed. A closed Run permits reading counts and recovering an earlier saved command, but refuses a new target change.

If another operator changes targets, your proposed values and reason remain. Refresh, inspect the current targets, then choose Review current revision before saving again. If a save is not acknowledged, the exact command remains on your device: Retry target change recovers its original result. Do not replace that command merely because the connection failed. The saved receipt records who changed targets, why, when, and the before/after values; the table separately shows current state, which may include later changes.

Target management requires current paid editor access to the Account and Script. Aggregate dashboard access does not expose configuration or target editing. The platform supplies counts and recorded observations; the script decides how to use them. Metric score setup is described below. Rim fitting still requires its separate hosted inventory and refresh integration.

Configure quota priority scores in the candidate build

After confirmed quota setup, Quota priority scores can bind numeric quota expressions on an unused open-link QSS draft. This remains a local candidate, unavailable in the deployed beta. Up to 100 immutable bindings share the existing score capacity. Each binding has its own original actor, reason and receipt.

1. In New score binding, enter Score binding name, matching the name your script will request.
2. Enter Quota score expression and a reason. Use target(), reserved(), contributed() and remaining() for the overall quota, or supply an exact cell ID such as remaining("north"). Arithmetic, min() and max() are available. This is a bounded expression language; it does not execute SQL.
3. Choose Review score binding, inspect the immutable expression, selected source/policy and attribution, then Confirm score binding.
4. Confirm every required binding before separately activating the Run.

For example, min(1, max(0, remaining("north") / max(1, target("north")))) returns the remaining fraction of the North target. Remaining subtracts completed contributions and active reservations, with a lower bound of zero. A fresh metric must return 0..1; invalid, non-finite, out-of-range or division-by-zero results record no score. Guard zero targets explicitly when dividing.

The script uses the existing service primitive:

function north_priority() returns integer = service.call("quota-score", "north-priority").score

The recorded native result contains score (integer 0..1000), target_revision and policy_revision. Higher values mean higher configured priority. The script owns thresholds, routing and study decisions. A score creates no reservation; use the separate quota allocation call for admission. Even score 1000 cannot override a full hard quota.

Bindings become fixed at creation and cannot be added after activation. If activation wins a concurrent creation, that fresh creation is refused without late application. Admitted · unconfirmed means an original command was selected; it does not prove that a binding was accepted. Review recovery can confirm an original accepted binding after activation or closure and retains its original actor. It cannot create a new binding in that state.

An unacknowledged command retains its exact request on the device. Retry score command recovers it; unknown errors do not permit a replacement command. Resolve unsaved or pending score work before changing Run status or leaving the Run. GET, review and recovery do not activate a Run.

Scores are recorded per native call identity and repeat scope. Back, reload and replay reuse the original value, even after targets change. A new device can reanswer against the authorized observations; this does not restore unsaved answers from another device. Canonical metric Runs currently refuse generic provider calls and rim collection payloads through this door. Provider services, rim inventory and production adoption remain separate work.

Inspect responses

Open Responses for aggregate counts and the authorized attempt roster. The UI shows the latest synced state; offline work may be absent until the respondent reconnects. Completed, finished and expired attempts are different statuses. History can include reset or erased attempts, so counts are not a unique-person census.

Dashboard-only access exposes aggregate progress and withholds respondent details, operational controls and exports. Script operators have separate permissions. Changing a progress-role assignment does not grant Script editing.

Create a private answer export

For a QSS Run with completed retained answers, open Exports:

1. Choose Export version to set the questions, labels and order, or choose Union of versions. Choose All data or Only data collected using this version where available. A union includes all versions and leaves blanks for missing answers.
2. Choose CSV, JSONL, or CSV (SSS). The current layout is wide. CSV (SSS) includes its Triple-S metadata; all formats include a data dictionary.
3. For SSS, choose exact text or the explicit single-line conversion. Stored answers stay unchanged. CSV refuses formula-like text; use JSONL to preserve it.
4. Choose Create export when enabled. Wait for Ready, then download from your own authorized session. Use Refresh if processing status is delayed.

The standard answer dataset includes completed retained QSS responses. Retaining a finished unsuccessful attempt does not include it automatically in that dataset.

Exports are private to the requester and exclude sample identifiers by default. That does not remove identifying text from answers. An erasure or permission change can invalidate a prepared export. Treat any file you already downloaded according to your own retention obligations.

Current admission limits are 1,000 responses, 8 MiB of response history, 100,000 answer cells and 16 MiB of output. An unsupported structure, lossy profile or exceeded limit refuses the export rather than creating a partial file. Queued exports depend on deployment configuration. Parquet, larger-volume streaming and native ODIN answer datasets are not available through this guide. Hosted ODIN completion remains unverified; debugger replay is not trusted final evidence.

For AI-assisted design, scoped aggregate progress and the candidate paid-operator quota reads, see Survey MCP. The current quota read reports operational targets/counts; setup history reports the original configuration. Preparation, target changes, recovery and activation still use the reviewed human UI.

In a supplied candidate Workbench, QUBE: Allow MCP Fieldwork Reads requests explicit consent for this editor window/current Test connection and uses the existing device sign-in if needed. It enables the application setting qube.ai.mcp.fieldwork.enabled, which defaults to false; changing it alone grants nothing. Only the exact https://test.qubesurvey.com destination supports this bridge. Supply the intended Account UUID and choose a returned Run UUID; current scoped progress permissions and paid operator permissions still apply.

QUBE: Disable MCP Fieldwork Reads, disconnect, a changed connection or credential, and window reload revoke local access while script tools remain available. The child holds a revocable loopback capability; the ordinary hosted bearer stays in the editor host. Returned data may reach your assistant and cannot be recalled. The bridge adds no mutation tools, exports or hosted OAuth, and it does not enable quotas in the deployed beta. Unavailable reads are not zero counts. Scripts still own study decisions; accepted final over-target counts and original admission history keep their existing meaning.