# Using custom actions for filtering and navigating Custom actions To add interactive options for dashboard subscribers (Quick readers), you create custom actions on one or more visuals in your analysis. Enhancing dashboards with custom actions helps people explore data by adding more context from within the dataset. It can make it easier to drill into the details and to find new insights in the same dashboard, a different dashboard, or a different application. You can add up to 10 custom actions to each visual in a dashboard. Before you begin, it's helpful to do some planning. For example, identify fields that are good candidates for filtering, for opening a different sheet, for opening a URL, or for sending email. For each sheet, identify the widgets that display these fields. Then decide which widgets are going to contain actions. It's also a good idea to create a naming scheme so the names of the actions are consistent throughout the entire analysis. Consistent names make it easier for the person using your analysis to figure out what the action will do, plus they make it easier for you to maintain actions that you might be duplicating throughout the analysis. Actions only exist on the dashboard widget where you create them and they work in the context of that widget's parent sheet and child fields that it displays. You can create actions only on specific types of widget: visuals and insights. You can't add them to other widgets, for example filter or list controls. Custom actions can only be activated from the widget where you create them. To activate an action, the person using the analysis can left-click (select) or right-click (use the context menu) on a data point. A *data point* is an item in the dataset, for example a point on a line chart, a cell in a pivot table, a slice on a pie chart, and so on. If the person clicks a visual element, the *select* action is activated. This is the action that is currently a member of the **On select** category of the **Actions** in an analysis. If the person instead right-clicks a visual element, they can choose from a list of *menu* actions. Any action listed is currently a member of the **Menu option** category of the **Actions** in an analysis. The **On select** category can contain one and only one member action. By default, the first action you create becomes the select action—the one activated by left-clicking. To remove an action from the **On select** category, change the action's **Activation** setting to **Menu option**. After you save that change, you can set a different action's **Activation** setting to **Select**. You can choose from three **Action types** when you configure an action: + **Filter action** – Filter data included in visual or in the entire sheet. By default, filters are available for all fields in the parent visual. Cascading filters are enabled by default. Filter actions work across multiple datasets by using automatically generated field mappings. If the analysis uses more than one dataset, you can view the automatically generated field mappings for fields that exist in multiple datasets. To do this, choose ****View field mapping**** at the end of the action settings, while you're editing an action. If you are viewing a list of actions, choose ****View field mapping**** from the menu for each action. The field mappings appear in a new screen that shows the mapping between the initial dataset and all the other datasets in the visual. If no fields are automatically mapped, a message displays with a link to [Mapping and Joining Fields](mapping-and-joining-fields.md). + **Navigation actions** – Enable navigation between different sheets in the same analysis. + **URL actions** – Open a link to another web page. If you want to open a different dashboard, use a URL action. You can use a URL action to send data points and parameters to other URLs. You can include any available field or parameter. If the URL uses the `mailto` scheme, running the action opens your default email editor. **Topics** + [ # Adding one-click interactive filters ](quick-actions.md) + [ # Creating and editing custom actions in Amazon Quick Sight ](custom-actions.md) + [ # Repairing custom actions ](repairing-custom-actions.md) + [ # Understanding field mapping for custom actions in Amazon Quick Sight ](quicksight-actions-field-mapping.md) # Adding one-click interactive filters Adding interactive filters *One-click interactive filtering* provides point-and-click filtering that cascades from the clickable visual to all the other visuals and insights on a sheet. Add this to your analysis to start with summaries and drill down into the metrics, all within the same dashboard sheet. After you set this up, when you click a data point (for example, a point in a line chart), you instantly filter using all mapped fields on all the other visuals on that sheet. If you have multiple datasets, all target fields must be mapped for this to work. Also, you can only have one action that works by clicking a data point; all other actions work from the context menu. Use the following procedure to create a one-click filter in an analysis. **To create a one-click filter on a visual or insight** 1. In your analysis, choose a visual or insight that you want to add interactive filtering to. 1. Choose **Actions** from the Menu options dropdown in the upper right corner. 1. Choose **Filter same-sheet visuals.** Doing this immediately adds one-click filtering. 1. Repeat this process for each visual that you wish to make interactive. # Creating and editing custom actions in Amazon Quick Sight Creating and editing custom actions You create one action for each task that you want to be able to add to a visual. The actions you create become part of the functionality of each visual or insight. The following table defines when to use each type of action. | Action to perform | Type of action | | --- | --- | | Add or customize an interactive filter action, including one-click filters | Filter action | | Open another sheet in the same dashboard | Navigation action | | Open a sheet in a different dashboard in the same Amazon Web Services account | URL action | | Open a URL (`https`, `http`) | URL action | | Send an email (`mailto`) | URL action | You can set the following attributes and options for a custom action: + ****Action name**** – This is a descriptive name that you choose for the action. By default, actions are named **Action 1**, **Action 2**, and so on. If your custom action is activated from a context menu, this name displays in the menu when you right-click on a data point. To make the action name dynamic, you can parameterize it. Use the plus icon near the action name header to display a list of available variables. Variables are enclosed in angle brackets `<< >>`. Parameters are prefixed with a `$` , for example `<<$parameterName>>`. Field names have no prefix, for example `<>`. + ****Activation**** – Available options are **Select** or **Menu option**. To use an action, you can *select* the data point (left-click) or navigate to the *menu option* in the context menu (right-click). Navigation actions and URL actions listed in the middle of the context menu, just above **Color** options. Actions that are activated by menu are also available from the legend on a visual. + ****Action type**** – The type of action that you want. Settings that are specific to an action type only display after you choose the action type. + **Filter action** settings include the following: + ****Filter scope**** – The fields to filter on. To filter on all fields, choose **All fields**. Otherwise, choose **Select fields** and then turn off the items you don't want to target. The default is **All fields**. + ****Target visuals**** – The dashboard widgets to target. To apply the filter to all of them, choose **All visuals**. Otherwise, choose **Select visuals** and then turn off the items you don't want to target. When you apply a filter action to other visuals, the effect is called *cascading filters*. The default is **All visuals**. A cascading filter applies all the visuals that are set up in the **Target visuals** section of a specific filter action. Amazon Quick Sight initially evaluates your visuals and preconfigures the settings for you. But you can change the defaults if you wish to do so. You can set up multiple cascading filters on multiple visuals in the same sheet or analysis. When you are using the analysis or dashboard, you can use multiple cascading filters at the same time, although you activate each of these one at a time. A filter action requires at least one target visual, because a filter action requires a source and a target. To filter only the current visual, create a regular filter instead by choosing **Filter** at left. + **Navigation action** settings include the following: + ****Target sheet**** – The sheet to target. + ****Parameters**** – The parameters to send to the target sheet. Choose the plus icon to add an existing parameter. + **URL action** settings include the following: + ****URL**** – The URL to open. URL actions can be deep links into another application. Valid URL schemes include `https`, `http`, and `mailto`. + ****\$1** (Values)** – (Optional) The parameters to send to the target URL. Parameter names start with a `$`. The parameters on both the sending and the receiving end must match in name and data type. + ****Open in**** – Where to open the URL. You can choose **New browser tab**, **Same browser tab**, or **New browser window**. Some types of actions enable you to include values from parameters or fields that are available in the visual or insight. You can type these in manually or choose **\$1** to select from a list. For the custom action to work, every field and parameter it references must be actively in use in the parent widget. Use the following procedure to create, view, or edit a custom action in an analysis. **To create, view, or edit a custom action** 1. With your analysis open, choose **Actions** from the **Menu options** dropdown in the upper right corner. The existing actions, if any, display by activation type. To turn an existing action on or off, use the box to the right of the action's name. 1. (Optional) To edit or view an existing action, choose the menu icon next to the name of the action. To edit the action, choose **Edit**. To delete it, choose **Delete**. 1. To create a new action, choose either one of the following: + The add icon near the **Actions** heading + The **Define a custom action** button 1. For **Action name**, define an action name. To make the action name dynamic, use the plus icon to add parameter or field values. 1. For **Activation**, choose how the action runs. 1. For **Action type**, choose the action type you want to use. 1. For a **Filter action**, do the following: 1. For **Filter scope**, choose the scope of the filter. 1. For **Target visuals**, choose how far the filter cascades 1. For a **Navigation action**, do the following: 1. For **Target sheet**, choose the target sheet. 1. For **Parameters**, choose the plus icon near the **Parameters** heading, select a parameter, and then choose a parameter value. You can choose all values, enter custom values, or select specific fields. 1. For a **URL action**, do the following: 1. For **URL**, enter the hyperlink. 1. Choose the plus icon near the **URL** heading. Then, add variables from the list. 1. For **Open in**, choose how to open the URL. 1. After you are finished with the action, choose one of the following at the bottom of the **Actions** panel (you might need to scroll down): + **Save** – Save your selections, and create the custom action. + **Close** – Close this custom action and discard your changes. + **Delete** – Delete this action. # Repairing custom actions For a custom action to work, every field and parameter it references must be active in the parent widget. If a field is missing from the source widget, or if a parameter is missing from the analysis, the action for that field or parameter becomes unavailable. Menu actions are no longer included in the context menu. Select actions no longer respond to attempts to interact. However, in all other ways, the widget continues to function. No error displays to your users. You can fix broken filter actions and URL actions by adding the missing fields back to the broken visual or insight. The following procedure explains how to fix an action that broke because someone removed a field or parameter without updating the action. These steps provide basic guidance how to fix this issue. However, use your own judgment on how or if you should make changes to the analysis. If you're not sure, it's better to ask a Amazon Quick administrator for assistance before you change anything. For example, there might be a way to restore a previous version of the analysis, which might be safer if you aren't sure what happened to it. **To remove a field from a broken action** 1. From the start page, choose **Analyses**. Then choose the analysis to fix. 1. Choose the visual or insight where the action no longer works. Make sure that it's highlighted on the sheet. 1. Choose **Actions** from the Menu options dropdown in the upper right corner. 1. Locate the action you want to fix and choose **Edit**. 1. If the action type is **Filter action**, and you see an error that says *the field used by this action was removed*, check the settings for **Filter scope**. **Selected fields** can only display fields that are in the visual. To disable selected fields that are removed, choose one of the following: + Change the **Filter scope** setting to **All fields**. Doing this enables the widget to filter on every field. + If you want to use a list of **Selected fields**, verify the list of fields. If you need to include another field, you need to add it to the visual first. 1. If the action type is **Navigation action**, follow the guidance on the error message, which reflects the type of change that caused the error. 1. If the action type is **URL action**, check the **URL** setting for variables marked with double angle brackets (`<`). Open the list of available variables by choosing the plus icon. Remove any fields or parameters that aren't in the list. Be sure you also remove the matching *URL parameter* and it's separator (`?` for the first URL parameter, or `&` for subsequent parameters). The following examples show (in **bold**) which part is removed if you were removing the field named `Product` from the visual. ``` https://www.example.com/examplefunction?q=< ``` ``` https://www.example.com/examplefunction?q=<&uact=<<$CSN> ``` ``` https://www.example.com/examplefunction?pass=yes&q=<+<&oq=<+<&uact=<<$CSN> ``` Make sure to test the new URL. 1. (Optional) To delete the action, scroll to the end and choose **Delete**. 1. When you are finished, confirm your changes to the action. Scroll to the bottom of the **Action** pane and choose **Save**. If the error also exists in an associated dashboard, share and publish the dashboard again to propagate the fix. # Understanding field mapping for custom actions in Amazon Quick Sight Understanding field mapping Automated field mapping is based on identical fields. Fields with the same name and data type map automatically across datasets. Their field names and data types must be an exact match. This works similar to a join, except that it is automatically generated based on names and data types for every matching field. If you are missing fields, you can create them by using calculated fields in the dataset that's missing a field. If you don't want to have some of the fields mapped to each other, you can rename or remove them from the dataset. It's important to make sure that all target fields are mapped if they are enabled for use with a filter action (in the **Filter scope**). Doing this allows filtering to apply automatically. If some target fields aren't mapped, the automatic filtering doesn't work. Mapping is generated only when you create or save a custom action. So after every change that affects the mapping, make sure to return to it and save it again. When you create an action, mapping is based on the fields as they exist at that point. When you save an action, any mapped fields that you renamed since you created the custom action stay mapped. However, if you alter the data type of a mapped field, the mapping is removed. If your mapping is missing some fields, you can do one of the following to fix it: + Only target the mapped fields, by removing the unmapped fields from the **Filter scope.** + Remove the visual in question from the target visuals. + Create calculated fields to supply the missing fields for the mapping, and then save your custom action. + Edit the dataset and rename the fields or change their data types, and then save your custom action. + Edit the dataset and rename the fields or change their data types, and then resave your custom action. **Note** The information that displays on the mapping screen shows the configuration from the most recent time you saved it. To refresh or update the view, save the action again. If you add or edit datasets, they aren't automatically mapped or remapped. This causes the filtering to work incorrectly. For example, suppose that you add a new dataset, then create visuals for it. The new visuals won't respond to filter actions, because there is no field mapping to connect them. When you make changes, remember to save your custom actions again to redo the field mappings. If you remove a parameterized field or any other targeted field from the source visual, the action that uses it breaks. The action for the missing field either doesn't work when you select a data point, or it's hidden from the context menu. For information about preparing your dataset for automated field mapping, see [Mapping fields](mapping-and-joining-fields.md#mapping-and-joining-fields-automatic).