createStep
Adds a step to a task and appends it to the end of that task's step list. A step is one thing a tester reads, answers, or uploads, except TriggeredEmail: that one is invisible to testers and sends an email the moment a tester answers the step immediately before it, so it takes no text and is rejected as the first step of a task. Creating always appends, so create steps in the order testers should work through them, or reorder them afterwards with updateStepsOrder. On a draft or scheduled beta project the change is applied immediately. On a running or paused beta project the change is STAGED: testers do not see it until commitTaskChanges publishes all staged changes (revertTaskChanges discards them; getBetaTasks with version 'unpublished' shows the staged state). While staging, these tools accept BOTH the live id and the staged id of a task or step, but always respond with the STAGED row — expect ids you did not pass in, with liveVersionId linking back to the live row. Content of finished or archived beta projects cannot be edited.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | The step's question or title, as the tester sees it (up to 128 characters). Omit it for a TriggeredEmail step, which testers never see; passing one is rejected. | |
| type | Yes | The kind of step. MultipleChoices, SingleChoice, Rate, Ranking and TriggeredEmail REQUIRE a content shaped for the type (a choices array, a choices array, a scale object, an items array, an email object). FreeText, Instructions and File take no content and reject one. YesNo takes no authored content either: omit it and the fixed Yes / No pair is set automatically, though echoing that exact pair back is accepted so a step read from getBetaTasks round-trips. TriggeredEmail is not a step testers see or answer: it sends an email the moment a tester answers the step immediately before it, so it takes no "text" and can never be the first step of a task. | |
| taskId | Yes | ID of the task, from getBetaTasks. Never invent ids. | |
| content | No | The step configuration, shaped by type: for MultipleChoices/SingleChoice an array of at least 2 { choice } options with non-empty texts, optionally plus ONE final { choice: "Other", other: true } option that lets the tester type a free answer (its label is fixed: choice must be the literal text "Other", any other wording is rejected); for Rate an object { scale (number, 3 or more), symbol ("Thumb", "Star" or "Square"), lowerText?, higherText? (labels for the scale ends, up to 20 characters, default empty) }; for Ranking an array of at least 2 items { id (a v4 UUID you generate), text } with unique ids and unique texts; for TriggeredEmail an object { to, subject, message, cc? } where to is { allManagers?: boolean, allTesters?: boolean, tagsIds?: string[], personFieldIds?: string[] } and names at least one audience, subject is plain text of at most 128 characters and takes no variables (nothing replaces them there, so the recipient would read the braces), message is the email body as basic HTML reading at most 4096 characters of text, and cc is a list of Person custom field ids. Any other key of the email object or of to is rejected rather than dropped, so bcc and to.emails are not accepted: nothing would send to them. tagsIds are tester tag ids from listTesterTags, and ONLY the entries it marks assignable: a computed smart tag is rejected because a triggered email cannot be sent to one. personFieldIds and cc are ids of Person-type fields from listCustomFields; a personFieldIds field routes the email to the manager-persons that tester recorded in it, cc puts them in copy. The email goes out the first time a tester answers or skips the step before it (skipping a whole optional task sends nothing), one email per tester, and the audiences reach: allTesters ONLY that tester, never every tester in the beta project; tagsIds that same tester, only if they carry one of the tags (tester tags never reach managers, and beta labels are not tags); allManagers every manager on the beta project. To notify a manager when a tester finishes a task, make this the task's last step and use allManagers or personFieldIds. message may use these tester variables: {{USERNAME}}, {{FULL_NAME}}, {{ADDRESS}}, {{EMAIL}}, {{PHONE}}, {{PROJECT_NAME}}, {{WORKSPACE}}, {{REMAINING_PROJECT_DAYS}}, {{CURRENT_WEEK_DAY}}. The {{MANAGER_*}} ones belong to invitations and are rejected here. On an SDK beta project the audience must be managers only (allManagers), because its testers are not workspace testers and every other audience would reach nobody. REQUIRED for MultipleChoices, SingleChoice, Rate, Ranking and TriggeredEmail; omitting it is rejected. Must be OMITTED for FreeText, Instructions and File; passing one is rejected. Omit it for YesNo too (its answers are fixed to Yes / No, set automatically); passing that exact pair back is accepted, anything else is rejected. Pass the array or object value itself, not a JSON-encoded string. Call getBetaTasks to see the current shape of existing steps. | |
| required | No | Whether the tester must answer this step. Defaults to true. | |
| productId | Yes | ID of the beta project to query. Get valid IDs from the listProducts tool. | |
| description | No | Supporting detail shown under the step (up to 1024 characters of text; basic HTML is allowed). |