Dynamic options

Defining dynamic options

To define a dynamic options customer response:

1. In a step, click Define customer response.

2. Choose the Options response type.

3. Click the Dynamic toggle.

4. In the Source variable field, choose the variable that contains the array that defines the dynamic options (for example, the variable containing the response from a custom extension that you called in a previous step).

5. Optional: In the Option field, write an expression that maps the items in the source array to the options that will be listed. This expression serves as a template that converts each item in the array to a meaningful value that will be displayed to the customer. In this expression, use the dynamic variable ${item} to represent the item.

   In some situations, you do not need to specify an expression:

   • If the items in the array are simple values such as strings or integers, the value of each item is automatically shown as an option. However, you might still want to define a mapping if you want to manipulate or reformat the items to make them more meaningful. For example, you might use the expression "Part #" + ${item} to show part numbers using the format Part #12345.

   • If the items in the array are JSON objects, the default mapping looks for a property called label and uses its value (if present) as the option. If the item does not include a label property, or you do not want to use the value of the label property as the option, you must write an expression to specify a mapping. You can use dot notation to refer to a property in the object using its JSON path (for example, ${item}.name).

6. Optional: Click Add fallback option to include a static choice, such as None of the above, if the options aren't what the customer wants. You can then add a step that is conditioned on this static option to provide further assistance. To add the condition, write a expression such as ${step_id}.value == "None of the above".

Mapping examples

Suppose you want to build an action that shows a list of pets available for adoption and prompts the customer to select a pet to see more information about. The source variable contains an array from a custom extension in the following format:

[
  {
    "id": "123",
    "name": "Casey",
    "breed": "Shetland sheepdog",
    "age": 3
  },
  {
    "id": "987",
    "name": "Phoebe",
    "breed": "chihuahua",
    "age": 7
  }
]

The schema for the items does not include a label property, so the default mapping is not available. Instead, you might use an expression to build a complex label that includes data taken from several different properties. For example, you might use the expression ${item}.name + " (" + ${item}.breed + ", age " + ${item}.age + ")" to define the option labels:

Remember that you can use expression methods to manipulate values from the source variable in various ways. For example, you might have an action customers use to select a credit card for payment, but for security reasons you don't want to show the entire card number. You could write an expression that uses the substring() method to include only the last four digits of each card number (for example, "Card ending in " + ${item}.card_number.substring(16, 20)).

Referencing the selected item

After the customer has selected one of the dynamically generated options, you will probably need to reference the selected item in a subsequent step.

If you reference the action variable representing the customer response, the default is to use the value of the selected option. However, in some situations, you might not want to use the same value that was used to display the option to the customer. Instead, you might need to use a unique identifier or other property that unambiguously identifies the selected option.

For example, if the customer selects a pet to show more information about, you probably need to use a unique identifier (the id property in our example) to query the database, since the pet's name, age, and breed might not be unique. Or if the customer is selecting a credit card from options that show only the last four digits, you will need to use the full credit card number to access the account details or complete a transaction.

In this situation, you can write an expression to access the original properties of the selected item:

1. Create or edit a step that comes after the step in which the customer selects from the dynamic options.

2. In the Variable values section, write an expression to assign a value to a session variable. (For more information, see Using an expression to assign a value to a session variable.)

3. In the expression editor, type a dollar sign ($) and then select the step in which the customer selected the dynamic option.

4. Use the property name item to represent the selected item, and dot notation to access its properties. For example, the following expression accesses the id property of the item selected in a previous step:

   ${step_331}.item.id
   

   You can use a complex expression to construct a value using multiple properties of the selected item. For example, you might use an expression such as ${step_123}.item.firstname + " " + ${step_123}.item.lastname to construct a person's full name. Use the expression to define the value in whatever format you need to complete any required action.