--- sourceDocument: Brazil Platform Analytics sourceDocumentLink: https://www.servicenow.com/docs/r/now-intelligence Release : - brazil ft:locale : - en-US ft:publication_title : - Brazil Platform Analytics ft:clusterId : - par bundleId : - par workflow : - Platform --- # Shipping manual segments via plugins # Shipping manual segments via plugins {#ariaid-title1} Release version: Brazil Updated September 10, 2026 ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 3 minutes to read Business unit application developers can ship manual segments with their applications to provide domain-specific saved searches that work from the moment the app is installed. ## Shipping overview {#shipping-manual-segments-plugins__shipping-overview} Manual segments are the recommended way to ship domain-specific saved searches with your application. They receive a priority boost over automated segments during search, and the LLM is instructed to retain all their filters unless completely irrelevant---whereas automated segment filters are critiqued individually.{#shipping-manual-segments-plugins__shipping-intro} Shipping manual segments with your plugin ensures that users can immediately ask natural language questions about your application's data using business terminology, without waiting for automated segments to be generated from usage patterns.{#shipping-manual-segments-plugins__shipping-benefits} ## How to ship manual segments {#shipping-manual-segments-plugins__how-to-ship} 1. Create your manual segment config records in a development instance. 2. Verify they sync correctly and produce expected search results. 3. Include the sn_query_gen_segment_table_config records in your app's update set. {#shipping-manual-segments-plugins__shipping-steps} ## Plugin installation behavior {#shipping-manual-segments-plugins__installation-behavior} Understanding how manual segments behave during plugin installation is important for setting proper expectations:{#shipping-manual-segments-plugins__installation-intro} * Business rules are **bypassed** during plugin installation---the async sync will not fire automatically at install time. * The records will be synced into sn_query_gen_segment the next time the **Generate Semantic Layer** scheduled job runs (post-install) or when the weekly **Sync Segments** job runs. * Ensure your plugin does not ship duplicate records. There is no unique constraint at the database level---admins must ensure no duplicate names per entity. {#shipping-manual-segments-plugins__installation-notes} Important: Manual segments shipped via plugin will not be immediately available for search after installation. They become active after the next scheduled sync job runs. ## Example: Full configuration for a table {#shipping-manual-segments-plugins__example-configuration} The following example shows manual segments for the incident table that could be shipped with an ITSM application:{#shipping-manual-segments-plugins__example-intro} **Prerequisite:** The incident table must have a record in sn_query_gen_table_config with enable_semantic_generation = true and an active entity.{#shipping-manual-segments-plugins__prerequisite-note} {#shipping-manual-segments-plugins__example-segments__entry__4} | Name | Description | Table | Filter | |-|-|-|-| | Critical Open Incidents | High priority incidents that are currently open and unresolved. Includes all assignment groups. | incident | `priority=1^state!=7^state!=8` | | My Team's Overdue Incidents | Incidents assigned to the current user's group that have passed their SLA due date. | incident | `assignment_group=javascript:getMyGroups()^sla_due=javascript:gs.daysAgoStart(7)` | [Table 1. Example manual segments for incident table] {#shipping-manual-segments-plugins__example-segments} ## Best practices for shipping segments {#shipping-manual-segments-plugins__best-practices} Focus on high-value, high-traffic tables : Concentrate manual segments on the tables your users ask about most. A handful of well-crafted segments on your app's primary tables will have more impact than broad coverage across rarely-queried tables. Use business language, not technical codes : Segment names should match how users naturally speak about your domain. "Critical Open Incidents" is better than "P1_OPEN_INC". Provide descriptions for disambiguation : If you ship multiple segments for the same table, descriptions help the LLM pick the right one. Without descriptions, the LLM may arbitrarily choose between similar matches. Test before shipping : Verify in a test environment that segments sync correctly and appear in search results for relevant utterances. Check the query logs to confirm matching behavior. Avoid duplicating automated segments : Before creating a manual segment, check whether an automated segment already covers the same filter. If one exists but has a poor name, consider improving the source rather than creating a duplicate. {#shipping-manual-segments-plugins__shipping-best-practices} ## Checklist before shipping {#shipping-manual-segments-plugins__checklist} Verify the following before including manual segments in your plugin:{#shipping-manual-segments-plugins__checklist-intro} * Each target table has an active entity in the semantic layer (sn_query_gen_table_config with enable_semantic_generation = true) * Segment names are written in plain user language, not technical shorthand * Descriptions are provided for segments where the name alone may be ambiguous * Filters are valid encoded queries and under 2,000 characters for optimal LLM prompt inclusion * No duplicate records (same name + table combination) exist in your update set * All sn_query_gen_segment_table_config records are included in your app's update set * You have verified in a test environment that segments sync correctly and appear in search results for relevant utterances {#shipping-manual-segments-plugins__shipping-checklist} ## Monitoring after deployment {#shipping-manual-segments-plugins__monitoring-after-deployment} After shipping manual segments with your application:{#shipping-manual-segments-plugins__monitoring-intro} * Monitor which segments are being matched in the query logs * Verify that generated queries are correct for the intended use cases * Collect user feedback on query accuracy and coverage * Iterate on segment names and descriptions based on usage patterns {#shipping-manual-segments-plugins__monitoring-tasks} If a segment is matching but producing wrong results, the issue is usually the name being too generic or the filter being too broad. Refine the name and description before adjusting system properties.{#shipping-manual-segments-plugins__troubleshooting-note} **Related concepts** * [Manual segment data model and sync behavior](https://www.servicenow.com/docs/_gkswBMVWQepDfQQ96bFgQ "Manual segments use a two-table data model with automatic synchronization between the configuration table and the runtime table used for search operations.") * [Guidelines for segments](https://www.servicenow.com/docs/zrzfEZ8GeWveVYIP2xo1bg "Follow these suggestions to help you use segments in the semantic layer effectively.") **Related tasks** * [Create a manual segment](https://www.servicenow.com/docs/bCxcKK~4dXP8WP9xrM~bzw "Manual segments are admin-created saved searches with friendly names that bridge natural language questions and database filters for the Query Generation semantic layer.")