docs - actions (#28473)

docs/README.md

@@ -89,6 +89,7 @@ Metabase's reference documentation.
 - [Interactive dashboards](./dashboards/interactive.md)
 - [Charts with multiple series](./dashboards/multiple-series.md)
 - [Dashboard subscriptions](./dashboards/subscriptions.md)
+- [Actions on dashboards](./dashboards/actions.md)
 
 ### Data modeling
 
@@ -99,6 +100,13 @@ Metabase's reference documentation.
 - [Formatting defaults](./data-modeling/formatting.md)
 - [Segments and metrics](./data-modeling/segments-and-metrics.md)
 
+### Actions
+
+- [Actions overview](./actions/start.md)
+- [Introduction to actions](./actions/introduction.md)
+- [Basic actions](./actions/basic.md)
+- [Custom actions](./actions/custom.md)
+
 ### Organization
 
 - [Organization overview](./exploration-and-organization/start.md)

docs/actions/basic.md

+---
+title: Basic actions
+---
+
+# Basic actions
+
+Basic actions are premade [actions](./introduction.md) that do things that people typically want to do when interacting with a database.
+
+Basic actions auto-track the schema of primary source table backing the model. By auto-track the schema, we mean that Metabase will create forms for people to fill out that include all of the fields in the model from the primary source table that underlies that model, and the action will update whenever you change the model. Basic actions are only be available for models that include a single primary key.
+
+Custom columns are also excluded because they are computed columns; if you want to change a custom column's values, you should update the values in the columns used to compute that column.
+
+If you only want to give people the option to update a subset of columns, you can write a [custom action](./custom.md).
+
+## Creating basic actions
+
+Once actions are enabled, you can create basic actions on a new or existing [model](../data-modeling/models.md).
+
+1. Select a model and click on the **info** button, then click on **Model detail**.
+2. On the model detail page, click on the **Actions** tab.
+3. Click on the **...** next to the **New Action** and select **Create basic actions**.
+
+## Basic action types
+
+![Basic actions](./images/basic-actions.png)
+
+Basic actions include:
+
+- [Update](#update)
+- [Delete](#delete)
+- [Create](#create)
+
+By default, none of the input fields are required for basic actions.
+
+### Update
+
+The update action will present people with a form with editable fields for each column in the primary source table that's also included in the model. So if the model's source table has columns a, b, c, and d, but the model only includes columns a, b, and c, then the form will only show input fields for columns a, b, and c.
+
+When setting up an update action on a dashboard, you can either prompt the person to fill in a value for each field, or have a field automatically filled in via parameters (such as values set in dashboard filters).
+
+### Delete
+
+The Delete action will create a form that prompts people for an ID, and will delete the record (row) in the underlying table that backs the model.
+
+### Create
+
+The Create actions is the `INSERT INTO` action. The Create action will present a form with editable fields for each column in the primary source table that's also included in the model. So if the model's source table has columns a, b, c, and d, but the model only includes columns a, b, and c, then the form will only show input fields for columns a, b, and c.
+
+Once filled out, the action will insert the record into the primary table that underlies the model.
+
+## Basic actions on dashboards
+
+When setting up actions on a dashboard, you can either prompt the person to fill in a value for each field, or have a field automatically filled in via parameters (such as values set in dashboard filters). See [Actions in dashboards](../dashboards/actions.md).
+
+## Archiving basic actions
+
+Because basic actions are made of magic, you cannot archive them. You can just toggle them on or off. From the model detail page, next the **New action** button, click on the **...** menu and click **Disable basic actions**.
+
+## Further reading
+
+- [Introduction to actions](./introduction.md)
+- [Custom actions](./custom.md)

docs/actions/custom.md

+---
+title: Custom actions
+---
+
+## Custom actions
+
+Write SQL to update records in your databases.
+
+![Custom action](./images/custom-action.png)
+
+## Creating a custom action
+
+> You must be in a group with Native query editing access to create an action
+
+There are two ways to create a custom action:
+
+1. Click the **+ New** > **Action**. When you save your action, you'll be prompted to associate that action with a model. (NOTE: the **Action** option will only show up in the **+ New** menu if you've first created, or have access to, a model in Metabase.)
+2. Via the model detail page: from a model, click on the **info** button in the upper right. In the upper right of the sidebar, click **Model detail** > **Actions** > **New action**.
+
+## Custom action editor
+
+Here you can write your own code to create an action, like writing an action that would only update a subset of the columns in a model.
+
+For example, you could write an action that would update the `plan` column for a record in the `Invoices` table in the Sample Database:
+
+```
+{% raw %}
+UPDATE invoices
+SET plan = {{ plan }}
+[[, payment = {{ payment }}]]
+WHERE id = {{ id }}
+{% endraw %}
+```
+
+The above code will create a form that prompts people to input updated values for the (required) `plan` field and optionally the `payment` field for a given record specified by `ID`. The code in brackets `[[ ]]` makes it optional: the enclosed statement will only run if someone inserts a value in the payment field.
+
+## Field types for action variables
+
+For each {% raw %}{{ variable }}{% endraw %} that you set in an action, you'll need to set the field type.
+
+Each of these variable field types present different options.
+
+If you don't require a variable, you can optionally specify a default value for Metabase to use in cases where people don't fill out the field.
+
+You can include placeholder text for all fields in the action form.
+
+**Text**
+
+- Text
+- Long text
+- Dropdown
+- Inline select
+
+**Number**
+
+- Number
+- Dropdown
+- Inline select
+
+**Date**
+
+- Date
+- Date + Time
+
+**Category**
+
+- Dropdown
+- Inline select
+
+For both **Dropdown** and **Inline select**, you can specify a list of options to present on the form, with each option on its own line.
+
+![Dropdown select](./images/dropdown.png)
+
+## Action settings
+
+From the model detail page, click on the **...** next to the action. Once in the action editor, click on the **gear** icon to bring up the action settings.
+
+### Make public
+
+Creates a publicly shareable link to the action form.
+
+![Public action form](./images/public-form.png)
+
+### Set a success message
+
+Here you can edit the success message, which is the message Metabase will display in the toast that pops up after Metabase hears back from the database that everything went smoothly.
+
+If something goes wrong, Metabase will display the error message it received from the database.
+
+## Further reading
+
+- [Introduction to actions](./introduction.md)
+- [Basic actions](./basic.md)

docs/actions/introduction.md

+---
+title: Introduction to actions
+---
+
+# Introduction to actions
+
+> For now, actions are only available for PostgreSQL and MySQL
+
+![Example action](./images/example-action.png)
+
+**Actions** are entities in Metabase that let you build custom forms and business logic.
+
+## What are actions?
+
+Actions let you write parameterized SQL that writes back to your database. Actions can be attached to [buttons on dashboards](../dashboards/actions.md) to create custom workflows. You can even publicly share the parameterized forms they generate to collect data.
+
+Here are a few ideas for what you can do with actions:
+
+- Create a customer feedback form and embed it on your website.
+- Mark the customer you’re viewing in a dashboard as a VIP.
+- Let team members remove redundant data.
+
+## Enabling actions
+
+To enable actions for a database connection, admins should click on the gear icon in the upper right and navigate to **Admin settings** > **Databases**, then click on the database you want to create actions for. On the right side of the connection settings form, toggle the **Model actions** option. 
+
+For actions to work, the database user account (the account you're using to connect to the database) must have write permissions. And for now, actions are only supported on PostgreSQL, MySQL, and H2 databases.
+
+## Who can use actions
+
+Actions are associated with models, so you'll need to have created (or access to) at least one model before you can start using actions.
+
+- **To create or edit an action**, a person must be in a group with Native query editing privileges for the relevant database.
+-  **To run an action**, all you need is view access to the action's model or dashboard (or a link to a public action).
+
+## Types of actions
+
+There are two types of actions:
+
+- [Basic](./basic.md)
+- [Custom](./custom.md)
+
+## Running actions
+
+There are multiple ways to run actions:
+
+- [From the model details page](../data-modeling/models.md#model-detail-page) by clicking the **run** button.
+- From a [public form](./custom.md#make-public) of an action.
+- From a [button on dashboard](../dashboards/actions.md).
+

docs/actions/start.md

+---
+title: Actions overview
+---
+
+# Actions overview
+
+Actions let you write parameterized SQL that can then be attached to buttons, clicks, or even added on the page as form elements.
+
+## [Introduction to actions ](./introduction.md)
+
+Use actions to update your data based on user input or values on the page.
+
+## [Basic actions](./basic.md)
+
+Metabase will create basic actions that auto-track a model's schema.
+
+## [Custom actions](./custom.md)
+
+Write SQL to create new actions.

docs/dashboards/actions.md

+---
+title: Actions on dashboards
+---
+
+# Actions on dashboards
+
+![Dashboard with filter, action button, and detail card view](./images/dashboard-filter-action.png)
+
+To put [actions](../actions/start.md) in action, you can combine them with a [model](../data-modeling/models.md) and a [filter](./filters.md) on a dashboard.
+
+## Adding an action to a dashboard
+
+Visit a dashboard page and click on the **pencil** icon, then click on the **box with a mouse pointer** to add an action.
+
+Metabase will add an action button to the dashboard grid, and open a sidebar with the buttons settings.
+
+### Button text
+
+A label explaining what the button does, e.g., "Ignition".
+
+### Button variant
+
+You can select from a variety of handsome buttons:
+
+- Primary
+- Outline
+- Danger
+- Success
+- Borderless
+
+![Button types](./images/buttons.png)
+
+## Connecting an action to a dashboard filter
+
+Many types of actions rely on knowing the entity IDs for the model to determine which records to update or delete. You can add a filter to the dashboard to filter on ID, and wire up that filter to the action button.
+
+![Wiring up an action button to a dashboard filter](./images/filter-to-action-button.png)
+
+If you also wire that filter up to the model cards on the dashboard, you can filter for individual records, view them in the model cards, and update them with action buttons with the ID already filled in:
+
+![Button form](./images/button-form.png)
+
+ You can add as many buttons as you want, and wire them up to one or more filters.
+
+ ## Further reading
+
+ - [Actions](../actions/start.md)
\ No newline at end of file

docs/dashboards/start.md

@@ -25,3 +25,7 @@ Combine multiple questions on a single chart.
 ## [Dashboard subscriptions](./subscriptions.md)
 
 Set up a dashboard to email or Slack its results on a schedule.
+
+## [Actions on dashboards](./actions.md)
+
+Add action buttons to dashboards.

docs/data-modeling/models.md

@@ -50,9 +50,36 @@ Models you create are automatically [pinned to the current collection](../explor
 
 ![Turn a saved question into a model](./images/turn-into-a-model.png)
 
+## Model detail page
+
+To view a model's detail page:
+
+- From a collection: click on the **book** icon next to a model.
+- From a model: click on the **info** button in the upper right, then click **Model details**.
+
+![Model detail page](./images/model-detail.png)
+
+Here you'll see several tabs:
+
+- **Used by**: lists the items based on the model.
+- **Schema**: lists the fields in the model.
+- **Actions**: lists the actions in the model, and allows you to create new [actions](../actions/start.md).
+
+The model detail page also shows some basic info about the model:
+
+- Description
+- Contact (who wrote the model)
+- Backing table(s)
+
+To start a new question based on the model, click **Explore**.
+
+To edit the model's underlying query, click **Edit definition**.
+
+You can also edit the model's metadata.
+
 ## Add metadata to columns in a model
 
-Metadata is the secret sauce of models. When you write a SQL query, Metabase can display the results, but it can't "know" what kind of data it's returning (like it can with questions built using the query builder). What this means in practice is that people won't be able to drill-through the results, because Metabase doesn't understand what the results are. With models, however, you can tell Metabase what kind of data is in each returned column so that Metabase can still do its drill-through magic. Metadata will also make filtering nicer by showing the correct filter widget, and it will help Metabase to pick the right visualization for the results.
+Metadata is the secret sauce of models. When you write a SQL query, Metabase can display the results, but it can't "know" what kind of data it's returning (like it can with questions built using the query builder). What this means in practice is that people won't be able to drill-through the results, because Metabase doesn't understand what the results are. With models, however, you can tell Metabase what kind of data is in each returned column so that Metabase can still do its drill-through magic. Metadata will also make filtering nicer by showing the correct filter widget, and it will help Metabase to pick the right visulization for the results.
 
 If you only set one kind of metadata, set the **Column type** to let Metabase know what kind of data it's working with.
 

docs/questions/sharing/public-links.md

@@ -16,7 +16,7 @@ Sometimes you'll want to share a dashboard or question with someone who isn't a
 
 In order to share Metabase items like questions and dashboards via a public link or an embedded iframe, an admin needs to enable public sharing for that Metabase instance by going to **Settings gear icon** > **Admin settings** > **Public sharing**.
 
-Once toggled on, the **Public sharing** section will display Metabase questions and dashboards with active public links. To deactivate a public link, click **Revoke link**.
+Once toggled on, the **Public sharing** section will display Metabase questions, dashboards, and actions with active public links. To deactivate a public link, click the **X** in the **Revoke link** column for that item.
 
 ## Enable sharing on your saved question or dashboard
 

docs/start.md

+# Actions
+
+## Actions