Usage Manual

This page describes how to configure and use the PowerFinder plugin.

Prerequisites

Before using the plugin:

• A PowerFinder instance and its DataStore must be reachable from the CMDBuild server
• You need an access token for PowerFinder and one for the DataStore
• To index attachments, the CMDBuild DMS must be enabled

Supported versions

The plugin is supported starting from:

• CMDBuild 4.3

Configuration

Plugin configuration

To configure the plugin, perform the following steps in the CMDBuild desktop application:

1. Open the subscription section on administration and complete the required fields
2. Install and enable the plugin through the Plugin Manager
3. Open AI → Configurations in the Administration module, check Active and select PowerFinder as the Provider
4. In the Plugin Manager, open PowerFinder and expand Plugin configuration
5. Fill in the connection parameters in the General config tab
6. Define the indexes in the Indexes tab and the contexts in the Contexts tab
7. Click Save in the Plugin Manager to save the plugin configuration

The AI → Configurations page sets these core parameters:

Parameter	Description	Example
org.cmdbuild.ai.enabled	Enables the AI features: global chatbot, AI Assistant widget and Homepage AI search (Active checkbox)	true
org.cmdbuild.ai.service.type	AI provider used by CMDBuild (Provider combo)	powerfinder

The General config tab sets the connection parameters. All of them are required:

Field	Parameter	Description	Example
Url	ai.powerfinder.url	Base URL of the PowerFinder service	https://powerfinder.example.it/powerfinder-v2/api
Token	ai.powerfinder.token	Application token used to call PowerFinder	eyJhbGciOi...
Datastore url	ai.datastore.url	Base URL of the PowerFinder DataStore	https://aicompanion.example.it/datastore/v3/ingestion-api
Datastore token	ai.datastore.token	Token used to call the DataStore	eyJhbGciOi...

The indexes and contexts are stored as JSON in the hidden parameter ai.powerfinder.metadata. The Indexes and Contexts tabs edit it for you. For the full structure, see the Configuration reference.

info

The Save buttons of the index and context forms only keep your changes in the page. The changes are saved in CMDBuild only when you save the plugin configuration in the Plugin Manager.

After the plugin configuration is saved, the plugin updates PowerFinder in the background. It creates, updates or removes the indexes, synchronizes the data and starts the reindexing on PowerFinder. See Data synchronization.

Indexes

An index sends the cards of one class or process to PowerFinder. The Indexes tab lists the configured indexes with their Name, Class/Process, number of Active attributes, Attachments and active status.

To add an index, click Add index and fill in the form:

Field	Description
Class/Process	Class or process whose cards are indexed. You cannot change it after the index is created
Name	Unique code of the index. It defaults to table_<ClassName>. You cannot change it after the index is created
Filters	Optional CMDBuild filter, set with the filter icon. Only the cards that match it are indexed
Attachments	Also index the attachments of the indexed cards. Requires the DMS
Attributes	Attributes sent to PowerFinder. Pick an attribute in Select an attribute, enter its Powerfinder description and click +. The icon at the top right of the list adds all the remaining attributes. Uncheck Active to keep an attribute in the list without sending it
Permissions	Who can query the index, set with Mode. See Access control

Click Save to add the index to the list, then save the plugin configuration to apply it.

The Permissions Mode can be:

• Use permission of class/process (auto): users who can read the class or process can query the index
• Custom (custom): only the groups checked in the list below the mode can query the index

From the row of an index you can also:

• Expand it (+) to see its details, then edit or delete it
• Turn it on or off with the check icon. Inactive indexes are not synchronized and are never queried
• Start an incremental indexing with the green play icon (Indexes). The message Indexing has started in the background confirms the request

Reference and lookup attributes are sent as their description. Lookup arrays are sent as a comma-separated list of descriptions.

Contexts

A context groups the indexes used for a specific kind of request. The Contexts tab lists the contexts with their Context name, Associated indexes and Notes.

To add a context, click Add context, enter a unique Context name, add Notes if you want, and check the indexes under Associated indexes. Only active indexes are listed. You cannot rename a context after it is created.

Two contexts always exist and cannot be deleted:

Context	Used by
default	Global chatbot and requests that do not specify a context
search	Homepage AI search

Both are created empty. Add at least one index to each one you use. A query on a context with no indexes fails.

For an AI Assistant widget, create a context and set its name in the widget configuration.

Data synchronization

The plugin sends to the PowerFinder DataStore, for each active index:

• The active attributes of each card
• The card ID and a deletion flag
• If Attachments is on, the attachment files of each card

The data is synchronized:

• When you save the plugin configuration: new indexes get all the active cards that match the filter. Existing indexes get the cards changed in the last week. Indexes removed from the configuration are deleted from PowerFinder. If you change the active attributes of an index, the index is recreated
• When a card is created, updated or deleted: the card is sent right away. A deleted card is sent with the deletion flag, so PowerFinder removes it from the results
• When you click the Indexes action on an index: an incremental sync of that index, as when you save

When the attachments of a card are sent again, the copies already in the DataStore are replaced.

Using PowerFinder

Once the plugin is configured, the AI features of CMDBuild send their requests to PowerFinder:

• the global chatbot, which queries the default context
• the Homepage search in AI mode, which queries the search context
• the AI Assistant widget, which queries the context set in its configuration

Each request is limited to the indexes the user is allowed to query. See Access control.

When PowerFinder finds nothing relevant, the answer says that the information is not available.

Access control

CMDBuild decides which indexes a user can query. PowerFinder only receives the indexes that pass this check.

An index is allowed for a user when it is active and:

• with mode Use permission of class/process, the user can read its class or process
• with mode Custom, at least one of the user's active groups is in the index's group list

A user with more than one group can query the union of the indexes allowed for each group.

Each request uses one context. The indexes sent to PowerFinder are:

indexes sent = indexes of the context ∩ indexes allowed for the user

Example: the context ticketing contains table_KnowledgeBase and table_Employee. The user's groups allow table_Manuals, table_KnowledgeBase and table_Incident. The query is sent only to table_KnowledgeBase.

Additional information

Known limitations

• One index per class: keep only one active index for each class or process. With more, card changes are not sent
• Filter on card changes: the index filter is applied when the configuration is saved and on manual indexing, but not when a single card is created or updated. A changed card that does not match the filter is still sent
• Incremental sync window: incremental syncs send only the cards and attachments changed in the last week. For older changes, recreate the index
• Attribute types: only simple attribute types can be indexed: text, numbers, booleans, dates and times, references, foreign keys and lookups. If an index contains other attribute types, its synchronization fails
• Custom mode with no groups: an index in Custom mode with no groups selected cannot be queried by anyone

Deployment notes

• The plugin requires CMDBuild core 4.3.0 or later and the CMDBuild AI module
• The plugin uses the first DataStore tenant and the PowerFinder tenant linked to the token
• When the configuration is saved, the plugin removes from the DataStore every index that is not in the configuration. Do not share the DataStore tenant with other CMDBuild instances or applications
• Every change to the configuration starts a sync in the background. With large classes or many attachments the first sync can take a long time. Check the CMDBuild log for errors
• The tokens are stored as password parameters