Skip to content

[DOCS-14229] Update Forms documentation #36493

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
estherk15 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[DOCS-14229] Update Forms documentation #36493

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions config/_default/menus/main.en.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2942,6 +2942,16 @@ menu:
parent: actions_heading
identifier: forms
weight: 50000
- name: Form components
url: actions/forms/components/
parent: forms
identifier: forms_components
weight: 1
- name: Form responses
url: actions/forms/responses/
parent: forms
identifier: forms_responses
weight: 2
- name: Action Catalog
url: actions/actions_catalog/
pre: books
Expand Down
120 changes: 58 additions & 62 deletions content/en/actions/forms/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@
title: Forms
description: Build forms to collect input, analyze responses, and trigger automations.
disable_toc: false

further_reading:
- link: https://www.datadoghq.com/blog/datadog-forms
tag: Blog
Expand All @@ -18,99 +17,96 @@ Forms are in Preview. Click {{< ui >}}Request Access{{< /ui >}}, and fill in the

Datadog Forms allow you to collect input, analyze responses, and trigger automations in Datadog. Forms and their responses can be shared across your organization, allowing you to collect and analyze data with your team.

## Examples

Here are some ways you can use forms:
Some ways you can use forms:
- Scaffold services from predefined templates.
- Collect engineering feedback in an internal developer portal (IDP).
- Create service requests for security, platform, or IT teams, directly from employee form responses.
- Create service requests for security, platform, or IT teams directly from employee form responses.

## Create a form

When creating a form, you can use a template or start from scratch. Templates are starter forms that cover common use cases. They come loaded with a sample description and questions to help familiarize yourself with form elements. Templates also showcase best practices for setting up form elements.

{{< img src="/actions/forms/forms-blueprint-selected.png" alt="The form creation page with the IDP Feedback Survey selected" style="width:100%;" >}}
When creating a form, you can use a blueprint or start from scratch. Blueprints are starter forms that cover common use cases. They come loaded with a sample description and questions to help familiarize yourself with form elements, and some blueprints include a pre-configured automation. Blueprints include Developer Experience Survey, IDP Feedback, Case Management Service Request, Report an Incident, Bug Report, On-Call Escalation, Post-Incident Review, and more.

To create a form:
To create a form:
1. On the [Forms][1] page, click {{< ui >}}New Form{{< /ui >}}.
1. Select a template or {{< ui >}}Start with a blank form{{< /ui >}}, then click {{< ui >}}Continue{{< /ui >}}.
1. Select a blueprint or start with a blank form, then click {{< ui >}}Continue{{< /ui >}}.
1. Optionally, name your form and give it a description. Click {{< ui >}}Continue{{< /ui >}}.
1. New forms are auto-populated with placeholder components. To edit the form, click a placeholder component, or click the **<i class="icon-plus-circled-wui"></i>** icon to add a new component. Component types include short answer, paragraph, dropdown, checkboxes, ratings, and toggle. The following table lists the elements available inside components:
| Element | Description | Component Availability |
|----------------------------|---------------------------------------------------------------------|-----|
| {{< ui >}}Required{{< /ui >}} | Determines whether the question requires an answer from the respondent; required questions are marked with a red asterisk on forms. | All components |
| {{< ui >}}Field name{{< /ui >}} | The name of the field. Appears in the JSON version in [**Responses**][8]. Not visible to respondents. | All components |
| {{< ui >}}Placeholder{{< /ui >}} | The text the respondent sees before entering any text. | Short answer, paragraph, and dropdown |
| {{< ui >}}Default value{{< /ui >}} | The default item or text that is selected before the respondent makes a selection. | All components except ratings and checkboxes |
| {{< ui >}}Data{{< /ui >}} | The available options that respondents can choose from. | Dropdown and checkboxes |
| {{< ui >}}Questions{{< /ui >}} | The questions respondents are asked when rating their experience. | Ratings |
1. Click {{< ui >}}Save{{< /ui >}} to save your changes.
1. To add a new component, click **Add Component**, or on the Fields side panel, click the **+** icon. See [Form components][2] for the full list of component types and their options.
1. Click {{< ui >}}Save{{< /ui >}}.

To preview, share, and debug your form:
1. Click {{< ui >}}View{{< /ui >}} to display the form as it appears to respondents. Click {{< ui >}}Edit{{< /ui >}} to return to the creator view.
1. Click {{< ui >}}Share{{< /ui >}} to copy the form link.
1. Click {{< ui >}}View{{< /ui >}} to display the form as it appears to respondents. Click {{< ui >}}Edit{{< /ui >}} to return to the creator view.
1. Click {{< ui >}}Share{{< /ui >}} to copy the form link or configure sharing options.
1. In the {{< ui >}}Debug{{< /ui >}} section, you can:
- Click {{< ui >}}Form{{< /ui >}} to show a mini-preview of your form.
- Click {{< ui >}}Data Definition{{< /ui >}} to show the JSON version of the components' definition.
- Click {{< ui >}}UI Definition{{< /ui >}} to show the JSON version of the form's UI.

### Add automation
## Import a form

After creating a form, you can add an [action][4] or [workflow blueprint][5] that triggers automatically when a form is submitted.
1. From the [Forms][1] page, click a form.
1. Click {{< ui >}}Automation{{< /ui >}}.
1. Choose an action or blueprint.
1. The action or blueprint opens in a workflow canvas, where you can [edit it][2].
1. Click {{< ui >}}Create{{< /ui >}}.
You can import an existing form into Datadog from a JSON file or migrate directly from Google Forms.

**Note**: Because forms are powered by workflows, automations triggered by forms appear under [Workflow Automation][6]. Additionally, there is no charge associated with workflow executions that are triggered by a form.
To import a form:
1. On the [Forms][1] page, click {{< ui >}}New Form{{< /ui >}}.
1. Click {{< ui >}}Import a Form{{< /ui >}}.
1. Choose a source to import your form fields, then follow the prompts.

## Manage access
## Form settings

From the [Forms][1] page, click a form. In the {{< ui >}}Fields{{< /ui >}} panel, click the gear <i class="icon-cog-2"></i> icon to access the following settings:

| Setting | Description |
|---------|-------------|
| Accepting Responses | Toggle to set the form as active or inactive. When inactive, the form does not accept new responses. |
| Anonymous Responses | When enabled, respondent emails are not stored. |
| Manage Permissions | Configure who can view the form and submitted responses. See [Manage access](#manage-access). |
| Edit Theme | Change the form's color theme. |
| Clone Form | Create a copy of the form. |
| Export Form | Download the form as a JSON file. |

For more information on managing responses, see [Form responses][3].

## Share a form

By default, only the creator of a form can access it. To change the permissions on a form:
To configure sharing for a form:
1. From the [Forms][1] page, click a form.
1. Click the gear <i class="icon-cog-2"></i> icon.
1. To change who can see the form and submit answers, click {{< ui >}}Edit Form Permissions{{< /ui >}}.
1. To change who can see the submitted responses, click {{< ui >}}Edit Response Permissions{{< /ui >}}.
1. Click {{< ui >}}Share{{< /ui >}}.

The following sharing options are available:

## Analyze your data
| Option | Description |
|--------|-------------|
| Share within Datadog | Share the form with users in your Datadog organization. |
| Share with external users | Share the form with users outside your Datadog organization. Add recipients by email address or domain, or share with anyone with a link. You can configure an access expiration date for either option. |

### View in forms
To pause or remove external sharing, click {{< ui >}}Share{{< /ui >}}, then click {{< ui >}}Edit{{< /ui >}} and select {{< ui >}}Pause Sharing{{< /ui >}} or {{< ui >}}Delete Sharing{{< /ui >}}.

To view form responses in a table format:
## Add automation

After creating a form, you can add an [action][4] or [workflow blueprint][5] that triggers automatically when a form is submitted.
1. From the [Forms][1] page, click a form.
1. Click {{< ui >}}Responses{{< /ui >}}.
1. Click the edit icon on a response to view the JSON version.
1. At the top of the form, select {{< ui >}}Automation{{< /ui >}}.
1. Choose an action or blueprint.
1. The action or blueprint opens in a workflow canvas, where you can [edit it][6].
1. Click {{< ui >}}Create{{< /ui >}}.

**Note**: Datadog stores responses in a datastore, which is listed in [Datastores][7].
**Note**: Automations triggered by forms appear under [Workflow Automation][7]. There is no charge for workflow executions triggered by a form.

### View in a dashboard
## Manage access

To visualize form responses in a dashboard:
1. Navigate to the [DDSQL Editor][13].
1. In the {{< ui >}}Data{{< /ui >}} tab, click {{< ui >}}Actions Datastores{{< /ui >}}.
1. Select the datastore associated with your form, then click {{< ui >}}Insert into editor{{< /ui >}}.
1. Optionally, click the query's title to rename it.
1. Click {{< ui >}}Save{{< /ui >}}.
1. [Create a dashboard][9], then [add a widget][14]. For forms, all widgets except Timeseries are supported.
1. When [defining the metric][15], select {{< ui >}}DDSQL Editor{{< /ui >}} and the datastore query you created earlier.
1. Finish [configuring your widget][12], then click {{< ui >}}Save{{< /ui >}}.
By default, only the creator of a form can access it. To change the permissions on a form:
1. From the [Forms][1] page, click a form.
1. In the {{< ui >}}Fields{{< /ui >}} panel, click the gear <i class="icon-cog-2"></i> icon.
1. To change who can see the form and submit answers, click {{< ui >}}Edit Form Permissions{{< /ui >}}.
1. To change who can see the submitted responses, click {{< ui >}}Edit Response Permissions{{< /ui >}}.

## Further reading

{{< partial name="whats-next/whats-next.html" >}}

[1]: https://app.datadoghq.com/actions/forms
[2]: /actions/workflows/build/#build-a-workflow-with-the-workflow-builder
[3]: https://app.datadoghq.com/workflow/blueprints/scaffold-new-service
[2]: /actions/forms/components/
[3]: /actions/forms/responses/
[4]: https://app.datadoghq.com/actions/action-catalog/
[5]: https://app.datadoghq.com/workflow/blueprints
[6]: https://app.datadoghq.com/workflow
[7]: https://app.datadoghq.com/actions/datastores
[8]: /actions/forms/#view-in-forms
[9]: /dashboards/#get-started
[10]: /dashboards/widgets/#add-a-widget-to-your-dashboard
[12]: /dashboards/widgets/configuration/
[13]: https://app.datadoghq.com/ddsql/editor
[14]: /dashboards/widgets/#add-a-widget-to-your-dashboard
[15]: /dashboards/querying/#define-the-metric
[6]: /actions/workflows/build/#build-a-workflow-with-the-workflow-builder
[7]: https://app.datadoghq.com/workflow
79 changes: 79 additions & 0 deletions content/en/actions/forms/components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: Form components
description: Reference for form component types, element options, validation rules, and conditional fields.
further_reading:
- link: /actions/forms/
tag: Documentation
text: Forms
---

## Overview

Forms are made up of components, which are individual question or input blocks. Each component has a set of configurable elements and optional validation rules. You can also set conditional logic on individual fields to show or hide them based on a respondent's previous answers.

## Component types

When building a form, click **Add Component** to get started. The following component types are available:

| Component | Description |
|-----------|-------------|
| Short answer | A single-line text input. |
| Paragraph | A multi-line text input. |
| Number input | A numeric input field. |
| Dropdown | A list of options where the respondent selects one. Supports static options or [dynamic options](#dynamic-dropdown-options). |
| Radio buttons | A list of options where the respondent selects one. |
| Checkboxes | A list of options where the respondent can select multiple. |
| Rating | A set of rating questions. |
| Toggle | A boolean on/off switch. |
| Ranking | A ranked ordering of a list of options. |
| Date picker | A calendar date selector. |
| Image | An image embedded in the form for context or instructions. |

## Component elements

Each component has a set of configurable elements in the component editor:

| Element | Description |
|-----|-------------|
| {{< ui >}}Required{{< /ui >}} | Toggle to determine whether the question requires an answer. Required questions are marked with a red asterisk. |
| {{< ui >}}Advanced{{< /ui >}} | Configure the placeholder text and default value for the component. |
| {{< ui >}}Rules{{< /ui >}} | Configure validation rules to restrict the values respondents can submit. See [Validation rules](#validation-rules). |
| {{< ui >}}Conditions{{< /ui >}} | Configure conditional logic to show or hide the component based on a respondent's previous answers. See [Conditional fields](#conditional-fields). |

## Validation rules

You can configure validation rules on individual components to restrict the values respondents can submit.

For short answer and paragraph components, you can set a minimum and maximum character length, or restrict input to a specific pattern: email, URL, alphanumeric, or a custom regex.

For number input components, you can set a minimum and maximum value.

## Conditional fields

Conditional fields let you show or hide a question based on a respondent's answer to a previous question. For example, you can show a follow-up question only when a respondent selects a specific option from a dropdown.

To configure a conditional field:
1. Click a component to open its editor panel.
1. Click {{< ui >}}Conditions{{< /ui >}}.
1. Click {{< ui >}}Add Condition{{< /ui >}} and define the rule.
1. Click {{< ui >}}Save{{< /ui >}}.

## Dynamic dropdown options

Dropdown components can fetch options dynamically from Datadog tag values at runtime. Dynamic options update automatically as your tag values change, without requiring manual edits to the form.

To configure dynamic options:
1. Click a dropdown component to open its editor panel.
1. Click {{< ui >}}Advanced{{< /ui >}}.
1. Under {{< ui >}}Options source{{< /ui >}}, select {{< ui >}}Dynamic{{< /ui >}}.
1. Select the tag key to use as the source of options.
1. Optionally, configure substring filtering or cross-tag scope constraints.
1. Click {{< ui >}}Save{{< /ui >}}.

## JSON editor

In addition to the visual component editor, you can edit the underlying JSON Schema of the form directly. In the {{< ui >}}Fields{{< /ui >}} panel, click the <i class="icon-dev-code"></i> code icon to open the JSON code editor.

## Further reading

{{< partial name="whats-next/whats-next.html" >}}
63 changes: 63 additions & 0 deletions content/en/actions/forms/responses.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: Form responses
description: View, analyze, and manage form responses using Datadog Sheets, dashboards, and response settings.
disable_toc: false
further_reading:
- link: /actions/forms/
tag: Documentation
text: Forms
---

## Overview

{{< img src="/actions/forms/forms_responses.png" alt="Example of viewing form responses in Datadog" style="width:100%;" >}}

After respondents submit a form, Datadog automatically stores their answers and makes them available for review, analysis, and visualization. You can view raw responses in a table, get AI-generated summaries and visual analytics by question type, or query response data in a dashboard.

## View responses

To view form responses, from the [Forms][1] page, click a form, then click {{< ui >}}Responses{{< /ui >}}.

Each component displays a corresponding response analysis block, which may include an AI-generated summary, raw individual responses, and visual analytics that vary by component type (for example, bar charts for dropdowns and checkboxes, distribution charts for ratings).

**Note**: Datadog stores responses in [Datastores][2].

## Open in Datadog Sheets

You can open form responses in Datadog Sheets to filter, sort, and analyze them in a spreadsheet view. To open responses in Sheets:
1. From the [Forms][1] page, click a form.
1. Click {{< ui >}}Responses{{< /ui >}}.
1. Click {{< ui >}}Open in Sheets{{< /ui >}}.

## View in a dashboard

To visualize form responses in a dashboard:
1. Navigate to the [DDSQL Editor][3].
1. In the {{< ui >}}Data{{< /ui >}} tab, click {{< ui >}}Actions Datastores{{< /ui >}}.
1. Select the datastore associated with your form, then click {{< ui >}}Insert into editor{{< /ui >}}.
1. Optionally, click the query's title to rename it.
1. Click {{< ui >}}Save{{< /ui >}}.
1. [Create a dashboard][4], then [add a widget][5]. All widgets except Timeseries are supported for forms.
1. When [defining the metric][6], select {{< ui >}}DDSQL Editor{{< /ui >}} and the datastore query you created earlier.
1. Finish [configuring your widget][7], then click {{< ui >}}Save{{< /ui >}}.

## Response settings

To configure response settings, in the {{< ui >}}Fields{{< /ui >}} panel, click the gear <i class="icon-cog-2"></i> icon and select an option:

| Setting | Description |
|---------|-------------|
| Accepting Responses | Toggle to enable or disable response collection. You can also set an end date to automatically stop accepting responses on a specific date. |
| Anonymous Responses | When enabled, respondent emails are not stored. |

## Further reading

{{< partial name="whats-next/whats-next.html" >}}

[1]: https://app.datadoghq.com/actions/forms
[2]: https://app.datadoghq.com/actions/datastores
[3]: https://app.datadoghq.com/ddsql/editor
[4]: /dashboards/#get-started
[5]: /dashboards/widgets/#add-a-widget-to-your-dashboard
[6]: /dashboards/querying/#define-the-metric
[7]: /dashboards/widgets/configuration/
Binary file added static/images/actions/forms/forms_responses.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading