Commerce Dynamic Menu Attributes

The Domain, Variable, and Display determine the menu options for the user side menu. After defining the domain items, customers can simply add new items to the referenced Data Table or Transaction Array when they need new menu options. Administrators can select the following items when defining Dynamic Menus:

• Domain - The Data Table or Transaction Array that contains the Dynamic Menu options.

  Note: When Transaction Arrays are available, they are listed at the top of the Domain resources before the Data Table or Transaction Array items.

• Variable - The Data Table or Transaction Array column that contains the list of variable values of all possible Dynamic Menu options. Just like Single Select Menu and Multi-Select Menu attributes, CPQ uses the variable value of the selected menu option for Commerce processing and rules.

• Display - The Data Table or Transaction Array column that contains display names for all possible Dynamic Menu options. Display names determine the menu option names that appear in the user side menu.

  • A display name can be different from or the same as the variable name of a menu option.
  • If administrators intend the display name and variable name to match each other across all entries, they can set the Variable and Display settings to reference the same Data Table or Transaction Array column.

For example, an administrator wants to implement a Dynamic Menu so users can select a country. They create a "Country" Dynamic Menu attribute and select their pre-defined "CountryTax" Data Table for the Domain, the "CountryCode" column for the Variable, and the "Country" column for the Display value. As shown below, the Domain is highlighted in red, the Variable is highlighted in blue, and the Display is highlighted in green.

The following image shows the target "CountryTax" Data Table that contains the menu options.

When added to the JET Transaction UI, the Country menu will show the Display column values as menu options. Another feature to note is the “Type to Filter” functionality, which provides a field where users can enter text filter criteria. The Dynamic Menu will filter out options that do not contain the character(s) entered by the user.

If a Data Table or Transaction Array column has multiple items with the same value, the Dynamic Menu filter returns multiple results with the same value, resulting in users seeing the same result multiple times in the Dynamic Menu options.

Administrators can enable Distinct Values to ensure that a value displays only once in the user side menu.

The following image shows user side Dynamic Menu options without and with distinct values enabled.

Dynamic Menus can filter the menu options shown to the user based on static values or other attribute values. Within the Filter field, administrators can define a query to filter which Data Table or Transaction Array column values to display to the user. The size of the Filter text box supports 4000 characters.

In addition to the Country menu, the administrator wants to implement a Dynamic Menu so users can select a state. They create a "State" Dynamic Menu attribute and select their pre-defined "StateTax" Data Table for the Domain and the "State" column for the Variable and the Display value.

The following image shows the target "StateTax" Data Table that contains the menu options.

Filter Syntax

CPQ can interpret query specifications that follow a subset of MongoDB syntax.

For example, within the State Dynamic Menu attribute the administrator defined a Filter to match the "CountryCode" column in the StateTax Data Table to the value selected in the Country attribute. The Dynamic Menu will filter the menu options based on the user selection. Example Filter: {CountryCode:"|country|"}

When a user selects "United States" from the Country drop-down, the "State" Dynamic Menu uses the "US" CountryCode value to filter the "State" column values from the "StateTax" Data Table. On the user side, only menu options whose "CountryCode" value matches the value selected in the "Country" attribute value are shown.

The Case Sensitive option determines if the matching between the selected attribute value and the defined "Variable" Data Table or Transaction Array column differentiates between capital and lowercase letters. By default, this option is disabled and matches are case insensitive. If your site has case sensitive variable values, you should enable this option to ensure the desired results are returned. If your site has case sensitive display values and the Case Sensitive option is disabled, the site will return the first value based on the "Order By" selection and direction.

For example, assume that a Dynamic Menu has the same column defined tor the Variable and Display values. The chosen column has the following values: red, Red, and RED.

• If Case Sensitive is disabled, no matter which option a user selects they will get back the value that is deemed first based on the Order By selection and direction. This may not be the value associated with the case sensitive option they chose, because the site is performing a case-insensitive match and all of the values match each other (e.g. red = Red = RED)
• If Case Sensitive is enabled, when a user selects a case sensitive option they will always get the value that matches their selection, because the site is performing an exact match and the values do not match each other (e.g. red ≠ Red ≠ RED)

Customers can also provide translations for Dynamic Menu display values for named supported languages. To enable translations, administrators select the "Translations" option and provide the translated values in the target Data Table or Transaction Array domain.

The column selected for Display contains the base language values. Language codes are appended to the column name for the translated values. Data Table or Transaction Array column names for all other language columns should use the following format: "<Display Column Name>_<Language_Code>"

• Dynamic Menus support two-letter translations language codes. For example, the following column is used to provide French translations for the Country display values: "Country_fr"
• Dynamic Menus also support additional two-letter country codes. When using country codes, the first two characters of a language code define the language and the last two characters define the country. For example, the following column is used to provide Brazil Portuguese translations for the Country display values: "Country_pt_BR"

For the following example, English is the site base language. Therefore, the "Country" column contains English values. The "Country_de" column contains German translations, the "Country_es" column contains Spanish translations, and the "Country_fr" column contains French translations.

The following image shows user side Dynamic Menus for German, Spanish, and French translated sites.

During use, the session language (typically the logged in user's language) is used to determine which display value to show. If a display value translation cannot be found for the session language, the site base language display value will be used. This can occur if a specifically named column for the session language does not exist in the Data Table or Transaction Array or if the column exists but there is no value in that row.

When an administrator selects the Translations option for a Dynamic Menu attribute, the Available Translations section appears. This list shows the supported language set of a site. A "ü" checkmark icon indicates the appropriate translation column is found, and an "x" icon indicates the appropriate translation column was not found. Hovering the mouse over each language will indicate the name of the column from which translations are expected to be found for the language.

When the Advanced Validations option is enabled, data validations are triggered on a direct value changes and are also triggered during any modification action even when the value has not changed.

Complete the following steps to create a Commerce Dynamic Menu Attribute.

1. Log in to Oracle CPQ and open the Admin Home page.
2. Click Process Definition, in the Commerce and Documents section.
3. Select Documents from the Navigation drop-down menu for the applicable process, and then click List.
4. Select Attributes from the Navigation drop-down menu for the main or sub-document, and then click List.
5. Click Add.

Main Information

6. Enter the attribute Label.

7. Enter the attribute Variable Name.

   The Variable Name field populates automatically. Variable names can only contain alphanumeric characters and underscores. The entry can be changed before saving, but after saving the value is read-only.

8. Select Menu from the Attribute Type drop-down menu.
9. Select the Dynamic Menu for the Menu Source.

Dynamic Menu Population

10. Set the following Domain-related fields. Refer to Dynamic Menu Domains for more information.

    1. Domain: Select the Data Table or Transaction Array resource that defines the Dynamic Menu options.

       Note: When Transaction Arrays are available, they are listed at the top of the Domain resources before the Data Table items.

    2. Distinct Values: Select this option to ensure that a value displays only once to users in the Dynamic Menu.

       Note: The "Translations" option is not available when the Distinct Values option is enabled.

    3. Variable: Select the Data Table or Transaction Array column that contains the variable values of the Dynamic Menu options.

       Note: The Variable field is not selectable when the Distinct Values option is enabled.

    4. Display: Select the Data Table or Transaction Array column that contains display names for the Dynamic Menu options.
    5. Order By: Select the Data Table or Transaction Array column used to sort Dynamic Menu user options.
    6. Order By Direction: Select Ascending or Descending order.
    7. Filter: (optional) Define a query to filter which menu options in the Domain are shown to the user. Refer to Dynamic Menu Filters for more information.
    8. Case Sensitive: Select this option if your site has case sensitive variable values. By default, this option is disabled and matches are case insensitive. Refer to Case Sensitive Dynamic Menus for more information.
    9. Translations: Select this option to display translated menu values in the user's language preference, when the translated values are provide in the Data Table or Transaction Array resource. Refer to Dynamic Menu Translations for more information.

    10. Advanced Validation: When enabled, data validations run on the Dynamic Menu attribute even when there is no change in the value.

        Note: You should only enable this option when required, to prevent negative impacts on performance. The performance impact is even greater for sub-document Dynamic Menu attributes.

11. Click Add or Add and New to save changes.