Integrating in Application

This section is intended for application developers to integrate Trusted Answer Search into their application and build a natural-language interface. The integration can be done in the following ways:

  1. Portal APEX App A pre-built, end-user facing application that performs search on Trusted Answer Search. Enterprise developers can deploy this app to provide search or chatbot functionality for their end-users.

  2. Search Widgets Pre-built JavaScript widgets that add a search bar or floating search icon to an existing web page. The widgets call Trusted Answer Search through Oracle REST Data Services (ORDS).

  3. PL/SQL Search API If enterprise developers do not use the pre-built APEX Portal App, they can call the DBMS_TRUSTED_SEARCH.SEARCH() PL/SQL procedure directly or invoke it through an ORDS REST endpoint.

APEX Portal Experience

Deploy the Trusted Answer Search portal application when you want to provide a stand-alone search experience for end-users without building a custom UI from scratch.

  1. Administrator setup Your Trusted Answer Search administrator must install the portal app that ships in the installation archive. The setup script provisions the APEX application and makes the portal available at a dedicated URL.

  2. Authorize end-users Search Space Experts (or Search Administrators) must grant each end-user access to the appropriate search space inside the admin app. Only authorized users can sign in to the portal.

  3. Share or link to the portal Application developers can either:

    • Add a link or button in their website that redirects users to the hosted portal URL, or
    • Communicate the direct portal link (for example via email or in-product messaging) so users can access it on demand.

What end-users see

Search Widgets

Use the Trusted Answer Search widgets when you want to embed search directly into an existing application page without building a custom search interface. The widget package includes:

Both widgets use the same ORDS-backed search endpoint and the same configuration attributes. You can deploy either widget independently of the APEX portal application.

Administrator Setup

Before application developers embed a widget, a Trusted Answer Search administrator must install and verify the widget REST endpoints.

  1. Verify prerequisites Confirm that the Trusted Answer Search back-end components are installed and that Oracle REST Data Services is available for the database. On Autonomous AI Database Cloud Services (ADB-S), ORDS is available by default. For on-premises deployments, install and configure ORDS before running the widget installer.

  2. Extract the widget package From the Trusted Answer Search release archive, extract widget_ship.zip.

  3. Configure the widget installer Edit install_widget.conf and provide the database connection, installer user, and TASADMIN password. The installer user must have the privileges required to create the ORDS-backed REST objects.

    Example:

    DB_CONNECT_STRING='myadb_high'
INSTALLER_USER=ADMIN
INSTALLER_USER_PASSWORD=<admin_password>
TASADMIN_PASSWORD=<tasadmin_password>

  4. Configure JWT authentication for production deployments To protect the search endpoints, configure the JWT parameters in install_widget.conf. If JWT_ISSUER, JWT_AUDIENCE, and JWT_JWK_URL are not set together, the endpoints are installed without JWT protection.

    JWT_ISSUER=https://identity.oraclecloud.com/
JWT_AUDIENCE=https://myadb-host.adb.us-phoenix-1.oraclecloudapps.com/ords/trusted-search/
JWT_JWK_URL=https://idcs-example.identity.oraclecloud.com:443/admin/v1/SigningCert/jwk
JWT_SCOPE_NAME=search_access

    For production or internet-facing deployments, configure JWT authentication so search requests run under an authenticated user identity. Without JWT authentication, any client that can reach the endpoint can call it.

  5. Run the widget installer

    cd widget_ship
./install_widget.sh --config install_widget.conf

    The installer registers the widget REST endpoints under <ORDS_BASE_URL>/trusted-search/search-api/.

  6. Verify endpoint access Use the identity/ endpoint to confirm that the endpoint is reachable and that JWT identity resolution works when JWT authentication is configured.

    curl -i -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://<adb-host>/ords/trusted-search/search-api/identity/"

    A successful authenticated response includes the resolved user identity:

    {
  "remote_ident": "user@example.com",
  "tas_ctx_username": "user@example.com",
  "tas_ctx_source": "ORDS",
  "client_identifier": "user@example.com",
  "session_user": "TASADMIN",
  "apex_app_user": null
}

Application Developer Setup

After the administrator installs and verifies the widget endpoints, application developers can host the widget files and embed them into target pages.

  1. Host the widget JavaScript files From widget_ship.zip, copy one or both widget files to a web server or static asset location that your application can load:

    • search_bar_widget.js
    • search_icon_widget.js

    Serve the files over HTTPS when the application page is served over HTTPS.

  2. Embed the widget Add the script tag for the widget you want to use. Set data-ords-search-url to the Trusted Answer Search ORDS search endpoint and data-search-space to the search space that users should query.

    Inline Search Bar:

    <script
  src="/assets/js/search_bar_widget.js"
  data-ords-search-url="https://your-host.example.com/ords/trusted-search/search-api/search/"
  data-search-space="wikimedia">
</script>

    Floating Search Icon:

    <script
  src="/assets/js/search_icon_widget.js"
  data-ords-search-url="https://your-host.example.com/ords/trusted-search/search-api/search/"
  data-search-space="wikimedia">
</script>

    On ADB-S, find the ORDS base URL on the database details page under Tool Configuration, Web Access (ORDS), Public access URL.

    The following image shows an example of embedding the Search Bar widget in a Wikimedia Insights application page:

    Search Bar widget embedded in a Wikimedia Insights application page

  3. Provide the end-user token when JWT is enabled If the administrator enabled JWT authentication for the widget endpoints, the host application must obtain an access token for the signed-in end user and include it as a bearer token when the widget calls the ORDS search endpoint. Use an end-user authorization flow, such as Authorization Code. Do not use a client credentials token for user-facing widget searches because it represents the client application, not the end user.

  4. Optionally configure widget display Define window.SEARCH_WIDGET_CONFIG before loading the widget script to customize display settings.

    <script>
  window.SEARCH_WIDGET_CONFIG = {
    showTargetInputs: true,
    placeholder: "Powered by Oracle Trusted Answer Search",
    debounceMs: 150
  };
</script>

    Supported options are:

    • showTargetInputs: set to true to display target input values beneath each result card.
    • placeholder: sets the placeholder text for the Search Bar widget.
    • debounceMs: sets the delay, in milliseconds, before the widget runs a search after the user stops typing.

    The following image shows widget options defined in the HTML page:

    Widget options defined in the head tag

  5. Confirm network access and CORS Confirm that the application page can reach the Trusted Answer Search ORDS endpoint. If the widget is hosted from a different origin than ORDS, configure Cross-Origin Resource Sharing (CORS) for the ORDS endpoint.

  6. Test the widget Load the page, issue a few searches such as What are the total editors on all Wikimedia pages?, and verify that results are returned from the expected search space. If results do not appear, inspect the browser developer tools for authentication, network, or CORS errors.

Widget REST Endpoints

The widget installer registers the following endpoints under <ORDS_BASE_URL>/trusted-search/search-api/.

identity/

Use the identity/ endpoint to verify that authentication and user identity resolution are configured correctly.

curl -i -H "Authorization: Bearer <ACCESS_TOKEN>" \
  "https://<adb-host>/ords/trusted-search/search-api/identity/"

When JWT authentication is configured, a request without a valid bearer token returns 401 Unauthorized.

search/

The widgets use the search/ endpoint to execute searches. The endpoint accepts the query and search space through HTTP headers.

Header Description
X-Q User search query text
X-N Search space name 
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-Q: What are the total editors on all Wikimedia pages?" \
  -H "X-N: wikimedia" \
  "https://<adb-host>/ords/trusted-search/search-api/search/"

The endpoint resolves the user identity, executes the search through DBMS_TRUSTED_SEARCH.SEARCH, and returns the matching results as JSON.

Widget Visuals

Search Bar:

Search Bar widget showing Wikimedia search suggestions

Search Icon:

Floating Search Icon widget in the Wikimedia Insights application

When selected, the Search Icon opens a conversational search panel:

Search Icon panel opened with Wikimedia search results

Troubleshooting Widget Integration

API Experience

If you need to run searches from your own back-end service, call the Trusted Answer Search PL/SQL procedure. The application developer is responsible for authenticating and authorizing end-users in their application and ensuring they are permitted to query the target search space.

Connect to the Trusted Answer Search database using your preferred driver (JDBC, python-oracledb, Oracle Call Interface, etc.) and execute the packaged procedure in the DBMS_TRUSTED_SEARCH PL/SQL package:

PROCEDURE search (
    p_user_query              IN  VARCHAR2,
    p_search_space            IN  VARCHAR2,
    p_search_space_version_id IN  VARCHAR2 DEFAULT NULL,
    p_search_record           OUT JSON
);

Arguments:

Exceptions / errors:

Example (Wikimedia search space):

DECLARE
  l_result JSON;
BEGIN
  dbms_trusted_search.search(
    p_user_query    => 'italian page views',
    p_search_space  => 'wikimedia',
    p_search_record => l_result
  );

  DBMS_OUTPUT.put_line(l_result.to_string);
END;
/

Sample p_search_record JSON for the query “italian page views”:

{
  "version": 1,
  "id": "b0f4fd97-8f6f-47a7-9ac1-55b1a2c9d5fd",
  "user_query": "italian page views",
  "search_matches": [
    {
      "rank": 1,
      "search_target_id": "7a3f8fb3-6b2d-4cf2-95bb-3c8d329cb6a4",
      "search_target_title": "Page Views by Country Map",
      "match_candidate_type": "SAMPLE_QUERY",
      "original_candidate": "Show page views by country for a language",
      ...
      "score": 0.9142,
      "url": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/page-views-by-country/normal|map|2-year|~total|monthly",
      "target_input_matches": {
        "language": "it",
        "period": "2-year",
        "project": "wikipedia"
      }
    },
    {
      "rank": 2,
      "search_target_id": "2f4d59b9-7de2-4f63-931c-2aaf61b86f3e",
      "search_target_title": "Top Viewed Articles",
      "match_candidate_type": "TARGET_DESCRIPTION",
      "original_candidate": "This report shows the most viewed articles for a selected Wikimedia project and language.",
      ...
      "score": 0.7575,
      "url": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/top-viewed-articles/normal|table|2-year|~total|monthly",
      "target_input_matches": {
        "frequency": "monthly",
        "language": "it",
        "period": "2-year",
        "project": "wikipedia"
      }
    },
    {
      "rank": 3,
      "search_target_id": "697de3c7-0b8f-4d55-a963-5e5cde06ed5a",
      "search_target_title": "Total Page Views",
      "match_candidate_type": "TARGET_DESCRIPTION",
      "original_candidate": "This report shows pageview volume for a Wikimedia project over time.",
      ...
      "score": 0.7418,
      "url": "https://stats.wikimedia.org/#/it.wikipedia.org/reading/total-page-views/normal|bar|2-year|~total|monthly",
      "target_input_matches": {
        "frequency": "monthly",
        "language": "it",
        "period": "2-year",
        "project": "wikipedia"
      }
    }
  ]
}

Use the returned JSON to render answers, links, or actions from your application.