diff --git a/docs/docs/user-guide/incidents/forms.mdx b/docs/docs/user-guide/incidents/forms.mdx new file mode 100644 index 000000000000..7bebd89dba8c --- /dev/null +++ b/docs/docs/user-guide/incidents/forms.mdx @@ -0,0 +1,48 @@ +--- +description: How to create custom incident forms +--- + +# Forms + +## Creating a custom form + +Within Dispatch, admins can create a custom form under Settings -> (choose Project) -> Incident / Form Types. This brings up a table of existing form types (if any). Click on the NEW button to create a new form type. + +### Form schema + +The form schema takes a JSON array of form objects of the following type: + +| Attribute | Possible values | Notes | +|-----------|-----------------------------|-----------------------------------| +| type | boolean, select, text, date | | +| title | | this is the question | +| if | | conditional (see below) | +| name | | unique identifier string | +| multiple | true, false | only for select | +| options | | list of options / only for select | +| hint | | shown as small text (optional) | + +The following fields are required for each form object: `type`, `title`, and `name`. For `select` types, there must be a corresponding `options` attribute. + +Note: be sure to set the form type to "Enabled" so that it will appear in the forms tab in the incident. + +#### Conditionals + +The `if` attribute can be a complex JavaScript boolean expression. Refer to other form items using the format `$` where `` is the unique name identifier. + +##### Example + +```[ { "type": "boolean", "title": "Is this a good form?", "name": "good_form", "hint": "Check if you like"}, + { "type": "select", "if": "$good_form", "title": "How good?", "options": [ "Very much", "A lot", "It's ok" ], "multiple": false, "name": "like_level"}, + { "type": "text", "if": "$good_form && $like_level && $like_level.includes('A lot')", "title": "Provide more feedback", "name": "feedback"} + ]``` + +## Fill out a form in an incident + +After an incident is opened, go to the View/Edit panel and select the Forms tab at the top. This view will list all of the forms that have been filled out so far. They can either be in the Draft or Completed state. Users can either edit an existing form or create a new one based on any of the enabled form types created as above. + +While a form is being completed, the user can **Cancel** to discard any changes, **Save as Draft** to save the filled in information and set as _Draft_, or **Submit** to save and set as _Completed_. + +## Attorney review + +A new tab on the left "Forms" lists all of the _Draft_ and _Completed_ forms for leadership and attorney review. For each form, users can view/edit, delete, and a special **Attorney Review** option. This option shows relevant incident details and the values filled out in the form. It also provides an attorney status dropdown and two new fields for attorney notes and open questions.