AI Tools Extension Documentation

Overview

The AI Tools extension enables controlled, secure exposure of selected Feature Types and their Attributes for AI-related operations (e.g., vectorization, analysis) while respecting metadata, access control, and code list visibility. Configuration is driven by a single XML file (extensions/ai-tools.xml) that declares pattern-based accessibility rules.

Configuration File Location

Place the file at: extensions/ai-tools.xml inside the project configuration root . If the file is missing, REST endpoints will respond with a configuration error.

XML Schema (Logical Structure)

Root element (BER namespace):

<ber:aiToolsConfiguration>
  <ber:accessibleFeatureTypesArray>
    <ber:featureType ftid="FEATURE_TYPE_PATTERN">
      <ber:accessibleAttributeArray>
        <ber:accessibleAttribute>ATTRIBUTE_ID_OR_PATTERN</ber:accessibleAttribute>
        ...
      </ber:accessibleAttributeArray>
      <ber:excludedAttributeArray>
        <ber:excludedAttribute>ATTRIBUTE_ID_OR_PATTERN</ber:excludedAttribute>
        ...
      </ber:excludedAttributeArray>
    </ber:featureType>
    ...
  </ber:accessibleFeatureTypesArray>
  <ber:accessibleCodelistsArray>
    <ber:accessibleCodelist clid="CODELIST_ID_PATTERN" />
    ...
  </ber:accessibleCodelistsArray>
</ber:aiToolsConfiguration>

Notes

Wildcards: Supported wildcard is * (matches zero or more characters). No regex, no character classes. Example: ft_501* matches ft_501, ft_501A, ft_501_xyz.
Abstract feature types are skipped automatically during resolution.
Attributes are first INCLUDED via accessibleAttribute patterns, then any pattern in excludedAttribute removes matching IDs.
If a feature type entry has no accessibleAttributeArray, it results in an empty attribute set (effectively inaccessible)
Code list columns are only exposed for attributes whose code list matches a pattern and is resolved into accessibleCodelists.

Generated View Definitions

For each of the accesible featuretype a new view will be created in the DB (when synchronizing the DB):

View name format: AI_<FEATURE_TYPE_ID>_VIEW (uppercase preserved as is in code).
SQL built by selecting ft.* plus whitelisted attribute DB column names, joining the feature type container table and attribute table on SID.
Filtering assures only attributes meeting both configuration and code list accessibility make it into the SELECT list.
The created views also implement access control for the AI Agent DB user
Please make sure to define the AI Agent DB user by adding property aiDbUser to configuration properties and make sure such user exists. (Defaults to defaultAiUser)

REST API Endpoints

Base Path: /rest/ai-tools (produces application/json)

1. Search Feature Types

GET /rest/ai-tools/feature-types?query=<text>

Purpose: Fuzzy search among resolved accessible Feature Types.
Input: query (string); empty/blank yields empty result.
Logic: ranks by weighted score (name + description).

Output: Array of FeatureTypeDto objects:

[{"name":"Display Name","ftid":"featureTypeId","description":"..."}]

Limit: Top 5 matches.
Errors: If ai-tools configuration is missing

2. Detailed Feature Type Schema

GET /rest/ai-tools/feature-types/{id}

Purpose: Provide attribute-level schema for a single accessible Feature Type including AI view table name.
Security Checks:
1. User must have QUERY permission on feature type (LidsAccessFeatureType permissions).
2. Attribute list reduced to those where user has both SELECT and FILTER permissions.

Output: DetailedFeatureTypeDto:

{
  "name": "Display Name",
  "id": "featureTypeId",
  "description": "...",
  "databaseTableName": "AI_FEATURETYPEID_VIEW",
  "attributes": [
    {"id":"attrId","name":"Attr Name","dbName":"DB_COLUMN","dataType":"STRING|INTEGER|CODELIST[...]"}
  ]
}

Data type string for accessible code list attributes: CODELIST[name=<name>;dbTable=<table>;columns=(Name=<colName>; dbName=<colDbName>)...].
Errors:
- 403 if missing QUERY permission (ForbiddenException).
- 400 if feature type not found in accessible configuration.
- 500 if configuration missing.

Error & Edge Case Handling

Edge Case	Behavior
Missing `ai-tools.xml`	Capability not registered; endpoints throw configuration error.
Invalid root element	`InvalidMetadataException` aborts parse.
Missing `ftid` / `clid` attributes	Parse error (`InvalidMetadataException`).
Abstract Feature Type matches pattern	Ignored silently.
No attributes matched after excludes	Feature Type accessible with zero attributes (endpoints will likely produce empty attribute list).
User lacks QUERY permission	403 on schema endpoint.
Attribute permission lacks SELECT or FILTER	Attribute omitted from schema response.

Summary

The AI Tools extension safely exposes a curated subset of metadata-defined Feature Types and Attributes through configuration-driven pattern matching and runtime security filtering. It supplies simple discovery and schema endpoints and supports generating SQL view definitions for downstream AI workflows while enforcing both declarative configuration and user permissions.

Overview​

Configuration File Location​

XML Schema (Logical Structure)​

Notes​

Generated View Definitions​

REST API Endpoints​

1. Search Feature Types​

2. Detailed Feature Type Schema​

Error & Edge Case Handling​

Summary​