Forms that create work
A form turns answers into a real work item in a project. Use one when people who do not know your workflow need to report a bug, ask for something or send a request. This page is for project administrators who design forms and for members who fill them in.
Design a form
Section titled “Design a form”-
Create a form in a project. Give it a name and choose the work type it creates, for example a bug.
-
Add questions. A form has 1 to 100 of them. Each question has a name, a value type, an optional help text of up to 500 characters, and whether an answer is required. Choice questions have options.
-
Map each question to a field of the work item: the summary, the description, the priority, or a custom field of the project. A summary question is required, and no field can be mapped twice.
-
Write a confirmation message of up to 500 characters. People see it after they submit.
-
Turn the form on. A paused form does not accept answers.
A form created without questions starts with a summary and a description question.
What a form cannot map
Section titled “What a form cannot map”Forms cannot set the status or the resolution. A new work item gets the initial status of its work type’s workflow. If that workflow starts in a done status, the submission is refused with 422 resolution_required and nothing is created. Conditional questions are not available.
Who can fill in a form
Section titled “Who can fill in a form”By default only people who can create work in the project can submit. A project administrator can widen that.
| Access | Who can submit |
|---|---|
| Project | People who can work in the project |
| Signed in | Anyone signed in to your site |
| Public link | Anyone who has the link |
Sharing a form creates a link. Creating a new link, or stopping sharing, retires the old link at once, and the old link then answers 404. Forms with questions that pick a person or a group cannot be shared.
A visitor who is not signed in sees only the form’s name, description and questions. They never see the project or the field identifiers. A signed-in-only form asks visitors to sign in first. If the person who shared a link can no longer manage the project, the link stops working.
You can ask public visitors for an e-mail address. In that case the address is required to submit.
Abuse limits
Section titled “Abuse limits”| Limit | Value |
|---|---|
| Daily limit per form | Set by the project administrator, from 1 to 5,000 |
| Per visitor | 5 submissions per 10 minutes for each visitor address |
| Per signed-in person | 10 submissions per 10 minutes |
| Hidden trap field | A hidden field that must stay empty. A filled field is refused. |
A limit answers 429 too_many_submissions or daily_limit_reached, with a Retry-After header. A refused trap field answers 400 submission_rejected.
What happens when someone submits
Section titled “What happens when someone submits”The server checks every answer again, even if the page already did. A refused answer is marked at its question, and the code is invalid_answer. Answers you typed stay on your device through a failed send, a reload or a sign-in.
If all answers are valid, Orbit creates the work item, keeps the stored answers and records the activity in one step. Invalid input creates nothing. The person then sees the form’s confirmation message and a reference. Only a signed-in person who may read the new work also receives its key.
Submitting to a disabled form answers 409. Submitters need write permission in the project, except through a shared form.
Read the submissions
Section titled “Read the submissions”Project administrators can list a form’s submissions, 100 per page at most. Submissions do not appear in general lists.