Skip to content
Snippets Groups Projects
Unverified Commit 2e00a28d authored by Jeff Bruemmer's avatar Jeff Bruemmer Committed by GitHub
Browse files

docs - actions (#28473)

parent 4853d09f
No related branches found
No related tags found
No related merge requests found
Showing
with 315 additions and 2 deletions
...@@ -89,6 +89,7 @@ Metabase's reference documentation. ...@@ -89,6 +89,7 @@ Metabase's reference documentation.
- [Interactive dashboards](./dashboards/interactive.md) - [Interactive dashboards](./dashboards/interactive.md)
- [Charts with multiple series](./dashboards/multiple-series.md) - [Charts with multiple series](./dashboards/multiple-series.md)
- [Dashboard subscriptions](./dashboards/subscriptions.md) - [Dashboard subscriptions](./dashboards/subscriptions.md)
- [Actions on dashboards](./dashboards/actions.md)
### Data modeling ### Data modeling
...@@ -99,6 +100,13 @@ Metabase's reference documentation. ...@@ -99,6 +100,13 @@ Metabase's reference documentation.
- [Formatting defaults](./data-modeling/formatting.md) - [Formatting defaults](./data-modeling/formatting.md)
- [Segments and metrics](./data-modeling/segments-and-metrics.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
- [Organization overview](./exploration-and-organization/start.md) - [Organization overview](./exploration-and-organization/start.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)
---
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/images/basic-actions.png

174 KiB

docs/actions/images/custom-action.png

134 KiB

docs/actions/images/dropdown.png

167 KiB

docs/actions/images/example-action.png

132 KiB

docs/actions/images/public-form.png

106 KiB

---
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).
---
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.
---
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/images/button-form.png

127 KiB

docs/dashboards/images/buttons.png

34.6 KiB

docs/dashboards/images/dashboard-filter-action.png

90.4 KiB

docs/dashboards/images/filter-to-action-button.png

108 KiB

...@@ -25,3 +25,7 @@ Combine multiple questions on a single chart. ...@@ -25,3 +25,7 @@ Combine multiple questions on a single chart.
## [Dashboard subscriptions](./subscriptions.md) ## [Dashboard subscriptions](./subscriptions.md)
Set up a dashboard to email or Slack its results on a schedule. 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/images/model-detail.png

133 KiB

...@@ -50,9 +50,36 @@ Models you create are automatically [pinned to the current collection](../explor ...@@ -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) ![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 ## 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. If you only set one kind of metadata, set the **Column type** to let Metabase know what kind of data it's working with.
......
...@@ -16,7 +16,7 @@ Sometimes you'll want to share a dashboard or question with someone who isn't a ...@@ -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**. 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 ## Enable sharing on your saved question or dashboard
......
# Actions
## Actions
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment