addScreeningQuestion
Adds a question to this beta project's screening form (the public application form). Only usable BEFORE the form is live: publish it with publishScreeningForm once the questions are ready. Allowed types: MultipleChoices, SingleChoice, FreeText, YesNo, Rate, Instructions (file and ranking are not supported on screening forms). Auto-review rules can then reference the question by its questionId (getScreeningSetup). Requires the screening setup to exist (configureScreening). Each question carries ready: false means it fails authoring validation (a choice question with no options, say) and blocks publishScreeningForm until fixed. ready is input for your reasoning, not for users: when everything passes, do not mention it; when something fails, say what is missing in plain words instead of quoting the flag.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | The question shown to applicants. | |
| type | Yes | The answer type. | |
| 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 applicant must answer. 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 question (basic HTML allowed). |