Using the Search Assistant
Follow the steps below to access and use the Search Assistant for semantic search in Codebeamer.
Accessing the Search Assistant
1. Go to the AI Assistant tab on the main menu on the Codebeamer homepage.
 |
The AI Assistant tab and its submenu Search Assistant are visible to all users. However, the Search Assistant feature is available only to the users who are a member of the AI Users group. The system validates access only after the page loads.
|
2. Select Search Assistant. The Search Assistant page opens.
|
|
If you are not a member of the AI Users group or a System Administrator as required by the feature rules, an entitlement error message appears.
|
The Search Assistant page has a two-panel layout:
• Left filter panel — Contains the scope and filter controls. You can collapse the left filter panel to expand the results panel.
• Right results panel — Displays the semantic search results.
Configuring the Search Scope — For Codebeamer Versions 3.1 and Later
1. In the Search for field, enter a natural-language semantic query. The Search for field drop-down displays the five most recent search strings when the field is focused.
|
|
• Describe your query in as much detail as possible and provide relevant context to improve the quality of the results. For example, instead of "test data security", use "requirements related to test data security" to receive more precise results.
• The Search for field supports a maximum limit of 500 characters.
|
2. Select one or more streams in the Select Streams drop-down menu.
|
|
• The default selection is All Streams.
• Hidden streams are included in search results and appear under a separate “Hidden Streams” group.
|
3. Select one or more projects in the Select Projects drop-down menu.
|
|
• The menu lists only projects to which you have access.
• The projects displayed are based on the selected streams. Changing the streams resets the list to All Projects.
• Only fully indexed projects appear in the Select Projects drop-down menu. Projects undergoing first‑time indexing do not appear in this list. Ensure that you check the last indexed details for each project in the Select Projects drop-down menu.
|
4. In the left filter panel, select the entity type to include in the search:
◦ Items: Select items to enable selection of the following item fields:
▪ Text Fields: Includes all text and wiki text fields from items in the selected project.
▪ Item Comments: Includes all item comments from items in the selected project.
▪ Review Comments: Includes all review comments for the items.
|
|
In all supported versions of Codebeamer, the Review Comments option is displayed only if the parent project is part of the filter selection and if Review Hub has been enabled for indexing.
|
◦ Wikis: Includes content from the wiki pages.
5. Click Search. The search results are displayed in the right panel.
6. Select a result to open the corresponding item, wiki page, or review in Codebeamer.
Configuring the Search Scope — For Codebeamer Version 3.0
1. In the Search for field, enter a natural-language semantic query. The Search for field drop-down displays the five most recent search strings when the field is focused.
|
|
• Describe your query in as much detail as possible and provide relevant context to improve the quality of the results. For example, instead of "test data security", use "requirements related to test data security" to receive more precise results.
• The Search for field supports a maximum limit of 500 characters.
|
2. Select one or more projects in the Select Projects drop-down menu.
|
|
• The menu lists only the projects to which you have access.
• The list updates based on the selected working-sets; changing the working-sets resets the list to All Projects.
|
3. Select one or more working-set in the Working-Sets drop-down.
|
|
• The system filters working-sets based on the selected projects.
• Changing projects resets working-sets to All Working Sets.
|
4. In the left filter panel, select the entity types to include in the search:
◦ Items: Select items to enable selection of any or all of the following item fields:
▪ Text Fields: Includes all text and wiki text fields from items in the selected project.
▪ Item Comments: Includes all item comments from items in the selected project.
▪ Review Comments: Includes all review comments for the items.
|
|
In all supported versions of Codebeamer, the Review Comments option is displayed only if the parent project is part of the filter selection and if Review Hub has been enabled for indexing.
|
◦ Wikis: Includes content from the wiki pages.
5. Click Search. The search results are displayed in the right panel.
Understanding the Search Assistant Results
• Each result displays a similarity score as a percentage. A higher score indicates a closer match to the search phrase.
• Similar results from multiple streams, including hidden streams, are grouped into a single group.
• Clicking a result opens the corresponding Codebeamer item, wiki, or review.
• Search results of the type document include the 
icon that you can click to open the result directly in Document View.
icon that you can click to open the result directly in Document View.• Each result displays the References option. The References option displays the combined total number of references and associations for the item.
|
|
If there are no references or associations for the item, the References option is not displayed.
|
• Selecting the References option opens the upstream and downstream references and associations for the item.
• Clicking the link to the references and associations directly opens the corresponding item in a new browser tab.
• If there are no matching results, the system displays a message.
|
|
If the search results, similarity scores, or result order are not as expected, refine your query by rephrasing it or adding more relevant context.
|
Key Considerations
• Before search is executed, the items for which you do not have read permission are automatically filtered out. Only the items to which you have access are returned in results.
• The ranking of search results includes only items that you are permitted to read. It is not influenced by fields for which you do not have field-level read access.
• The Summary or Title field is a mandatory field. If you do not have read access to this field, the entire item is excluded from the search results.
• Review Hub comments are returned as search results only if the items under review belong to a tracker that is included in the index.
• Incremental indexing updates may be delayed. Ensure that you check the Last Modified timestamp on the search results panel.
• Searching for exact terms or IDs may not provide the most accurate results. For keyword-based searches, use Codebeamer's Advanced Search feature. For more information, see Searching.
Known Limitations
• Search results include a similarity score to indicate relevance. While results are intended to be ranked accordingly, the current display order may not always consistently follow descending similarity scores across pages. As a result, highly relevant results might appear on later pages rather than at the top of the first page. PTC plans to address this limitation in a future release.
• When the search term exactly matches the summary or description of a result, the similarity score may still be lower than 100%. This is because the AI model evaluates the content along with additional context provided.
• Because Search Assistant uses semantic search, the results may include artifacts that are conceptually related to your query.