# Parameters in Amazon Quick Parameters *Parameters* are named variables that can transfer a value for use by an action or an object. By using parameters, you can create an easier way for a dashboard user to interact with dashboard features in a less technical way. Parameters can also connect one dashboard to another, allowing a dashboard user to drill down into data that's in a different analysis. For example, a dashboard user can use a list to choose a value. That value sets a parameter that in turn sets a filter, calculation, or URL action to the chosen value. Then the visuals in the dashboard react to the user's choices. To make the parameters accessible to the dashboard viewer, you add a parameter control. You can set up cascading controls, so that a selection in one control filters the options that display in another control. A control can appear as a list of options, a slider, or a text entry area. If you don't create a control, you can still pass a value to your parameter in the dashboard URL. For a parameter to work, it needs to be connected to something in your analysis, regardless of whether it has a related control. You can reference parameters in the following: + Calculated fields (except for multivalue parameters) + Filters + Dashboard and analysis URLs + Actions + Titles and descriptions throughout an analysis Some ways that you can use parameters are the following: + Using a calculation, you can transform data that is shown in an analysis. + If you add a control with a filter to an analysis you are publishing, the dashboard users can filter the data without creating their own filters. + Using controls and custom actions, you can let dashboard users set values for the URL actions. **Topics** + [ # Setting up parameters in Amazon Quick ](parameters-set-up.md) + [ # Using a control with a parameter in Amazon Quick ](parameters-controls.md) + [ # Creating parameter defaults in Amazon Quick ](parameters-default-values.md) + [ # Connecting to parameters in Amazon Quick ](parameters-connections.md) # Setting up parameters in Amazon Quick Setting up parameters Use the following procedure to create or edit a basic parameter. **To create or edit a basic parameter** 1. Choose an analysis to work with, then decide which field you want to parameterize. 1. Choose the **Parameters** icon from the icon list at the top of the page. 1. Add a new parameter by choosing the plus sign (**\$1 Add**) near the top of the pane. Edit an existing parameter by first choosing the `v`-shaped icon near the parameter name and then choosing **Edit parameter**. 1. For **Name**, enter an alphanumeric value for the parameter. 1. For **Data type**, choose **String**, **Number**, **Integer**, or **Datetime**, and then complete the following steps. + If you choose **String**, **Number**, or **Integer**, do the following: 1. For **Values**, choose **Single value** or **Multiple values**. Choose the single value option for parameters that can contain only one value. Choose multiple values for parameters that can contain one or more values. Multivalue parameters can't be `datetime` data types. They also don't support dynamic default values. To switch an existing parameter between single and multiple values, delete and recreate the parameter. 1. (Optional) For **Static default value** or **Static multiple default values**, enter one or more values. This type of static value is used during the first page load if a dynamic default value or URL parameter isn't provided. 1. (Optional) Choose **Show as blank by default**. Select this option to show the default value for multivalue lists as blank. This option only applies to multivalue parameters. + If you choose **Datetime**, do the following: 1. For **Time granularity**, choose **Day**, **Hour**, **Minute**, or **Second**. 1. For **Default date**, select either **Fixed date** or **Relative date**, and then do the following: + If you select **Fixed date**, enter a date and time by using the date and time picker. + If you select **Relative date**, choose a rolling date. You can choose **Today**, **Yesterday**, or you can specify the **Filter condition** (start of or end of), **Range** (this, previous, or next), and **Period** (year, quarter, month, week, or day). 1. (Optional) Choose **Set a dynamic default** to create a default that is user-specific. A *dynamic default* is a per-user default value for the first page load of the dashboard. Use a dynamic default to create a personalized view for each user. Calculated fields can't be used as dynamic defaults. Dynamic defaults don't prevent a user from selecting a different value. If you want to secure the data, you can add row-level locking. For more information, see [Using row-level security with user-based rules to restrict access to a datasetUsing user-based rules](restrict-access-to-a-data-set-using-row-level-security.md). This option only appears if you choose a single value parameter. Multivalue parameters can't have dynamic defaults. **Note** If you choose a multivalue parameter, the screen changes to remove the default options. Instead, you see a box with the text **Enter values you want to use for this control**. You can enter multiple values in this box, each on a single line. These values are used as the default selected values in the parameter control. The values here are unioned with what you choose to enter for the parameter control. For more information on parameter controls, see [Parameter Controls](parameters-controls.md). 1. (Optional) Set a reserved value to determine the value of the **Select all** value. The *reserved value* of a parameter is the value that is assigned to a parameter when you choose **Select all** as its value. When you set up a specific reserved value for your parameter, that value is no longer considered a valid parameter value in your dataset. The reserved value can't be used in any *parameter consumers*, such as filters, controls, and calculated fields, and custom actions. Also, it does not appear in the parameter control list. You can choose from **Recommended value**, **Null**, and **Custom value**. **Recommended value** is the default. If you choose **Recommended value**, the reserved value is set to the following values based on the value type: + Strings: `"ALL_VALUES"` + Numbers: `"Long.MIN_VALUE"-9,223,372,036,854,775,808` + "Integers: `Int.MIN_VALUE"-2147483648` To set a reserved value in your new parameter, choose the **Advanced settings** dropdown list in either the **Create a new parameter** page or the **Edit parameter** page and select the value that you want. 1. Choose **Create** or **Update** to complete creating or updating the parameter. After you create a parameter, you can use it in a variety of ways. You can create a control (such as a button) so that you can choose a value for your parameter. For more information, see the following sections. # Using a control with a parameter in Amazon Quick Parameter controls In dashboards, parameter controls appear at the top of the data sheet, which contains a set of visuals. Providing a control allows users to choose a value to use in a predefined filter or URL action. Dashboard users can use controls to apply filtering across all visuals datasets on a dashboard, without having to create the filters themselves. The following rules apply: + To create or edit a control for a parameter, make sure that the parameter exists. + Multiselect list controls are compatible with analysis URLs, dashboard URLs, custom actions, and custom filters. The filter must be either equal or not equal to the values provided. No other comparisons are supported. + Lists show up to 1,000 values. If there are more than 1,000 distinct values, a search box appears so you can filter the list. When the filtered list contains less than 1,001 values, the contents of the list appear as line items. + The **Style** option displays only the style types that are appropriate for the parameter's data type and single or multivalue setting. If the style that you want to use isn't in the list, recreate your parameter with the appropriate settings and try again. + If your parameter links to a dataset field, it must be an actual field. Calculated fields aren't supported. + The values display alphabetically in the control, unless there are more than 1,000 distinct values. Then the control displays a search box instead. Each time you search for the value you want to use, it initiates a new query. If the results contain more than 1,000 values, you can scroll through the values with pagination. Wildcard search is supported. To learn more about wildcard search, see [Using wildcard search](search-filter.md#search-filter-wildcard). Use the following procedure to create or edit a control for an existing parameter. **To create or edit a control for an existing parameter** 1. Choose an existing parameter's context menu, the `v` icon near the parameter name, and choose **Add control**. 1. Enter a name to give the new control a label. This label appears at the top of the workspace, and later at the top of the sheet that a dashboard displays on. 1. Choose a style for the control from the following: + **Text field** A text field lets you type in their own value. A text field works with numbers and text (strings). + **Text field - multiline** A multiline text field lets you type in their own values. With this option, you can choose to separate values you enter into the parameter control by a line break, comma, pipe (\$1), or semicolon. A text field works with numbers and text (strings). + **Dropdown** A dropdown list control that you can use to select a single value. A list control works with numbers and text (strings). + **Dropdown multiselect** A list control that you can use to select multiple values. A list control works with numbers and text (strings). + **List** A list control that you can use to select a single value. A list control works with numbers and text (strings). + **List - multiselect** A list control that you can use to select multiple values. A list control works with numbers and text (strings). + **Slider** A slider lets you select a numeric value by sliding the control from one end of the bar to another. A slider works with numbers. + **Date-picker** Using a date-picker, you can choose a date from a calendar control. When you choose to add a date-picker control, you can customize how to format dates in the control. To do so, for **Date format**, enter the date format that you want using the tokens described in [Customizing date formats in Quick](format-visual-date-controls.md). 1. (Optional) If you choose a dropdown control, the screen expands so you can choose the values to display. You can either specify a list of values, or use a field in a dataset. Choose one of the following: + **Specific values** To create a list of specific values, type in one per line, with no separating spaces or commas, as shown in the following screenshot. In the control, the values display alphabetically, not in the order that you typed them. + **Link to a data set field** To link to a field, choose the dataset that contains your field, then choose the field from the list. If you change the default values in the parameter, choose **Reset** on the control to show the new values. The values that you choose here are unioned with the static default values in the parameter settings. 1. (Optional) Enable the option **Hide [ALL] option from the control if the parameter has a default configured**. Doing this shows only the data values and removes the option to select all items in the control. If you don't configure a static default on the parameter, this option doesn't work. You can add a default after adding a control by choosing the parameter, and selecting **Edit parameter**. 1. (Optional) You can limit the values displayed in the controls, so they only show values that are valid for what is selected in other controls. This is called a cascading control. To create one, choose **Show relevant values only**. Choose one or more controls that can change what displays in this control. When creating cascading controls, the following limitations apply. + Cascading controls must be tied to dataset columns from the same dataset. + The child control must be a dropdown or list control. + For parameter controls, the child control must be linked to a dataset column. + For filter controls, the child control must be linked to a filter (instead of showing only specific values). + The parent control must be one of the following. + A string, integer, or numeric parameter control. + A string filter control (EXCLUDING Top-Bottom filters). + A non-aggregated numeric filter control. + A date filter control (EXCLUDING Top-Bottom filters). 1. When you finish choosing options for your control, choose **Add**. The finished control appears at the top of the workspace. The context menu, shaped like a `v`, offers four options: + **Reset** restores the user's selection to its default state. + **Refresh list** applies only to drop-downs that are linked to a field in a dataset. Choosing **Refresh list** queries the data to check for changes. Data used in the control is cached. + **Edit** reopens the control creation screen so that you can change your settings. Once you have the **Edit control** pane open, you can click on different visuals and controls to view formatting data for the specific visual or control. For more information about formatting a visual, see [Formatting in Amazon Quick](formatting-a-visual.md). + **Delete** removes the control. You can recreate it by choosing the parameter context menu. In the workspace, you can also resize and rearrange your controls. The dashboard users see them as you do, except without being able to edit or delete them. # Creating parameter defaults in Amazon Quick Parameter defaults Use this section to learn more about the types of parameter defaults that are available, and how to set up each of them. Each field can have a parameter and a control associated with it. When someone views a dashboard or email report, any sheet control that has a static default value configured uses the static default. The default value can change how data is filtered, how custom actions behave, and what text displays in a dynamic sheet title. Email reports also support dynamic defaults. The simplest default is a static (unchanging) default, which shows the same value to everyone. As the designer of the dashboard, you choose the default value. It can't be changed by the person using the dashboard. However, that person can choose any value from the controls. Setting a default doesn't change this. To restrict the values that a person can select, consider using row-level security. For more information, see [Using row-level security with user-based rules to restrict access to a datasetUsing user-based rules](restrict-access-to-a-data-set-using-row-level-security.md). **To create or edit a static default value that applies to everyone's dashboard view** 1. Choose the context menu (`v`) by the parameter that you want to edit, or create a new parameter by following the steps in [Setting up parameters in Amazon Quick](parameters-set-up.md). 1. Enter a value for **Static default value** to set a static default. To display a different default depending on who is viewing the dashboard, you create a dynamic default parameter (DDP). Using dynamic defaults involves some preparation to map people to their assigned defaults. First, you need to create a database query or a data file that contains information about the people, the fields, and the default values to display. You add this to a dataset, then add the dataset to your analysis. Following, you can find procedures that you can use to gather information, create the dataset, and add the dynamic default to the parameter. Use the following guidelines when creating a dataset for dynamic default values: + We recommend that you use a single dataset to contain all dynamic default definitions for a logical grouping of users or groups. If you can, maintain them in a single table or file. + We also recommend that the fields in your dataset have names that closely match the field names in the analysis. Not all dataset fields need to be part of the analysis, for example if you're using the same dataset for the defaults in multiple dashboards. The fields can be in any order. + We don't recommend that you combine both user and group names in the same column or even in the same dataset. This kind of configuration is more work to maintain and troubleshoot. + If you use a comma-delimited file to create your dataset, make sure to remove any space between values in the file. The following example shows the correct comma-separated value (CSV) format. Enclose text (strings) that include nonalphanumeric characters—like spaces, apostrophes, and so on—in single or double quotation marks. You can enclose fields that are dates or times in quotation marks, but it isn't required. You can enclose numeric fields in quotation marks, for example if the numbers contain special characters, as shown following. ``` "Value includes spaces","Field contains ' other characters",12345.6789,"20200808" ValueWithoutSpaces,"1000,67","Value 3",2020-AUG-08 ``` + After you create the dataset, make sure to double-check the data types that Quick selects for the fields. Before you begin, you need a list of the user or group names for the people who are going to have dynamic defaults. To generate a list of users or groups, you can use the Amazon CLI to get the information. To run CLI commands, make sure that you have the Amazon CLI installed and configured. For more information, see [Installing the Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-install.html) in the *Amazon CLI User Guide*. This is just one example of how to get a list of user or group names. Use whatever method works best for you. **To identify people for a dynamic default parameter (DDP)** + List either individual user names or group names: + To list individual user names, include a column that identifies the people for your DDP. This column should contain each person's system user name that they use to connect from your identity provider to Quick. This user name is often the same as a person's email alias before the @ sign, but not always. To get a list of users, use the [ListUsers](https://docs.amazonaws.cn/quicksight/latest/APIReference/API_ListUsers.html) Quick API operation or Amazon CLI command. The CLI command is shown in the following example. Specify the Amazon Web Services Region for your identity provider, for example `us-east-1`. ``` awsacct1="111111111111" namespace="default" region="us-east-1" aws quicksight list-users --aws-account-id $awsacct1 --namespace $namespace --region $region ``` The following example alters the previous command by adding a query that limits the results to active users. ``` awsacct1="111111111111" namespace="default" region="us-east-1" aws quicksight list-users --aws-account-id $awsacct1 --namespace $namespace --region $region --query 'UserList[?Active==`true`]' ``` The result set looks similar to the following sample. This example is an excerpt from JSON output (`--output json`). People who have federated user names have principal IDs that start with the word `federated`. ``` [ { "Arn": "arn:aws-cn:quicksight:us-east-1:111111111111:user/default/anacasilva", "UserName": "anacarolinasilva", "Email": "anacasilva@example.com", "Role": "ADMIN", "Active": true, "PrincipalId": "federated/iam/AIDAJ64EIEIOPX5CEIEIO" }, { "Arn": "arn:aws-cn:quicksight:us-east-1:111111111111:user/default/Reader/liujie-stargate", "UserName": "Reader/liujie-stargate", "Role": "READER", "Active": true, "PrincipalId": "federated/iam/AROAIJSEIEIOMXTZEIEIO:liujie-stargate" }, { "Arn": "arn:aws-cn:quicksight:us-east-1:111111111111:user/default/embedding/cxoportal", "UserName": "embedding/cxoportal", "Email": "saanvisarkar@example.com", "Role": "AUTHOR", "Active": true, "PrincipalId": "federated/iam/AROAJTGEIEIOWB6BEIEIO:cxoportal" }, { "Arn": "arn:aws-cn:quicksight:us-east-1:111111111111:user/default/zhangwei@example.com", "UserName": "zhangwei@example.com", "Email": "zhangwei@example.com", "Role": "AUTHOR", "Active": true, "PrincipalId": "user/d-96123-example-id-1123" } ] ``` + To list group names, include a column that identifies the groups containing the user names for your DDP. This column should contain the system group names that are used to connect from your identity provider to Quick. To identify groups that you can add to the dataset, use one or more of the following Quick API operations or CLI commands: + [ListGroups](https://docs.amazonaws.cn/quicksight/latest/APIReference/API_ListGroups.html) – Lists Quick groups by Amazon Web Services account ID and namespace for the Amazon Web Services Region that contains your identity provider. + [ListGroupMemberships](https://docs.amazonaws.cn/quicksight/latest/APIReference/API_ListGroupMemberships.html) – Lists the users in the specified Quick group. + [ListUserGroups](https://docs.amazonaws.cn/quicksight/latest/APIReference/API_ListUserGroups.html) – Lists the Quick groups that a Quick user is a member of. Or you can ask your network administrator to query your identity provider to get this information. The next two procedures provide instructions on how to finish creating a dataset for dynamic default values. The first procedure is for creating a dataset for a single-value DDP. The second one is for creating a dataset for a multivalue DDP. **To create a dataset for a single-value DDP** 1. Create dataset columns with single-value parameters. The first column in the query or file should be for the people using the dashboard. This field can contain user names or group names. However, support for groups is only available in Quick Enterprise edition. 1. For each field that displays a dynamic default for a single-value parameter, add a column to the dataset. The name of the column doesn't matter—you can use the same name as the field or parameter. Single-value parameters only work as specified if the combination of user entity and dynamic default is unique for that parameter's field. If there are multiple values a default field for a user entity, the single-value control for that field displays the static default instead. If no static default is defined, the control doesn't display a default value. Be careful if you use group names, because some user names can be members of multiple groups. If those groups have different default values, then this type of user name functions as a duplicate entry. The following example shows a table that appears to contain two single-value parameters. We make this assumption because no user name is paired with multiple default values. To make this table easier to understand, we add the word `'default'` in front of the field names from the analysis. Thus, you can read the table by making the following statement, changing the values for each row: When viewed by `anacarolinasilva`, the controls display a default region `NorthEast` and a default segment `SMB`. [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/quick/latest/userguide/parameters-default-values.html) 1. Import this data into Quick, and save it as a new dataset. 1. In your analysis, add the dataset that you created. The analysis needs to use at least one other dataset that matches the columns you defined for the defaults. For more information, see [Adding a dataset to an analysis](adding-a-data-set-to-an-analysis.md). **To create a dataset for a multivalue DDP** 1. Create dataset columns with multivalue parameters. The first column in the query or file should be for the people using the dashboard. This field can contain user names or group names. However, support for groups is only available in Quick Enterprise edition. 1. For each field that displays a dynamic default for a multivalue parameter, add a column to the dataset. The name of the column doesn't matter—you can use the same name as the field or parameter. Unlike single-value parameters, multivalue parameters allow multiple values in the field that's associated with the parameter. The following example shows a table that appears to contain a single-value parameter and a multivalue parameter. We can make this assumption because each user name has a unique value in one column, and some user names have multiple values in the other column. To make this table easier to understand, we add the word `'default'` in front of the field names from the analysis. Thus, you can read the table by making the following statement, changing the values for each row: When `viewed-by` is `liujie`, the controls display a `default-region` value of `SouthEast`, and a `default-city` value of `Atlanta`. And if we read ahead one row, we see that `liujie` also has `Raleigh` in `default-city`. [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/en_us/quick/latest/userguide/parameters-default-values.html) In this example, the parameter that we apply `default-region` to works correctly whether it's a single-value or multivalue parameter. If it's a single-value parameter, two entries work for one user because both entries are the same value, `SouthEast`. If it's a multivalue parameter, it still works, except that only one value is selected by default. However, if we change the parameter that's using `default-city` as its default from a multivalue to a single-value parameter, we don't see these defaults selected. Instead, the parameter uses the static default, if there is one defined. For example, if the static default is set to `Atlanta`, `liujie` has `Atlanta` selected in that control, but not `Raleigh`. In some cases, your static default value might also be used as a dynamic default. If so, make sure to test the control for a user name that doesn't use a default value that can be both. If a user name belongs to multiple groups, the named user sees a set of default values that is a union of the two groups' default values. 1. Import this data into Quick, and save it as a new dataset. 1. In your analysis, add the dataset that you created. The analysis needs to use at least one other dataset that matches the columns you defined for the defaults. For more information, see [Adding a dataset to an analysis](adding-a-data-set-to-an-analysis.md). Use the following procedure to add a dynamic default parameter to your analysis. Before you begin, make sure that you have a dataset that contains the dynamic defaults for each user name or group name. Also make sure that your analysis is using this dataset. For help with these requirements, see the procedures preceding. **To add a DDP to your analysis** 1. In the Quick console, choose the **Parameters** icon at the top of the page and choose an existing parameter. Choose **Edit parameter** from the parameter's menu. To add a new parameter, choose the plus (`+`) sign near **Parameters**. 1. Choose **Set a dynamic default**. 1. Configure the following options with your settings: + **Dataset with default values and user information** – Choose the dataset that you created and added to your analysis. + **User name column** – To create defaults that are based on user names, choose the column in the dataset that contains the user names. + **Group name column** – To create defaults that are based on group names, choose the column in the dataset that contains the group names. + **Column for default value** – Choose the column that contains default values for this parameter. 1. Choose **Apply** to save your setting changes, and then choose **Update** to save the parameter changes. To exit without saving changes, choose **Cancel** instead. 1. Add a filter for each field that contains dynamic defaults to make the defaults work. To learn more about using filters with parameters, see [Using filters with parameters in Amazon Quick](parameters-filtering-by.md) Amazon Quick uses the static default value for anyone whose user name doesn't exist in the dataset, doesn't have a default assigned, or doesn't have a unique default. Each person can have only one set of defaults. If you don't want to use dynamic defaults, you can set a static default instead. # Connecting to parameters in Amazon Quick Connecting to parameters Use this section after you have a parameter set up, to connect it and make it work. After you create a parameter, you can create consumers of the parameters. *Parameter consumers* are components that consume the value of a parameter, such as filters, controls, calculated fields, or custom actions. You can navigate to each of these options in another way, as follows: + To create a filter, choose the **Filter** icon at the top of the page. In short, you create a **Custom Filter** and enable **Use parameters**. The list shows only eligible parameters. + To add a new control for the parameter, choose the **Parameters** icon at the top of the page. In short, choose your parameter, and then **Add control**. + To use a parameter in a calculated field, either edit an existing calculated field, or add a new one by choosing **Add** at the top left. The parameter list appears below the field list. **Note** You can't use multivalue parameters with calculated fields. + To create a URL action, choose the **v**-shaped menu on a visual, and then choose **URL Actions**. For more information on each of these topics, see the following sections. **Topics** + [Using filters with parameters](parameters-filtering-by.md) + [Using calculated fields with parameters](parameters-calculated-fields.md) + [Using custom actions with parameters](parameters-custom-actions.md) + [Parameters in URLs](parameters-in-a-url.md) + [Parameters in titles and descriptions](parameters-in-titles.md) # Using filters with parameters in Amazon Quick Using filters with parameters Use this section to filter the data in an analysis or dashboard by a single-value parameter value. To use a multivalued parameter—one with a multiselect drop-down control—create a custom filter that is equal (or not equal) to the values. Before using a filter with a parameter, you should already know how to work with filters. 1. Verify that your analysis has a parameter already created. Choose **Edit** from either the parameter or the control menu to find out what settings are in use. 1. Choose the **Filter** pane from the left of the screen. If there is already a filter for the field that you want to use, choose it to open its settings. Otherwise, create a filter for the field that you want to filter by parameter. 1. Choose **Use Parameters**. 1. Choose your parameters from the list or lists below **Use parameters**. For text (string) fields, first choose **Custom Filter**, and then enable **Use Parameters**. For date fields, choose the **Start date** and **End date** parameters, as shown in the following screenshot. For fields with other data types, choose **Select a parameter** and then choose your parameter from the list. **Note** Parameters that can hold multiple values must use equal or not equal as the comparison type. 1. Choose **Apply** to save your changes. Test your new filter by choosing the control near the top of the analysis. In this example, we use a basic parameter that has no defaults, and a dynamic control that is linked to the **Region** field in the sample dataset named **Sales Pipeline**. The control queries the data, returning all values. If you delete or recreate a parameter that you are using in a filter, you can update the filter with the new parameter. To do this, open the filter, choose the new parameter that you want to use, and then choose **Apply**. If you rename a parameter, you don't need to update the filter or any other consumers. # Using calculated fields with parameters in Amazon Quick Using calculated fields with parameters You can pass the value of a parameter to a calculated field in an analysis. When you create a calculation, you can choose existing parameters from the list of parameters under **Parameter list**. You can't create a calculated field that contains a multivalued parameter—those with a multiselect drop-down control. For the formula, you can use any of the available functions. You can pass the viewer's selection from the parameter control, to the `ifElse` function. In return, you get a metric. The following shows an example. ``` ifelse( ${KPIMetric} = 'Sales',sum({Weighted Revenue}), ${KPIMetric} = 'Forecast',sum({Forecasted Monthly Revenue}), ${KPIMetric} = '# Active', distinct_count(ActiveItem), NULL ) ``` The preceding example creates a metric (a decimal) that you can use in a field well. Then, when a user chooses a value from the parameter control, the visual updates to reflect their selection. # Using custom actions with parameters in Amazon Quick Using custom actions with parameters A *custom action* enables you to launch URLs or filter visuals by selecting a data point in a visual or choosing the action name from the context menu. When you use a URL action with a parameter, you can pass or send parameters dynamically to the URL. To make this work, you set up a parameter, and then use it in the URL when you create a custom action with an action type of **URL action**. The parameters on both the sending and the receiving end must match in name and data type. All parameters are compatible with URL actions. For details on creating a URL action, see [Creating and editing custom actions in Amazon Quick Sight](custom-actions.md). If you just want to use a parameter in a link without creating a URL action, see [Using parameters in a URL](parameters-in-a-url.md). # Using parameters in a URL Parameters in URLs You can use a parameter name and value in a URL in Amazon Quick to set a default value for that parameter in a dashboard or analysis. The following example shows the URL of a dashboard that sets a parameter for another dashboard. ``` https://us-east-2.quicksight.aws.amazon.com/sn/dashboards/abc123-abc1-abc2-abc3-abcdefef1234#p.myParameter=12345 ``` In the previous example, the first part is the link to the target dashboard: `https://us-east-2.quicksight.aws.amazon.com/sn/dashboards/abc123-abc1-abc2-abc3-abcdefef1234`. The hash sign (`#)` follows the first part to introduce the *fragments*, which contain the values that you want to set. The values in the fragments aren't received or logged by Amazon servers. This functionality keeps your data values more secure. The fragment after `#` follows these rules: + Parameters are prefixed with `p.`. The names are the parameter name, not the control name. You can view the parameter name by opening the analysis, and choosing **Parameter** on the left sidebar. + The value is set using equals (`=`). The following rules apply: + Literal values don't use quotation marks. + Spaces inside values are automatically encoded by the browser, so you don't need to use escape characters when manually creating a URL. + To return all values, set the parameter equal to `"[ALL]"`. + To assign the parameter's value to `null`, set it equal to `%00`. For example, `p.population=%00`. + In custom actions, target parameter names begin with `$`, for example: `<<$passThroughParameter>>` + In custom actions, parameter values display with angle brackets `<< >>`, for example `<>`). The dashboard user sees the lookup value, not the variable. + For a custom URL action, multivalue parameters only need one instance of the same parameter in the fragment, for example: `p.city=<<$city>>` + For a direct URL, multiple values for a single parameter have two instances of the same parameter in the fragment. For an example, see following. + Ampersands (`&`) separate multiple parameters. For an example, see following. The server converts the date to UTC and sends it to the backend as a string without a time zone. To use Universal Coordinated Time (UTC) dates, exclude the time zone. Following are some examples of date formats that work: + `2017-05-29T00%3A00%3A00` + `2018-04-04 14:51 -08:00` + `Wed Apr 04 2018 22:51 GMT+0000` ``` https://us-east-2.quicksight.aws.amazon.com/sn/dashboards/abc123-abc1-abc2-abc3-abcdefef1234#p.shipdate=2018-09-30 08:01&p.city=New York&p.city=Seattle&p.teamMember=12&p.percentageRank=2.3 ``` In the browser, this code becomes the following. ``` https://us-east-2.quicksight.aws.amazon.com/sn/dashboards/abc123-abc1-abc2-abc3-abcdefef1234#p.shipdate=2018-09-30%2008:01&p.city=New%20York&p.city=Seattle&p.teamMember=12&p.percentageRank=2.3 ``` The previous example sets four parameters: + `shipDate` is a date parameter: `Sept 30, 2018`. + `city` is a multivalued string parameter: `New York`, and `Seattle` + `teamMember` is an integer parameter: `12`. + `percentageRank` is a decimal parameter: `2.3`. The following example shows how to set values for a parameter that accepts multiple values. ``` https://us-east-2.quicksight.aws.amazon.com/sn/dashboards/abc123-abc1-abc2-abc3-abcdefef1234#p.MultiParam=WA&p.MultiParam=OR&p.MultiParam=CA ``` To pass values from one dashboard (or analysis) to another dashboard based on the user's data point selection, use custom URL actions. If you choose, you can also generate these URLs manually, and use them to share a specific view of the data. For information on creating custom actions, see [Using custom actions for filtering and navigating](quicksight-actions.md). # Using parameters in titles and descriptions in Amazon Quick Parameters in titles and descriptions When you create parameters in Amazon Quick, you can use them in titles and descriptions throughout your charts and analyses to dynamically display parameter values. You can use parameters in the following areas of your analysis: + Chart titles and subtitles + Axis titles + Legend titles + Parameter control titles + Sheet titles and descriptions The following image shows a chart title that uses a parameter. ![\[Image of the Format visual pane with a parameter in the chart title and a chart with the parameter value in the title circled in red.\]](http://docs.amazonaws.cn/en_us/quick/latest/userguide/images/parameters-in-titles-labels2.png) Use the following procedures to learn how to add parameters to areas throughout your analysis. For more information about parameters and how to create them, see [Parameters](parameters-in-quicksight.md). ## Adding parameters to chart titles and subtitles Chart titles Use the following procedure to learn how to add parameters to chart titles and subtitles. **To add a parameter to a chart title or subtitle** 1. Open the **Properties** pane for the visual that you want to format. 1. In the **Properties** pane, choose the **Title** tab. 1. Select **Show title** or **Show subtitle**. These options might already be selected. 1. Choose the three dots at the right of **Edit title** or **Edit subtitle**, and then choose a parameter from the list. The parameter is added to the title in the **Properties** pane. In the chart, the parameter value is displayed in the title. For more information about editing titles and subtitles in visuals, see [Titles and subtitles on visual types in Quick](customizing-a-visual-title.md). ## Adding parameters to axis titles Axis titles Use the following procedure to learn how to add parameters to axis titles. **To add a parameter to an axis title** 1. Open the **Properties** pane for the visual that you want to format. 1. In the **Properties** pane, choose the axis that you want to format. 1. Select **Show title**. 1. Choose the three dots at the right of the default axis title, and then choose a parameter from the list. The parameter is added to the axis title in the **Properties** pane. In the chart, the parameter value is displayed in the axis title. For more information about editing axis titles, see [Axes and grid lines](showing-hiding-axis-grid-tick.md). ## Adding parameters to legend titles Legend titles Use the following procedure to learn how to add parameters to legend titles. **To add a parameter to a legend title** 1. Open the **Properties** pane for the visual that you want to format. 1. In the **Properties** pane, choose **Legend**. 1. Select **Show legend title**. 1. Choose the three dots at the right of **Legend title**, and then choose a parameter from the list. The parameter is added to the legend title in the **Properties** pane. In the chart, the parameter value is displayed in the legend title. For more information about formatting legends, see [Legends on visual types in Quick](customizing-visual-legend.md). ## Adding parameters to control titles Control titles Use the following procedure to learn how to add parameters to parameter control titles. **To add a parameter to a parameter control title** 1. Select the parameter control that you want to edit, choose the three dots at the right of the parameter control title, and then choose **Edit**. 1. In the **Edit control** page that opens, select **Show title**. 1. Choose the three dots at the right of **Display name**, and then choose a parameter from the list. The parameter is added to the parameter control title. For more information about using parameter controls, see [Parameter controls](parameters-controls.md). ## Adding parameters to sheet titles and descriptions Sheet titles and descriptions Use the following procedure to learn how to add parameters to sheet titles and descriptions in your analysis. **To add a parameter to a sheet title or description** 1. On the analysis page, choose **Sheets** in the application bar and then choose **Add title** or **Add description**. A sheet title or description appears on the sheet. 1. For **Sheet title** or for **Description**, choose the three dots at right, and then choose a parameter from the list. The parameter is added to the sheet title or description and the parameter value appears in the text when you close the text box. For more information about adding sheet titles and descriptions, see [Adding a title and description to an analysis](adding-a-title-and-description.md).