User Interface

The jmix-aitools-flowui-starter provides a complete chat UI with ready-to-use views, reusable fragments that you can embed into your own views, and the supporting services. Access to the UI is governed by the chat user role.

Views

The add-on registers two views out of the box.

View Description

AiChatHubView

The chat hub: a landing view with the message composer, the user’s recent conversations, and a searchable, date-grouped history. It is added to the main menu automatically.

AiChatView

A single conversation view. It is opened from the hub for a selected conversation, or without one to start a new chat.

Because the add-on contributes a menu item for AiChatHubView, users with the chat role get an entry point without any additional configuration. The menu item is added through the composite menu mechanism.

Fragments

When the built-in views do not fit your layout, you can embed the chat UI into your own views by using fragments. Add a fragment to a view descriptor with the <fragment> element and reference its class.

AiChatHubFragment

io.jmix.aitoolsflowui.view.chathub.AiChatHubFragment is the self-contained chat hub used by AiChatHubView. Add it to any view to get the composer, recent chats, and history in one component:

<fragment id="chatHubFragment"
          class="io.jmix.aitoolsflowui.view.chathub.AiChatHubFragment"/>

Its public API:

  • setRecentChatsCount(int) – overrides how many recent chats are shown next to the composer. When unset, the value comes from the jmix.aitools.ui.chat-hub-recent-chats-count application property.

  • setMarkIconSupplier(SerializableSupplier<Component>) – replaces the brand mark icon shown on the hub and on conversation cards.

AiChatFragment

io.jmix.aitoolsflowui.view.chat.AiChatFragment is the conversation panel used by AiChatView. It contains a title row, the message timeline, and the composer, all bound to one conversation. Embed it and bind a conversation programmatically:

<fragment id="chatFragment"
          class="io.jmix.aitoolsflowui.view.chat.AiChatFragment"/>
@ViewComponent
private AiChatFragment chatFragment;

@Autowired
private AiConversationService conversationService;

@Subscribe
public void onInit(final InitEvent event) {
    AiConversation conversation = conversationService.create();
    chatFragment.setConversation(conversation);
}

Key methods:

  • setConversation(AiConversation) / setConversationId(UUID) – binds the panel to a conversation.

  • sendMessage(String) – submits a user message programmatically.

  • setReadOnly(boolean) – hides the composer and the title edit button.

  • setMessageInputEnabled(boolean) / focusMessageInput() – controls the composer.

  • isAwaitingResponse() – indicates whether a reply is currently being generated.

  • setAiAvatarIconSupplier(SerializableSupplier<Component>) – customizes the assistant avatar.

AiChatInputFragment

io.jmix.aitoolsflowui.view.input.AiChatInputFragment is the reusable message composer: a text area plus a send button. Press Enter to submit the message. Press Shift+Enter to insert a newline. It is used inside the two fragments above, and you can also embed it on its own when you build a custom chat layout. Configure it with setSubmitHandler(Consumer<String>), setPlaceholder(String), setInputEnabled(boolean), focus(), and clear().

Services

The UI is backed by three services. They operate on the UI models AiConversation and AiChatMessage and are implicitly scoped to the current user.

Service Responsibility

AiChatService

Generates the assistant’s reply to a user message.

  • processMessage(message) – returns the reply.

  • processMessage(message, statusCallback) – same as above, but reports progress through a Consumer<AiToolStatusUpdate>.

  • isAvailable() – whether replies can be produced, that is, whether a model is configured.

AiConversationService

Manages the current user’s conversations.

  • loadConversations() – loads the user’s conversations, newest first.

  • loadConversation(id) – loads one conversation by ID.

  • create() – creates a new conversation.

  • save(conversation) – persists a conversation.

  • remove(conversation) – deletes a conversation and its messages.

AiChatMessageService

Manages the messages of a conversation.

  • createMessage(…​) – adds a message of a given type.

  • loadMessages(conversation) – loads all messages, oldest first.

  • loadLatestMessage(…​) – loads the most recent message, optionally by type.

Persistence and Empty Implementations

Where these services store data depends on which starter is present:

  • With jmix-aitools-flowui-data-starter, the services are backed by JPA entities, and conversations and messages are persisted in the database.

  • With only jmix-aitools-flowui-starter, the services are no-op stubs. AiChatService.isAvailable() returns false, nothing is persisted, and the chat is effectively disabled. This lets the UI render before persistence is in place.

To use the chat with non-default storage, provide your own beans that implement AiChatService, AiConversationService, and AiChatMessageService instead of adding the data starter.

Icon Provider

The brand icon shown on the hub and the assistant avatar is supplied by the AiIconProvider bean. Replace this bean to change the add-on’s iconography globally, or override it per fragment with the icon supplier setters shown above.

Security Role

The add-on provides one predefined resource role.

Name

AI Tools: chat user

Code

aitools-chat-user

Scope

UI

It grants an end user access to the chat: the chat hub and the conversation view, plus management of their own conversations and messages, including starting, continuing, renaming, and deleting chats. Specifically, the role grants:

  • view access to AiChatHubView and AiChatView, and to the menu item for the chat hub

  • full access to the user’s own conversations, and create/read access to their messages

Assign this role to every user who should be able to use the assistant. See Users for how to assign roles to users.

The role grants access only to the chat UI. It does not widen data access. When the assistant loads business data through the predefined data-load tools, the queries run under the current user’s own data access permissions, so the role does not let a user read anything they could not otherwise read. Any custom tools you add are responsible for their own access control.