Getting Started

Admin Setup

Installation

Download the Trusted Answer Search installation archive from https://oracle.com/downloads. After downloading, open the archive and follow README.md to deploy all components—including the backend services and the APEX administrative and portal applications.

Quick Start

When installation completes, open the apex_ship/QUICK_START.md guide inside the archive. Use the walkthrough to import the sample Wikimedia Stats or Trusted SQL search space and run search queries from the portal app to validate the deployment.

Creating Search Spaces

If you skipped the sample import in the Quick Start guide—or if the brokerage search space was not created automatically—you can add it manually in the admin app using the steps below.

Sign in with your Search Administrator or Search Space Expert credentials. You may use the privileged tasadmin account for the same.

Then, choose Search Spaces in the left navigation. The table lists every search space that currently exists.
Select Create Search Space (or edit an existing entry) to open the configuration drawer. Provide a concise internal Name such as BROKERAGE, then focus on the fields that power the end-user portal experience:
- Search Space Title shown in the Portal App – the heading displayed above the results rail.
- Description shown in the Portal App – a short paragraph that tells users what queries this space answers.
- Search Bar Placeholder Text in the Portal App – the hint text that appears inside the search box.
These strings are customer-facing, so invest the same care you bring to marketing copy: write clear, contextual guidance that matches the intent of your audience.
Click Create. The new search space appears in the table and can now hold search targets. Now, you can proceed to creating search targets.

Building Search Targets

Use the admin app to curate search targets that surface reliable answers for every user query. The steps below illustrate how to create a “Learn Margin Trading” search target inside the brokerage search space.

Sign in to the admin console with the Search Administrator credentials. After authentication you land on the dashboard — note the global Search Space selector in the header at top-right.
Open the Search Space dropdown and choose brokerage, then click Search Targets in the left navigation to load the catalog for that space.
Click Create Target on the top-right of the page. The form opens with three steps. Provide the general metadata first.
- Search Target Title – Learn Margin Trading
- Search Target Description – The target description should semantically describe what this target is about. Note that this description is used during the retrieval process of Trusted Answer Search and directly impacts the search quality. So, it is very important to write this well.
  
  Enter this description:
  Explains how margin accounts work, eligibility requirements, and risk management techniques for trading with borrowed funds.
In Step 2: Select Target Action, select URL and paste https://www.brokerage123.com/learn/trading/margin into the URL field. The form validates the link automatically.
In Step 3: Add Sample Queries, supply realistic prompts that should retrieve this target. Each sample query must mirror the language your app’s end-users naturally uses — specific scenarios and intent-driven phrasing guide semantic matching.

Enter the following queries into the Sample Query box and click Add Sample Query after every entry. For example:
- how does margin trading work
- margin requirements for stock trades
- risks of trading on margin
As you add them, the table beneath the input lists the saved queries.
Click Create Search Target. The button is enabled once a title, description, and target action (URL/SQL) is added. The new “Learn Margin Trading” target immediately appears in the brokerage catalog.

Note that this search target will not appear in the search results yet because you have not PUBLISHED this DRAFT search space version yet. We will publish the search space version once we are done making all the edits.

Search Space versioning is explained later in this document.

Configuring Target Inputs

Some reports require a parameter—such as a ticker symbol, account number, region, or date range—before they can resolve to the correct dataset. Instead of creating hundreds of near-duplicate search targets, use Target Inputs so Trusted Answer Search can inject the user’s intent directly into the action URL or SQL.

For instance, if you create an “Index Level and Performance” search target, the static report URL https://brokerage123.com/markets/index?symbol=GSPC shows the S&P 500 index level, while …?symbol=DJI displays the Dow Jones index. Rather than managing two separate targets, parameterise the action URL and map the placeholder to a Target Value Set:

https://brokerage123.com/markets/index?symbol=:INDEX_SYMBOL

From Search Targets, click Create Target to create an “Index Level and Performance” search target.

Title: Index Level and Performance
Description: This report shows a market index’s latest level, recent performance, and trend analysis.
Under Step 2: Select Target Action, select URL and paste the parameterized link https://brokerage123.com/markets/index?symbol=:INDEX_SYMBOL. The app automatically detects the :INDEX_SYMBOL placeholder and exposes a Target Inputs table beneath the URL.
Click Create New Target Set to launch the Add Target Value Set dialog.

Name: Index Symbols
Description: List of short codes for stock indexes
Target value sets can be maintained manually (static list) or sourced from a table column that you refresh on demand. For this example choose Manual Input, then add rows for GSPC (synonyms: S&P 500, S and P 500) and DJI (synonyms: Dow Jones, Dow Jones Industrial Average).
Save the value set and select it from the Target Value Set dropdown so the INDEX_SYMBOL row reads INDEX SYMBOLS. The table now shows which value set will supply runtime substitutions.
Provide sample queries that align with the placeholders your users will mention—e.g.,
- S&P 500 index level
- Dow Jones closing performance
- GSPC returns
These examples help semantic matching route the request to the correct target.

With the mapping in place, a search query such as “S&P 500 index level” resolves :INDEX_SYMBOL to GSPC, and Trusted Answer Search returns the fully qualified link https://brokerage123.com/markets/index?symbol=GSPC. Use the same pattern for table-driven value sets when a data team owns authoritative lists—simply point the target input at the refreshed table column instead of entering static rows.

With the new target saved, move on to publishing the draft search space version so end-users can reach the updated catalog.

Managing Search Space Versions

The following section allows a Search Administrator or Search Space Expert to review and promote changes to a search space.

From Search Spaces, locate the search space you are working on—in this example, BROKERAGE. The status column shows the current draft alongside any published version so you can confirm that edits are isolated to a draft.
Click BROKERAGE to open the versions dashboard. The version list (left) and version tree (right) surface the active draft at the top of the chain so you can verify it is still in Draft state before proceeding.
Select Current Draft Changes to check what has been added or updated in this draft version. The view highlights the new “Index Level and Performance” search target along with the newly-added Index Symbols value set.
Use the action menu (three dots) next to the draft version and choose Regressions to inspect whether previously-answered queries would degrade after publishing. Click Confirm on the Regressions Analysis popup and proceed to viewing the regressions. Review the reported regressions. There should not be any regressions in this example, as shown in the image below.
From there, return to the Search Space versions view, open the action menu (three dots) next to the DRAFT search space version again and choose Publish to promote the draft. Publishing makes the search space version available to end-users to query.

With the draft changes published, add an end-user who can query the brokerage search space.

Managing User Access

Trusted Answer Search uses Oracle Database authentication, so every user (i.e., Search Administrator, Search Space Expert, or Search Space User) must exist as a database account before you can authorize that user to access the Trusted Answer Search application.

The following steps add a Search Space User called tasuser. Run the following statement (or ask your Database Administrator) to provision a search-only account:

create user tasuser identified by tasuser;

Sign in to the admin app as tasadmin, choose Users in the left navigation, and confirm that the brokerage workspace is selected in the header. The report lists existing administrators, experts, and search-only users.
Click Add User to open the drawer. Enter tasuser, check only the User role, and pick brokerage from the Search Space list so the new account is scoped correctly. Finish by clicking Add.
The Users table immediately shows TASUSER. Select the username to review the access drawer. The Search Space Access region confirms that the account has User access to brokerage; add or revoke other spaces here as needed.

After adding the search space user, sign in to the brokerage search space using that account.

Querying on Portal App

Launch the portal application in a fresh session and sign in with tasuser / tasuser.
After login, pick BROKERAGE from the Search Space menu, type Show me the S&P 500 level into the question box, and submit the search. The top result returns the “Index Level and Performance” target with the index value set to GSPC. Notice that Trusted Answer Search extracted the S&P 500 reference from the user query and substituted the value GSPC from the Index Symbols Target Value Set in the URL.
Selecting Index Level and Performance opens the curated brokerage report in a new browser tab. The link resolves to https://brokerage123.com/markets/index?symbol=GSPC, which displays the latest S&P 500 index performance metrics.

Once the sample query is working end-to-end, explore how a Search Space Expert can improve search results over time.

Human-in-the-loop refinement

Search Space Experts can influence the search target retrieval by rewarding accurate answers and suppressing noisy matches.

All feedback (upvotes and downvotes) is stored against the DRAFT search space version (or against a published version when Settings → Edit Published Versions? is set to Yes). For this example, set Edit Published Versions? to Yes.
Let’s first establish a baseline: in the Portal app, search for “mutual funds” and note that “Mutual Funds Investing” target appears ahead of “Mutual Fund Research”.
In the Admin app, open Search History, click on the mutual funds query, and inspect that. The interactive report lets you drill into the exact ranking the user saw.
From the query drawer, click Upvote on the “Mutual Fund Research” card to promote it. An admin might do this when they want Mutual Fund Research to lead the answer rail because that is the report their end-users care about most. The success banner confirms that the adjustment is recorded in the current (draft) search space version.
Re-run the mutual funds query in the portal. The promoted target “Mutual Fund Research” now occupies Rank 1 and the previous leader shifts down.
Back in the query drawer, locate “Tax Forms & Information” and click Downvote to demote the noisy match.
Re-run the query in a fresh portal session. The downvoted card drops out of the top answers, letting a more relevant result enter the slate.
End-users can also react in real time by giving a thumbs up 👍 or thumbs down 👎 on the Portal app. The thumbs buttons on each card capture proposed votes by the end-user—“Mutual Fund Research” earns a 👍 while “Tax Forms & Information” gets a 👎 in the example below.

End-user upvote on the Portal app:

End-user downvote on the Portal app:

Note that the Portal app feedback is advisory: Trusted Answer Search’s ranking engine ignores it until a Search Space Expert reviews and confirms the suggestion in the admin app.
Go back to the Admin app. The Search History report highlights queries with pending signals in the User Feedback column.
Click the 👍 or 👎 icon to open the drawer, review who voted, and apply the change with the Confirm Upvote / Confirm Downvote buttons or provide your own feedback.

Review and Confirm end-user feedback:

Confirmed Upvote/Downvote:

Human-in-the-loop refinement keeps your published experience aligned with user intent—reward the search targets that answers the question correctly, demote bad or stale matches, and let experts guide the Trusted Answer Search retrieval process.