Parameters in Exploration Canvas

• What is a Parameter?
• Creating a Parameter on a Filtered View
  • Add a Parameter
• Editing a Parameter
• Adding a Parameter to a Query
• Important Notes About Parameters

What is a Parameter?

Parameters allow you to change a variable, such as a number, date, string, or Boolean, in the definition of a query, which can dynamically change the results of the query. You can use a parameter to change the values in a column, to change the logic of a calculated column or change the terms of a select in a query. This is a very powerful capability that can be used in an infinite number of ways to make your filtered view more flexible and capable of serving many use cases.

Creating a Parameter on a Filtered View

Parameters are attached to any derived view in the Exploration Canvas. When a parameter is created on a derived view it can be used on that view in the SoQL query. Any child views created from that parent view will also inherit the parameter from the parent view.

Add a Parameter

You can add a parameter to any draft derived view in Exploration Canvas, either when you are creating a new view or editing an existing view. To create a parameter:

• Open a draft by clicking “Edit” on an existing view or selecting “Create View” from the Exploration Canvas

• Navigate to the Parameters tab in the lower part of the Exploration Canvas

• Click “New Parameter”

• When the new parameter modal opens, choose an API field name

  • API field names must be all lower case and have no spaces

• Choose a display name for your parameter. This display name will be shown where parameter controls are present, like in the Global Filter bar in Stories.

• Choose a parameter data type

  • The Exploration Canvas allows for 4 types of Parameters to be used in your query:

    • Text

    • Number

    • Date

    • Checkbox (Boolean)

• Set a default value for your parameter. This is the value that will be evaluated by default on your view until it is overridden in a parameter control such as in stories.

Once you create the parameter you can copy the SoQL snippet in the modal to make it easier to add to your SoQL query. When you are finished click “Save”.

You will now see your newly created parameter listed in the Parameters tab with the name, type, and default value.

Note: You can also create a new parameter directly from the SoQL tab by clicking "Create New" directly from the Insert Parameter button in the SoQL Query Editor

Editing a Parameter

To edit a parameter, select the Actions button in the row to the right of the parameter you want to change. Select “Edit” from the dropdown.

From here you can change the display name and default value for your parameter. API field names and types cannot be modified after the parameter has been created. Changing the default value and saving will also change the results in the table of the Exploration Canvas.

Adding a Parameter to a Query

Once you have created a parameter, you need to add it to your SoQL query to use it. You can easily add parameters to your query in a couple of ways:

• Use the “insert parameter” button in the SoQL Query Editor

• Select the “copy” button from the SoQL Usage section of the create/edit modal for your parameter and paste the snippet into your query.

You can add a parameter in a number of different ways to change your query. For example, you can add it to a case statement in your SELECT to change values in a calculated column, or use it in a WHERE clause to change the data returned based on the parameter value.

Check out this article on Parameters Use Cases for more ideas on how you can use parameters to make your filtered views even more powerful!

Important Notes About Parameters

• When a parameter is created, it's attached to the view it's created on, and can only be used in that derived view, a child view of that derived view, or as a joined view.  Any related views will inherit the parameter of the parent view, and the value in that view will be applied to related views using that parameter. 
• Parameters cannot be deleted until they are removed from the query.  This is to ensure that the query won't fail after a parameter is used. 
• Once a parameter has been created you can change the Display name or the default value, but the API field name and the type of parameter cannot be changed once it is created.