8.9.10 Adding Natural Language Support to Interactive Reports

Add natural language support to interactive reports.

• About Natural Language Support in Interactive Reports
  Learn about natural language support available in interactive reports.
• Best Practices When Using Natural Language
  Learn about best practices when using natural language to filter a report.
• Enabling Natural Language Support for an Interactive Report
  Enable natural language support by configuring region attributes, defining context, and optionally specifying reference data.

8.9.10.1 About Natural Language Support in Interactive Reports

Learn about natural language support available in interactive reports.

About Natural Language Support

You can extend interactive reports to accept natural language input from end users. Utilizing a Large Language Model (LLM), you can convert user input into a declarative customization setting. Adding natural language input enables users to apply report settings, such as filters, control breaks, charts, and so on, using natural language.

About Enabling Natural Language Support

Enabling an interactive report to support natural language input, involves the following general steps:

1. Create a Generative AI Service. See Managing Generative AI Services.
2. Create an application with page containing an interactive report as part of the Body.
3. Associate the Generative AI Service with the application. See Configuring AI Attributes for an Application.
4. Enable natural language support and add report context. See Enabling Natural Language Support for an Interactive Report.

8.9.10.2 Best Practices When Using Natural Language

Learn about best practices when using natural language to filter a report.

When asking questions using natural language, remember that AI assistants only work with the existing columns and capabilities already available in your interactive report.

Best practices when using natural language to filter a report include:

• Use natural language to apply report settings such as filters, select columns, highlights, breaks, sorts, groups, charts, and pivots. You can also perform report actions such as reset, save and set the rows per page.
• Keep questions focused on how data should display in the report.
• Phrase instructions using language such as Show me..., Break by..., Highlight..., Group by..., and so on.
• A request containing multiple actions within one instruction. For example:

  Show all projects for Develop Production Partner Portal and Develop IT Management Apps, sort on the start date and highlight the rows in green that have a cost of zero.

In contrast, avoid the following when using natural language to filter a report:

• Do not ask questions to generate new insights or doing free-form analysis.
• Do not request complex queries such as nested groupings or multiple aggregations. Hierarchical rollups are supported. Request one grouping or calculation at a time.
• Open-ended requests are not supported. For example:
  • Why are sales down?
  • Who is the best manager?

8.9.10.3 Enabling Natural Language Support for an Interactive Report

Enable natural language support by configuring region attributes, defining context, and optionally specifying reference data.

This topic describes how to enable natural language support for an interactive report by enabling the Natural Language Support switch, configuring context for the report and report columns, and specifying reference data.

Note:

This discussion assumes you have already created a Generative AI Service. If no Generative AI Services are available in the workspace, some attributes described in this section are hidden. To learn more, see Managing Generative AI Services.

The following example shows an interactive report page built on the EBA_PROJECT_TASKS table available in the sample dataset, Project Data.

To enable the Natural Language Support and configure interactive report attributes:

1. Create a Generative AI Service.
2. Create an application with page containing an interactive report as part of the Body.

   The following example shows an interactive report built on the sample dataset, Customer Orders.

3. Associate the Generative AI Service with the application. See Configuring AI Attributes for an Application.
4. Configure Generative AI attributes:
   1. View the interactive report page in Page Designer.
   2. In the Rendering tab, select the region containing the interactive report.
   3. In the Property Editor, select the Attributes tab.
   4. Generative AI, Natural Language Support - Enable this option.

      Enabling Natural Language Support allows users to interact with the report using natural language prompts. When Natural Language Support is enabled, APEX uses AI to interpret user intent and apply relevant filters, sorting, or other report settings.

   5. Generative AI, Default Search Mode - Options include:
      • Search with AI - The search mode is the AI Search used for natural language support. When Natural Language Support is enabled, this is the default search mode.

        Note that when Search with AI is selected, if the user enters two or more words, it automatically triggers a row search.

      • Row Search - The search mode is the original interactive report row search.

      For this example, accept the default Search with AI.

   6. Generative AI, Report Context - Enter a short, human-readable description of what this report contains or its purpose. This contexts helps the AI better understand the meaning, context, and usage of user prompts. Supplying context is optional but can improve the accuracy and relevance of results.

      For example:

      This interactive reports displays IT projects. The report lists Project, Milestone, Name, Description, Assignee, State Date, End Date, Cost, Is Complete, and Updated By. The data supports filtering on the Project, Milestone, Name, Description, Assignee, State Date, End Date, Cost, whether the project is complete, and ho last updated the report.

   7. Click Save.
5. Configure Generative AI attributes for the START_DATE column:
   1. In the Rendering tab, expand Columns.
   2. Select START_DATE.
   3. Column Context - Provide a short, human-readable description of this column's meaning, purpose, or special values. Column Context helps the AI better understand the column's meaning, context, and usage when interpreting natural language prompts. For example:

      Date when the task is scheduled or expected to begin.
      Common Use: Timeline planning, scheduling, calculating durations. AI Hints: Use with END_DATE to derive durations; ensure logical ordering (start ≤ end).
      AI Hints: Use with END_DATE to derive durations; ensure logical ordering (start ≤ end).

6. Configure Generative AI attributes for the PROJECT_ID column:
   1. In the Rendering tab, select PROJECT_ID.
   2. Column Context - Provide a short, human-readable description of this column's meaning, purpose, or special values. Column Context helps the AI better understand the column's meaning, context, and usage when interpreting natural language prompts. For example:

      Context: The name of the overarching internal IT project.
      Common Use: Filtering tasks by project, highlightling by projects, grouping tasks within a project.
      AI Hints: This is the primary grouping attribute; most queries and aggregations will scope by this column.
      

   3. Reference Data Type - Select Shared Component.
   4. List of Values - Select EBA_PROJECTS.NAME.
7. Configure Generative AI attributes for the MILESTONE_ID column:
   1. In the Rendering tab, select MILESTONE_ID.
   2. Column Context - Provide a short, human-readable description of this column's meaning, purpose, or special values. Column Context helps the AI better understand the column's meaning, context, and usage when interpreting natural language prompts. For example:

      Context: The milestone the project task has reached within the task.
      Common Use: Organizing tasks under milestones, milestone progress tracking, reporting.
      AI Hints: Can be a nullable field; absence means task is not tied to a milestone. Uses structured reference data.
      

   3. Reference Data Type - Select Shared Component.
   4. List of Values - Select EBA_PROJECT_MILESTONES.NAME.
8. Configure Generative AI attributes for the ASSIGNEE column:
   1. In the Rendering tab, select ASSIGNEE.
   2. Column Context - Provide a short, human-readable description of this column's meaning, purpose, or special values.
   3. Reference Data Type - Select SQL Query.
   4. SQL Query - Enter the SQL query definition to populate this list of values. For example:

      select distinct assignee d, assignee r
         from eba_project_tasks

9. Save and run the page. Click Save and Run Page.

   The interactive report page appears.

   
   

   
   Description of the illustration ir_nls.png

   
   

   Note the search bar includes the following controls:

   • Columns to Search - Select specific columns to search or search all columns.
   • Search or ask a question - Enter natural language to apply filters, highlight, sort, show/hide columns,apply control breaks, perform group bys, aggregate data, pivot, create charts, add pagination save reports, and reset the report state.
   • Actions menu - Displays as three vertical dots (). Use the Actions menu to customize the interactive report. Contains the same options that appear in standard interactive reports.
   • Creates - Create a new row in the table.
10. In the Search or ask a question:
    1. Enter natural language to filter the report. For example:

       Show projects where the Assignee is Tyson King and highlight rows in yellow if the cost is greater than 5000.

    2. Press Enter.

       A revised report appears with two filters: Assignee = 'Tyson King' and Cost >5000.

       
       

       
       Description of the illustration ir_nls_search_results.png

       
       
11. To view the AI Assistant, click the Assistant icon ().
    1. Click the Assistant icon.

       The AI Assistant appears to the right of the report. Note the previously entered text displays in the AI Assistant window.

       
       

       
       Description of the illustration ir_nls_ai_assistant.png

       
       

       Additional AI Assistant controls include:

       • Detach - Displays the AI Assistant in a separate window on top of the report.
       • Close Assistant - Closes the AI Assistant window.
    2. To add additional filters, enter more criteria in Type your message here field and press Enter.