Skip to content

feat: implement search terms worksheet functionality#430

Merged
kallilsouza merged 4 commits into
mainfrom
feature/search-terms-metrics-report
Jun 11, 2026
Merged

feat: implement search terms worksheet functionality#430
kallilsouza merged 4 commits into
mainfrom
feature/search-terms-metrics-report

Conversation

@kallilsouza

Copy link
Copy Markdown
Contributor

What

Adds a new SEARCH_TERMS section to the Conversations Report generation flow. When this section is selected, the generated report includes an extra "Search terms" worksheet containing the contact URN, the event date, and the searched term, sourced from datalake weni_nexus_data events filtered by a configurable agent UUID and key.

Changes include:

  • New SEARCH_TERMS value in ConversationsReportSections.
  • New abstract method get_search_terms_worksheet on BaseConversationsReportService and its concrete implementation on ConversationsReportService.
  • SEARCH_TERMS registered in the worksheet mapping (_get_worksheets) and in the available widgets/sections list.
  • Settings-driven configuration via CONVERSATIONS_METRICS_SEARCH_TERMS_AGENT_UUID and CONVERSATIONS_METRICS_SEARCH_TERMS_KEY, raising SearchTermsAgentUUIDNotConfiguredError when the agent UUID is missing.
  • PT-BR and ES translations for the new "Search terms" and "Terms" strings.
  • Unit tests covering: successful worksheet generation, empty-data fallback row, missing-agent-UUID error path, and worksheet dispatch through _get_worksheets.

Why

Customers need visibility into the search terms used by end contacts so they can analyze data directly from the Conversations Report. Exposing this data as an additional worksheet inside the existing report keeps the flow consistent with the other sections (CSAT, NPS, Tool Results, etc.) and reuses the datalake integration already in place.

Sequence diagram

sequenceDiagram
    participant Client
    participant View as ReportsView
    participant Serializer as RequestConversationsReportGenerationSerializer
    participant Service as ConversationsReportService
    participant Settings as Django settings
    participant Datalake as Datalake events
    participant Worksheet as ConversationsReportWorksheet

    Client->>View: POST generate report (sections=[SEARCH_TERMS])
    View->>Serializer: validate payload
    Serializer-->>View: validated data
    View->>Service: generate report
    Service->>Service: _get_worksheets(report, start_date, end_date)
    Service->>Service: dispatch SEARCH_TERMS -> get_search_terms_worksheet
    Service->>Settings: read CONVERSATIONS_METRICS_SEARCH_TERMS_AGENT_UUID
    alt agent_uuid is empty
        Settings-->>Service: ""
        Service-->>View: raise SearchTermsAgentUUIDNotConfiguredError
    else agent_uuid is configured
        Settings-->>Service: agent_uuid
        Service->>Settings: read CONVERSATIONS_METRICS_SEARCH_TERMS_KEY
        Settings-->>Service: search_term_key
        Service->>Datalake: get_datalake_events(event_name=weni_nexus_data, key, metadata_key=agent_uuid, metadata_value)
        Datalake-->>Service: events list
        Service->>Service: translate headers using requester language
        alt events list is empty
            Service->>Worksheet: build worksheet with empty row
        else events list has items
            Service->>Worksheet: build rows (URN, Date, Terms)
        end
        Worksheet-->>Service: ConversationsReportWorksheet
        Service-->>View: worksheets including Search terms
        View-->>Client: report generated
    end
Loading

- Added a new section for search terms in the conversations report.
- Implemented the get_search_terms_worksheet method to retrieve search term data.
- Introduced error handling for missing agent UUID configuration.
- Updated tests to cover the new search terms functionality and ensure proper validation.
- Implemented get_search_term_widget function to check for the existence of the search term widget for a given project.
- Updated ConversationsReportService to include the search term widget in the available widgets list.
- Enhanced unit tests to cover the new search term widget functionality and ensure proper validation.
…eportService

- Removed conditional check for adding the search term widget to the available widgets list.
- Integrated the search term widget directly into the special widgets retrieval process for improved clarity and efficiency.
Base automatically changed from feature/search-terms-metrics to main June 11, 2026 20:49
@kallilsouza kallilsouza merged commit c738a2f into main Jun 11, 2026
3 checks passed
@kallilsouza kallilsouza deleted the feature/search-terms-metrics-report branch June 11, 2026 21:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants