Migration map.

questionnaire_apply

See the current correction and older-server guidance before preparing new inputs; keep existing task inputs unchanged during recovery.

This implementation is a dependency of the documentation branch.

Create or revise a full questionnaire through one composed workflow, including ordered questions/options and optional original images. Use visibility to activate or deactivate existing records.

Access and input

Requires OWNER or DELEGATEE with MANAGE_MARKETING_TOOLS on the selected channel. The source has no questionnaire plan or connected-domain gate. Hosted selected-channel resources admit these tools only for the exact channelCode; account resources exclude them.

channelCode and questionnaire/answer IDs are strings of 1–512 characters, excluding literal dot/double dot, slash, backslash, ASCII controls and DEL. Obtain them from authorized discovery/results; numeric row IDs, URLs and credentials are not substitutes. Strict input objects reject unknown properties.

Action combinations and nonempty settings are runtime refinements beyond the flat JSON Schema. The all-zero revisions and illustrative IDs below must be replaced with current authorized reader values. All examples are dry runs.

{
  "channelCode": "selected-channel-code",
  "requestId": "questionnaire-create-01",
  "action": "create",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "title": "Feedback",
    "titleDisplay": "Share your feedback",
    "description": "Tell us about your experience.",
    "isGuestAnswerAllowed": false,
    "isDuplicateAnswerAllowed": false,
    "backgroundColorInHex": "#f5f5f8",
    "questions": [
      {
        "title": "Your topic",
        "type": "SHORT_ANSWER",
        "isEssential": true,
        "hintText": "A short summary"
      },
      {
        "title": "Your experience",
        "type": "LONG_ANSWER",
        "isEssential": false
      },
      {
        "title": "Choose a category",
        "type": "RADIO",
        "isEssential": true,
        "options": [
          {
            "label": "Product"
          },
          {
            "label": "Support"
          }
        ]
      },
      {
        "title": "Topics of interest",
        "type": "CHECKBOX",
        "isEssential": false,
        "options": [
          {
            "label": "Updates"
          }
        ]
      },
      {
        "title": "Preferred contact",
        "type": "DROPDOWN",
        "isEssential": false,
        "options": [
          {
            "label": "Email"
          },
          {
            "label": "None"
          }
        ]
      }
    ]
  },
  "dryRun": true
}

Settings and ordered replacement

Creation defaults titleDisplay to title, description to empty, active state to true, guest/duplicate answers to false, backgroundColorInHex to #f5f5f8, and questions to empty. The console has a localized default description; supply the intended localized text explicitly. This tool does not infer locale. Omitted settings on revision preserve existing values; empty arrays and explicit null have different meanings from omission.

Each settings.questions[] is strict and uses these fields:

Retain a question with qid and/or id; both must match the same existing question when supplied. Each existing question can be retained once. A question without either identity is new. Existing types cannot be changed in place: omit the old question and add a new one without an old identity. Omitted questions/options are removed by replacement. Question and option order is recomputed from array order starting at 1. existingOrder preserves the selected option's image and unknown business fields while permitting label/reordering changes. Omitted question description/hint and hidden source fields are preserved. A stored null question description or cover reference remains null when omitted; this does not permit null in the writable description input. Explicit image removal still produces the empty source reference. UI helpers question.uuid and option.value are removed from the submitted DTO.

The 100-question and 16,384-character text/label caps are bridge limits for source-unbounded controls. Runtime composition rejects unknown/mismatched/duplicated retained identities and invalid guest/duplicate combinations. A supplied questions array is the complete desired list, not a patch.

{
  "channelCode": "selected-channel-code",
  "requestId": "questionnaire-revise-01",
  "action": "revise",
  "qrid": "selected-questionnaire-id",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "title": "Updated feedback",
    "coverImage": null,
    "questions": [
      {
        "qid": "selected-question-id",
        "title": "Choose a category",
        "type": "RADIO",
        "isEssential": true,
        "options": [
          {
            "label": "Support",
            "existingOrder": 2
          },
          {
            "label": "Product",
            "existingOrder": 1,
            "image": null
          }
        ]
      }
    ]
  },
  "dryRun": true
}

Images and service prerequisites

Images must contain structurally validated original PNG/JPEG bytes. Filename extensions are case-insensitive at runtime; the JSON-exported regex omits that flag, so use lowercase extensions for portability. No data URL or arbitrary image URL is accepted. Cover bytes must be strictly below 10 MiB, each option image strictly below 2 MiB. All replacement images together must be below 10 MiB per request, a bridge cap. The shared exported image object has the cover base64 bound (13,981,012 characters); option byte limits, canonical base64, structure and aggregate size are enforced at runtime. Split larger changes into separately read/revised operations.

A larger envelope does not raise those tools' individual image limits.

The host configures the normal API origin. Replacing images additionally needs the resource gateway, bucket and region before any effect, including when planning. The workflow obtains channel-scoped grants accepting HTTP200/201 data, validates the configured upload grant, and uploads checked original bytes sequentially. An older uncertain grant is never retried by this correction. Only verified receipt locations enter the full DTO; byte length and checksum must match. Journals retain metadata/receipts, never original bytes, base64 or upload credentials. Null stores an empty image reference; omission preserves it. No automatic orphan deletion or rollback occurs.

{
  "channelCode": "selected-channel-code",
  "requestId": "questionnaire-image-01",
  "action": "revise",
  "qrid": "selected-questionnaire-id",
  "expectedRevision": "0000000000000000000000000000000000000000000000000000000000000000",
  "settings": {
    "coverImage": {
      "filename": "cover.png",
      "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aDWQAAAAASUVORK5CYII="
    }
  },
  "dryRun": true
}

Inputs

Results and full readback

A new dry run returns success / QUESTIONNAIRE_PLAN with noop, changes and plannedStages; writesPerformed is false and verification.confirmed is false. Planning does not reserve a future revision. The workflow compares full content twice, verifies channel/credential continuity, checks the supplied revision, and repeats preservation checks before every effect.

An actual no-op records done without upload/save. Otherwise it sends one full create POST or known-ID revise POST after any uploads; creation accepts HTTP200/201 data, while revision still requires HTTP200 data. Other success statuses are not implicitly accepted. There is no recache. Creation requires returned positive id, qrid and channelId equal to the selected channel. Full readback checks requested fields, retained identities and all untouched business fields, including their supported null representations. Question arrays must have the exact requested length and match after sorting by explicit question order. Ambiguous question order/identity and duplicate option order reject. Option arrays retain their source positions and must match the requested order. New server IDs/defaults may be added. answersCount is excluded from content comparison.

Expected root updatedAt/lastRevisedAt and each question updatedAt are excluded only from cross-save matching because the service regenerates them. They remain in before/after snapshots, content revisions, repeated-read stability, no-op detection and pre-effect conflict checks. Other unknown business fields remain required to match. Expected question arrays are sorted by explicit order; option positions are not normalized. Saved journal snapshots are validated without rewriting or migrating their arrays. This narrow tolerance can reconcile a known-ID sent revision by readback but does not weaken pre-save conflict checks or permit unrelated drift. A mismatch still returns QUESTIONNAIRE_READBACK_MISMATCH and preserves the pending task; never resubmit just to force completion.

All baseline/readback records, the creation receipt, outgoing revision DTO and persisted before/after/created identities must belong to the selected numeric channel. Missing or conflicting identity is rejected, not silently stripped. A foreign answer parent cannot supply a valid revision. Older journals lacking the now-required channel identity are not automatically migrated; preserve them for inspection.

QUESTIONNAIRE_COMPLETE includes taskId, taskType questionnaire, phase done, questionnaires and revisions containing qrid/revision pairs. saveAcknowledged is separate from observed completion: known-ID readback can confirm a sent change without its acknowledgement. writesPerformed is false for no-op, true for a saved acknowledgement or recorded upload, and can be null when a sent effect is uncertain. verification.confirmed and fullReadbackVerified apply only to fresh completion; atomicSnapshot, causalityVerified, visitorFormVerified and imageAvailabilityVerified stay false. Pending output is QUESTIONNAIRE_PENDING with checkpoints, requiredAction and possibly lastResult/journalPersistence. An auth/context failure can suppress channel/navigation metadata and retain pending status.

Task recovery

Use task_status or task_resume with the original taskId and explicit taskType questionnaire. Same-ID apply must keep the original input/revision; dryRun is outside its fingerprint. A conflicting requestId returns REQUEST_ID_CONFLICT. Invalid stored identity/fingerprint/progress returns TASK_STATE_UNVERIFIED without adopting the journal. QUESTIONNAIRE_CONFLICT requires a fresh read before an unsent new operation; it is not permission to replace the ID of an uncertain task.

If creation was sent without a durable returned qrid, QUESTIONNAIRE_CREATE_UNKNOWN requires operator inspection. Do not adopt a similarly titled record or automatically repeat creation. A known-ID mismatch remains pending without resend. Completed journal rejection preserves history. There is no questionnaire DELETE tool; deactivate an unwanted record.

Navigation opens the known editor, or the list until create identity is durable.

Saved record identity

A missing record differs from an existing malformed record. Stored JSON null, false, zero or an empty string is rejected with TASK_STATE_UNVERIFIED by the existing record validator. Apply/dry-run/status/resume must not overwrite it or treat it as a fresh task. Preserve the file for inspection; do not delete/edit it or replace the request ID to bypass the error. Existing valid task recovery and genuinely missing-record behavior remain unchanged.