Stages Documentation

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
712:chatbot_config [2025/08/19 20:54] – Meier, Erich712:chatbot_config [2026/04/10 18:48] (current) – [Disable History] Meier, Erich
Line 5: Line 5:
 You can find more on its [[chatbot|basic usage and functionality here]]. You can find more on its [[chatbot|basic usage and functionality here]].
  
-The paragraphs below describe how to set up, train, and maintain the Stages Assistant.+The sections below describe how to set up, train, and maintain the Stages Assistant.
  
 ===== Acknowledgement of AI-enabled Features ===== ===== Acknowledgement of AI-enabled Features =====
  
-The Stages Assistant uses Generative AI to implement its various capabilities. Although our implementation aims to minimize hallucinations through its knowledge-graph technology, AI-based systems can be imprecise or incorrect, a phenomenon widely known as "hallucinating".+The Stages Assistant uses Generative AI to implement its various capabilities. Although our implementation aims to minimize mistakes through the use of knowledge-graph technology, AI-based systems can be imprecise or incorrect, a phenomenon usually known as "hallucinating".
  
 To make users aware of this fact, each user is required to accept an AI disclaimer before first use. To make users aware of this fact, each user is required to accept an AI disclaimer before first use.
Line 17: Line 17:
 ===== Views and Workspaces ===== ===== Views and Workspaces =====
  
-Processes in Stages exist in many different versions, workspaces, variants, and process instances. AI technologies work best if the scope of the underlying information is clear and well-defined. Combining different process versions, variants, and instances would result in imprecise or even misleading answers. Therefore, multiple Stages Assistants can be defined, one for each //view// on the process landscape.+Processes in Stages exist in many different workspaces and versions, including variants and specific project instances. AI technologies work best if the scope of the underlying information is clear and well-defined; combining the information from all Stages processes would result in imprecise or even misleading answers.
  
-Possible process views are:+Therefore, you must define one or more //views// of the process landscape that scope the processes considered by the Stages Assistant. 
 + 
 +Examples of a process view might include:
  
   * Standard processes that everyone should follow   * Standard processes that everyone should follow
-  * Process variants, e.g. a development process for normal products, one for safety-critical products, one of cybersecurity-critical products, and one for both safety- and cybersecurity-critical products +  * A process variant – for example, you might have separate views for a development process for safety-critical products and the process without safety requirements 
-  * Processes that are especially tailored for specific programs or projects+  * A process tailored for a specific program or process
  
-Views can consist of a single workspace or a collection of workspaces. This way, the standard process view can consist of a workspace containing the standard development process, one or more workspaces containing all organizational processes that are not executed by projects or product teams, and a workspace containing the organizational policies.+Views consist of a single workspace or a collection of workspaces. For example, if you have separate workspaces for the standard development process and other organizational workspaces, you can group them into a workspace collection to include all of that process content in a single view.
  
-Stages Assistants are always trained on the //Valid Version// of the process content in each workspace. This version __must be different__ than the Working Version.+Note: The Stages Assistant is always trained on the Valid Version of the process content in each workspace. The Valid Version __must be different__ than the Working Version; if the Working Version is set to be the Valid Version, the training will fail.
  
-===== Assistant Configuration ===== 
  
-Stages Assistants are configured in the ''Administration > AI > Chatbot'' menu. The main screen shows the currently configured assistant views.+===== Required Permissions ===== 
 + 
 +End users require the following permissions to use the Stages Assistant: 
 + 
 +  * ''Chatbot'': Read 
 +  * ''Workspace'': Read 
 + 
 +To configure the AI assistants, the following permissions are needed: 
 + 
 +  * ''AI Administration'': RCMD 
 +  * ''Workspace'': Read 
 + 
 +In both cases, the permission scope must include the workspaces for the defined view. If the view includes a workspace collection, the permissions must apply to all workspaces within the collection. 
 + 
 +In the Assistant, users will only see the views for which they have read permissions. 
 + 
 +===== Configuring the Stages Assistant ===== 
 + 
 +Configure the Stages Assistant in the ''Administration > AI > Chatbot'' menu. The main screen shows the currently configured assistant views.
  
 {{ :712:chatbotconfig-overview.png?direct }} {{ :712:chatbotconfig-overview.png?direct }}
  
-In addition to the name and the view, you can see the following information:+In addition to the name, you can see the following information for each view:
  
 +  * Workspace or collection assigned to the view 
   * Time and duration of last training run   * Time and duration of last training run
-  * Status+  * Status:
     * Ready: assistant view is fully trained, enabled, and can be used by end users     * Ready: assistant view is fully trained, enabled, and can be used by end users
-    * Disabled: assistant view has been disabled or not trained yet +    * Disabled: assistant view has been disabled or is not trained yet 
-    * Outdated: assistant view can be used for end users, but a newer valid version of one of the workspaces was released. Depending on the training configuration (see below), the view will either be automatically retrained or needs administrators to manually start the training. +    * Outdated: assistant view can be used for end users, but a newer valid version of one of the workspaces was released since it was last trained. Depending on the training configuration (see below), the view will either be automatically retrained or needs administrators to manually start the training. 
-  * Warnings that occurred during training, e.g. missing properties. If those warnings persist, please contact the Stages support or your dedicated Stages consultant. +  * Warnings that occurred during training, e.g. missing properties. If those warnings persist, please contact Stages Support or your Stages consultant. 
-  * Possible actions + 
-    * Edit the view configuration +Use the 3-dot menu to the right of the view to: 
-    * Rename the view + 
-    * Assign workspace or workspace collections (see above for details) +  * Edit the view configuration 
-    * Start training +  * Rename the view 
-    * Delete view +  * Assign or change the workspace or workspace collection (see above for details) 
-    * Enable/disable view+  * Start training 
 +  * Delete the view 
 +  * Enable/disable the view
  
 Clicking on the view name or selecting the Edit action opens the following configuration screen: Clicking on the view name or selecting the Edit action opens the following configuration screen:
Line 55: Line 77:
 {{ :712:chatbotconfig-details.png?direct }} {{ :712:chatbotconfig-details.png?direct }}
  
-In the configuration screen, the following information can be configured:+In the configuration screen, you can modify:
  
-  * //View name// +  * Name of the view 
-  * //Welcome message// that is displayed to the end users when they open the Assistant view. The message should describe the scope of information the Assistant can answer questions about. +  * Domain of the processes contained in the view, e.g. "Product Development Processes". It is not required and can be left blank, unless the Assistant answers are too generic or misleading. 
-  * //Color scheme// so users can visually distinguish the different views +  * Welcome Message that end users see when they access the view in the Stages Assistant. The message should describe the scope of information the Assistant can answer questions about. 
-  * //Default and trained languages.// Please note that each enabled language is trained separately, so enabling multiple languages increases the training costs. Most AI language models are capable of automatically detecting the language of the user questions and automatically answer in the correct language without requiring separate training. Separate trainings for each language are only required if the process content is different, e.g. specific for certain regions. +  * Color used to display user questions in the Assistant, so users can visually distinguish between different views 
-  * //Training schedule// to be selected automatically when new valid process versions are being released or requiring manual interaction +  * Default and trained languages//.// Please note that each language is trained separately, so enabling multiple languages increases the training costs. Most AI language models are capable of automatically detecting the language of the user questions and providing answers in that same language without requiring separate training. Separate trainings for each language are only required if the process content is different in each language, e.g. specific for certain regions. 
-  * //Security level// required by end users to access the assistant view+  * Training schedule, whether training should be run manually or automatically when new valid process versions are released. For workspace collections, where you might be releasing multiple processes within a short time, the 8 or 24-hour delay reduces duplicate training runs. 
 +  * Security level required by end users to access the view, if applicable.
  
-__Please note__ that each view needs to be separately enabled after successful training is run to be usable by the end users.+__Please note:__  You must successfully train and then enable each view in order for end users to access it.
  
-===== Acronym Handling ===== 
  
-The assistant needs to be made aware of company-specific acronyms that are not described in the process models.+===== Defining Acronyms =====
  
-To manage those acronyms, a Stages administrator with edit permission in the new "Acronyms" domain can access the table via ''Administration > Acronyms''.+Company-specific acronyms that are not described in the process models must be defined for the Stages Assistant using the ''Administration > Acronyms'' section. Managing acronyms requires administrator access and edit permissions for the "Acronyms" domain.
  
-For each acronym, its actual expansion and a longer multi-language explanation can be maintained.+For each acronym, you can provide both its expansion and a longer multi-language explanation.
  
-For mass updates, an import and export of CSV files can be accessed via the "''...''" menu.+For mass updates, you can import and export CSV files using the "..." context menu.
  
-===== Required Permissions =====+===== Disable History =====
  
-To use the AI assistants as end users, the following permissions are necessary: +In newer Stages Versions the chat history can be disabled, e.g., to comply with local policies or regulations. Chats and chat messages will not be stored in the database. To disable history, add the following property to conf/config.xml:
- +
-  * ''Chatbot'': Read +
-  * ''Workspace'': Read +
- +
-To configure the AI assistants, the following permissions are necessary: +
- +
-  * ''AI Administration'': RCMD +
-  * ''Workspace'': Read+
  
-For both cases, the permission scope needs to be set to the workspaces the chatbots are trained on. In case workspace collections are being used for chatbot training, all workspaces within all collections need to be covered by the permission scope.+<code xml> 
 +<property name="ai.chatbot.history.enabled" value="false"/> 
 +</code>
  
 ===== Limitations ===== ===== Limitations =====
  
-The context window of the used AI Large Language Models (LLMs) is subject to limitations. To accommodate those limits, the process models are never sent to the LLM in their entirety, but only in select segments that are required to answer the user questions. As a consequence, questions that address whole process models, e.g. "List all work products of all processes", currently cannot be answered.+Large Language Models (LLMs) have a so called context window which has a limited size. To accommodate that limit, Stages never sends the process models to the LLM in their entirety, but only in select segments that are required to answer the user questions. As a consequence, questions that address whole process models, e.g. "List all work products of all processes", currently cannot be answered.
  
-During the training of the assistant, all process elements are transformed into a knowledge graph and stored in special databases. The following elements are currently excluded in this transformation:+During the training of the Assistant, all process elements are transformed into a knowledge graph and stored in special databases. The following elements are currently excluded in this transformation:
  
-  * landing pages +  * Landing pages 
-  * process start pages +  * Process start pages 
-  * "comment only" associations +  * "Comment only" associations 
-  * descriptions that are managed via "''Management > Descriptions''" (except for the inlined ones) +  * Descriptions managed via "''Management > Descriptions''" (except for those used inline) 
-  * graphics that are embedded in element descriptions +  * Graphics embedded in element descriptions 
-  * custom element attributes +  * Custom element attributes 
-  * compliance mappings +  * Compliance mappings 
-  * user-role associations +  * User-role associations 
-  * project files+  * Project files
  
-It is planned, to include those elements in future revisions of the assistant training scripts, if those improve the quality of the given answers.+Such elements might be included in future revisions of assistant training scripts.
  
 Process interfaces to elements outside of the training view (workspace or workspace collection) are ignored. Process interfaces to elements outside of the training view (workspace or workspace collection) are ignored.
  
-To customize the trainings scripts, please contact the Stages support team or your dedicated Stages consultant.+To customize the training scripts, e.g. to have them adjusted to your specific metamodel, please contact your Stages consultant.