translate

Signed-off-by: Lada7878 <ladalada7878@gmail.com>

Author: Lada7878

content/documentation/user/ai-agent.md

@@ -0,0 +1,167 @@
+---
+title: AI Agent
+---
+
+This means: take the first element of the `choices` array, then the `message` field, then the `content` field.
+
+For other formats, possible values ​​are `response.text`, `content`, or `answer`.
+
+**How ​​to determine the correct path:**
+1. Make a test request to your API.
+1. Examine the structure of the JSON response.
+1. Find the field containing the model's response text.
+1. Specify the path to this field using dot notation.
+
+#### Request Body Template
+
+The **Request Body Template** field defines the structure of the JSON request that will be sent to the provider's API. You can use variables in the template, which will be automatically replaced with the relevant values.
+
+**Available variables:**
+- `{{.prompt}}` — the text of the user's question (will be automatically escaped for JSON).
+- `{{.model}}` — the model name specified in the provider settings.
+
+**Template examples:**
+
+For OpenAI-compatible APIs:
+
+```json
+{
+"model": "{{.model}}",
+"messages": [
+{
+"role": "user",
+"content": "{{.prompt}}"
+}
+],
+"temperature": 0.7
+}
+```
+
+For APIs with a different format:
+
+```json
+{
+"messages": [
+{
+"content": "{{.prompt}}",
+"role": "user"
+}
+],
+"model": "{{.model}}",
+"stream": false
+}
+``
+
+For APIs with a minimal request structure:
+
+```json
+{
+"query": "{{.prompt}}",
+"model_name": "{{.model}}"
+}
+```
+
+**Important:**
+- The template must be valid JSON. - The `{{.prompt}}` and `{{.model}}` variables will be automatically replaced when sending the request.
+- The `{{.prompt}}` value is automatically escaped for safe insertion into JSON.
+- You can add any additional fields required for your API (temperature, max_tokens, etc.).
+
+**Example of a complete custom provider setup:**
+
+1. **Name**: `My Custom API`.
+1. **Provider**: `Custom`.
+1. **Model**: `my-model-v1`.
+1. **URL**: `https://api.example.com/v1/chat`.
+1. **Method**: `POST`. 1. **Headers**:
+
+```sh
+Authorization: Bearer {{ .credentials.api_key }}
+Content-Type: application/json
+```
+
+where `api_key` is the name of the credential key (see the [Credentials for Providers](#credentials-for-providers) section).
+
+1. **Response Field**: `choices.0.message.content`.
+1. **Request body template**:
+
+```json
+{
+"model": "{{.model}}",
+"messages": [
+{
+"role": "user",
+"content": "{{.prompt}}"
+}
+],
+"temperature": 0.7,
+"max_tokens": 1000
+}
+```
+
+## Working with the AI ​​Agent
+
+### Opening Chat
+
+The AI ​​Agent is accessible through the chat sidebar on the right side of the interface. To open the chat, click the chat button in the lower right corner of the screen.
+
+### Selecting a Provider
+
+At the top of the chat is a provider selector. Select the desired provider from the list of available ones. If you only have one provider configured, it will be selected automatically.
+
+### Available Tools (MCP Tools)
+
+The AI ​​Agent uses MCP (Model Context Protocol) tools to work with the platform. A complete list with descriptions, parameters, and examples is provided in the [MCP server documentation](../user/mcp-server/).
+
+The model can call multiple tools in a single request if needed.
+
+Key features:
+- Retrieving and analyzing data from the platform catalog.
+- MCP proxy to external services (GitLab, SonarQube, Kubernetes, etc.) via `get_external_data` — requests are executed with user credentials.
+
+### Viewing Available Tools
+
+The chat displays a list of all available tools with their descriptions and usage examples. You can:
+
+- Expand the **Available Tools** section to view the list.
+- Expand each tool to view its parameters and examples.
+- Click on an example to paste it into the input field and immediately execute or edit the request.
+
+### Features
+
+1. **Data Analysis**: The AI ​​agent doesn't just return raw data; it analyzes it and provides structured responses.
+1. **Filtering**: You can request data with conditions, and the agent will perform the filtering.
+1. **Aggregation**: The agent can count, group data, and provide statistics.
+
+### Debugging
+
+If the agent's response seems incorrect, you can view the debug logs by clicking the question mark icon next to the response. This will help you understand which tools were called and what data was retrieved.
+
+## Usage Examples
+
+### Example 1: Service Analysis
+
+**Question:**
+
+```sh
+Get all services and show their name and creation date
+```
+
+**Result:**
+The agent uses MCP tools to retrieve service data and returns a list with their name and creation date.
+
+### Example 2: Action List
+
+**Question:**
+
+```sh
+Get a list of actions
+```
+
+**Result:**
+The agent will call the MCP tool and return a list of available platform actions.
+
+## Recommendations
+
+1. **Use specific questions**: The more specific the question, the more accurate the answer.
+1. **Specify parameters explicitly**: If you know the name of a resource or parameter, specify it in the question.
+1. **Experiment**: The AI ​​agent understands natural language, so try different question formulations.

content/documentation/user/catalog.md

@@ -0,0 +1,122 @@
+---
+title: Catalog
+weight: 30
+---
+
+The catalog is a section of the platform that contains a list of all resources, their parameters and relationships, and allows users to run scripts for resource entities.
+
+The catalog can be populated manually or automatically using data sources or webhooks.
+
+## Resources
+
+A resource is a template or entity type in the platform catalog. A resource defines the data structure, parameters, and properties that all entities of a given type will inherit. For example, the "GitLab Repositories" resource describes the data structure for GitLab repositories, and each specific entity of this resource represents a separate repository.
+
+The fundamental principle of the platform is that the data model is configured by the platform administrator. The administrator can independently create the resources they need.
+
+### Resource Naming
+
+When naming resources, follow these rules:
+
+- **Resource Name** can be any name and does not require special prefixes or separators. - The **Resource ID** must be unique across the entire platform.
+
+### Resource Grouping
+
+Resources in the catalog can be organized hierarchically, allowing for logical grouping of related resources and improving catalog navigation.
+
+To create a resource group, you need to:
+
+1. **Create Resources** — create all the necessary resources that will be included in the group. For example, the "Gitlab" resource could be the parent of "Repositories," "Groups," and other resources.
+
+2. **Link Child Resources to Parent Resources** — in the catalog sidebar, drag the child resource onto the parent resource. Child resources will be automatically linked to the parent and appear in the interface as nested elements.
+
+3. **Configure Display** — in the catalog sidebar, parent resources are displayed with an expand/collapse icon, allowing you to show or hide child elements.
+
+{{< alert level="info" >}}
+Changing resource grouping (dragging and dropping resources in the catalog sidebar) requires the global `update:resources-order` permission. For more information on access rights, see the ["Role Model"](../../admin/security/rbac/).
+{{< /alert >}}
+
+{{< alert level="info" >}}
+To view a child resource, the user must have `read:resources` permissions for the entire hierarchy of parent resources. For more information on access rights, see the ["Role Model"](../../admin/security/rbac/).
+{{< /alert >}}
+
+#### Displaying the Full Path
+
+The platform interface (resource selectors, tags, relationship graphs) displays the full resource path with the chain of parent resources separated by the `/` character. For example, if the "Repositories" resource is a child of the "Gitlab" resource, the interface will display "Gitlab / Repositories."
+
+### Resource Card
+
+By default, after creating a resource, its card will display a table of entities for that resource. Clicking on an entity in the table takes you to its card.
+
+If a dashboard is selected in the "Use Dashboard" field, it will be displayed on the resource card instead of the entity table.
+
+### Relationships between Resources
+
+Each resource can be linked to another resource or to itself via a two-way relationship. Relationships are configured by the platform administrator. After setting up relationships for a resource, each entity in that resource can be linked to one or more entities in another resource.
+
+You can create both vertical relationships (an entity from one resource is linked to an entity from another resource) and horizontal relationships (entities within a single resource are linked).
+
+## Entities
+
+An entity is a specific unit of each resource. For example, if a resource is called "Groups" and is a child of the resource "Gitlab," then each Gitlab group registered in the platform is an entity of that resource.
+
+Entities inherit resource parameters, but parameters can be specified separately for each entity.
+
+### Naming Entities
+
+When naming entities, follow these rules:
+
+- **The entity name** can be any name and does not require special prefixes or separators.
+- **The entity ID** must be unique within the resource.
+
+### Entity Card
+
+The entity card consists of built-in panels and custom panels. Built-in panels:
+
+- **Overview** — contains blocks indicating the entity's owner, description, parameters, and relationships.
+- **Action Triggers** — contains a list of actions that have been triggered for this entity.
+- **Process Starts** — Contains a list of processes that have started for this entity.
+- **Events** — Contains a list of events generated for this entity.
+
+New dashboards can be added to each entity card.
+
+Adding dashboards to one resource entity applies to all entities within that resource.
+
+### Relationships between entities
+
+Relationships for each entity are displayed in the entity card as a table and a graph. Each entity can be linked to one or more entities of the same or different resource, depending on the configured relationships between resources.
+
+Relationships between entities can be created manually or automatically using data sources or webhooks.
+
+### Events
+
+When the specification of any entity is created, deleted, or modified, an event of the corresponding type is generated: ENTITY_CREATED, ENTITY_DELETED, or ENTITY_UPDATED. These events serve the following purposes:
+
+- **Audit** — recording changes occurring to an entity during its lifecycle.
+- **Configure automated reactions** — configure reactions to changes in the entity specification.
+
+The event storage time is limited and can be configured through the platform configuration file.
+
+### Exporting Entities to CSV
+
+The platform provides the ability to export entities to a CSV file for subsequent data analysis and processing.
+
+#### Exporting Entities for a Single Resource
+
+To export entities for a specific resource:
+
+1. Open the resource card in the catalog.
+2. In the entity table, click the **Download .csv** button.
+3. The exported file will include all resource entities, taking into account the applied filters, sorting, and pagination.
+
+#### Exporting Entities from Multiple Resources
+
+To export entities from multiple resources simultaneously:
+
+1. In the catalog sidebar, click the **Download Entities** button.
+2. In the dialog box that opens, select one or more resources.
+3. Click the **Download .csv** button.
+4. All entities for the selected resources will be combined into a single CSV file.
+
+{{< alert level="info" >}}
+Unloading entities requires the global `read:entities` permission. For more information on access rights, see the [Role Model](../../admin/security/rbac/) section.
+{{< /alert >}}

content/documentation/user/credentials.md

@@ -0,0 +1,28 @@
+---
+title: Credentials
+menuTitle: Credentials
+d8Edition: ee
+moduleStatus: experimental
+---
+
+Credentials are a mechanism for securely storing and using access credentials to external services (tokens, passwords, API keys, etc.) in the DDP platform.
+
+## How it works
+
+All interactions with infrastructure services in DDP occur using the credentials of a specific user. Credentials are encrypted before being stored in the database and are decrypted only when needed in actions, data sources, and widgets.
+
+For more information on how they work, encryption, and configuration, see the [documentation](../../admin/security/credentials/).
+
+## Filling in credentials
+
+The platform administrator creates credential types in the "Administration" → "Credentials" section. For each credential type, you can specify your personal details in the "Credentials" section of your profile.
+
+For example, if an administrator created the **Kubernetes token** credential type, you can add a personal token for Kubernetes access in your profile.
+
+## Working with Credentials
+
+- After saving credentials, you cannot view their value; you can only update it.
+- Your profile displays information about whether certain credentials are filled in.
+- Credentials are used automatically in actions, data sources, and widgets where they are specified in the configuration.
+
+The approach to using credentials in actions, data sources, and widgets is described in the relevant sections of the documentation.