Feature ETP-3879: Improve Task doc based on feedback

docs/developer-guide/etendo-classic/bundles/platform/task.md

@@ -21,16 +21,33 @@ The system processes tasks in response to events that occur within Etendo, such
 
 ## Initial Configuration
 
-### PostgreSQL Configuration for Connect (Debezium) Use
+### Configure PostgreSQL for Debezium Change Capture
+
+Debezium is a change-data-capture tool that monitors your database for row-level changes and forwards them to Kafka. The two SQL commands below enable that monitoring on the Etendo database.
+
+The database name is the value of `bbdd.sid` in `gradle.properties` (typically `etendo`), and the connection must use the PostgreSQL system user defined by `bbdd.systemUser` (typically `postgres`).
+
+Choose the connection command that matches how your PostgreSQL instance is configured:
+
+- If PostgreSQL requires a password, run:
+    ```bash title="Terminal"
+    psql -U postgres etendo
+    ```
+- If you are on Linux and PostgreSQL uses peer (OS-level) authentication, run:
+    ```bash title="Terminal"
+    sudo -u postgres psql -d etendo
+    ```
+
+Once connected, run the following SQL commands:
+
+!!! warning "PostgreSQL service must be restarted after applying this change"
 
 ```sql title="PostgreSQL"
 ALTER SYSTEM SET wal_level = logical;
 ALTER TABLE etask_task REPLICA IDENTITY FULL;
 ```
 
-These commands prepare the PostgreSQL database to work with **Debezium**, a tool for capturing changes in tables.
-
-!!! warning "**PostgreSQL service must be restarted** after applying this change" 
+These commands prepare the PostgreSQL database to work with **Debezium**, a tool for capturing changes in tables. 
 
 | Command                 | Description                                                                                                                                      |
 |-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -39,8 +56,14 @@ These commands prepare the PostgreSQL database to work with **Debezium**, a tool
 
 These commands are **mandatory prerequisites** for Debezium to detect and propagate events to Kafka, which in turn triggers task processing in Etendo.
 
+!!! info
+    If you skip this manual configuration, the `./gradlew kafkaConnectSetup --info` task can detect missing settings and apply them automatically. However, doing so forces a PostgreSQL restart during the setup run. Apply the SQL commands manually first if a mid-setup database restart is not acceptable in your environment.
+
 ### Start RX Services
 
+!!! warning
+    Add these variables only after you have completed the base Etendo installation (the initial `./gradlew install` and first Tomcat startup). Do not include them during that initial install. Adding them before the base installation is complete will cause the base install itself to fail.
+
 1. Configure the following variables in `Gradle.properties` to enable and start the required services:
 
     ```groovy title="Gradle.properties"
@@ -77,12 +100,22 @@ These commands are **mandatory prerequisites** for Debezium to detect and propag
 
 4. Create the connection between Connect and Kafka by running:
 
+    !!! info
+        This command calls the Kafka Connect REST API, which runs on port 8083 inside the Docker network by default. If Kafka Connect has not fully started after `resources.up`, the command will fail. Wait until all Docker services are healthy before running it (you can check with `docker ps` or your Docker dashboard).
+
+        Only Kafka Connect needs to be healthy for this step. The other dockerized RX services (config, auth, DAS, edge) start automatically and do not require any manual ERP configuration at this point — you will configure them in the **Initialize RX Services** section below.
+
     ```bash title="Terminal"
     ./gradlew kafkaConnectSetup --info
     ```
 
 ### Compile the Environment and Start Tomcat
 
+!!! warning
+    **Tomcat must not be running** when this command executes, because `update.database` modifies the database schema and will fail or produce inconsistent data if Tomcat is active.
+
+    - **Docker-managed Tomcat** (`docker_com.etendoerp.tomcat=true` in `gradle.properties`): Stop the Tomcat container before running the command (e.g., `docker stop etendo-tomcat-1`). `smartbuild` will restart Tomcat automatically when the build completes.
+    - **Locally installed Tomcat** (Tomcat started manually on your machine, not through Docker): Stop the Tomcat process before running the command, then start it again manually once the build completes.
 
 ```bash title="Terminal"
 ./gradlew update.database compile.complete smartbuild --info
@@ -91,6 +124,9 @@ These commands are **mandatory prerequisites** for Debezium to detect and propag
 ### Initialize RX Services
 :material-menu: `Application` > `Etendo RX` > `RX Config`
 
+!!! warning
+    This step is mandatory. Without it, the Task module cannot function. The **Initialize RX Services** process populates the default configuration variables — including service endpoints and parameters — that the RX services need to communicate with Etendo Classic. Skipping this step causes task processing to fail silently — no error is shown and no tasks are created or processed.
+
 Once the environment is compiled and Tomcat is running, as `System Administrator` role, navigate to **RX Config** window, run the **Initialize RX Services** process from the toolbar. This step registers the access data required for the interaction between Etendo RX services. For more details, see [Etendo RX Configurations](../../../etendo-rx/getting-started.md#etendo-rx-configurations).
 
 ![](../../../../assets/developer-guide/etendo-rx/getting-started/initialize-rx-service.png)
@@ -122,7 +158,7 @@ A developer, with the `System Administrator` role, must define the task types, s
 In this tab you specify the observed table and the event (insert or update) that will trigger the creation of the task.
 In addition, optional filters (JEXL) associated to the table fields or even advanced filters defined as actions can be defined. 
 
-!!!warning
+!!! warning
     In case multiple tables or filters are defined, it must be ensured that they are mutually exclusive because more than one task could be created per event occurred.
 
 **Fields to note:**
@@ -153,7 +189,7 @@ This tab defines asynchronous jobs that are automatically executed when the task
 
 - **Module**: The module where this component will be exported.
 - **Line No.**: It determines the queuing order, although as they are asynchronous processes they can be executed in parallel.
-- **Job**: Reference to the job to be executed (should be set up as asynchronous), for more information visit [Async Jobs]() documentation.
+- **Job**: Reference to the job to be executed (should be set up as asynchronous), for more information visit [How to Create Jobs and Actions](../../how-to-guides/how-to-create-jobs-and-actions.md) documentation.
 - **Active**: Checkbox to enable or disable this event.
 
 ### Task No. Sequence Configuration
@@ -245,6 +281,7 @@ Now we will go through the settings:
 !!! info
     In the [Task - User Guide](../../../../user-guide/etendo-classic/optional-features/bundles/platform-extensions/task.md) section you can see how tasks are automatically created, assigned users and how to change their status from the window with the same name.
 
+
 ---
 This work is licensed under :material-creative-commons: :fontawesome-brands-creative-commons-by: :fontawesome-brands-creative-commons-sa: [ CC BY-SA 2.5 ES](https://creativecommons.org/licenses/by-sa/2.5/es/){target="_blank"} by [Futit Services S.L.](https://etendo.software){target="_blank"}.
 

docs/es/developer-guide/etendo-classic/bundles/platform/task.md

@@ -21,7 +21,26 @@ El sistema procesa los mantenimientos en respuesta a eventos que ocurren dentro
 
 ## Configuración inicial
 
-### Configuración de PostgreSQL para el uso de Connect (Debezium)
+### Configuración de PostgreSQL para la captura de cambios con Debezium
+
+Debezium es una herramienta de captura de datos de cambios (change-data-capture) que monitoriza la base de datos en busca de cambios a nivel de fila y los reenvía a Kafka. Los dos comandos SQL que se muestran a continuación habilitan dicha monitorización en la base de datos de Etendo.
+
+El nombre de la base de datos es el valor de `bbdd.sid` en `gradle.properties` (normalmente `etendo`), y la conexión debe realizarse con el usuario del sistema PostgreSQL definido por `bbdd.systemUser` (normalmente `postgres`).
+
+Elija el comando de conexión que corresponda a la configuración de su instancia de PostgreSQL:
+
+- Si PostgreSQL requiere contraseña, ejecute:
+    ```bash title="Terminal"
+    psql -U postgres etendo
+    ```
+- Si está en Linux y PostgreSQL utiliza autenticación peer (a nivel de sistema operativo), ejecute:
+    ```bash title="Terminal"
+    sudo -u postgres psql -d etendo
+    ```
+
+Una vez conectado, ejecute los siguientes comandos SQL:
+
+!!! warning "El servicio de PostgreSQL debe reiniciarse después de aplicar este cambio"
 
 ```sql title="PostgreSQL"
 ALTER SYSTEM SET wal_level = logical;
@@ -30,17 +49,21 @@ ALTER TABLE etask_task REPLICA IDENTITY FULL;
 
 Estos comandos preparan la base de datos PostgreSQL para trabajar con **Debezium**, una herramienta para capturar cambios en tablas.
 
-!!! warning "**El servicio de PostgreSQL debe reiniciarse** después de aplicar este cambio" 
-
 | Comando                 | Descripción                                                                                                                                      |
 |-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
 | `wal_level = logical`   | Establece el nivel de Write-Ahead Logging (WAL) en `logical`. Esto es necesario para que Debezium transmita cambios lógicos desde la base de datos. |
 | `REPLICA IDENTITY FULL` | Habilita la identidad de réplica completa en la tabla `etask_task`, permitiendo que Debezium acceda a los valores anteriores de las filas cuando se producen operaciones `UPDATE`. |
 
 Estos comandos son **requisitos previos obligatorios** para que Debezium detecte y propague eventos a Kafka, que a su vez desencadena el procesamiento de mantenimientos en Etendo.
 
+!!! info
+    Si omite esta configuración manual, la tarea `./gradlew kafkaConnectSetup --info` puede detectar los ajustes faltantes y aplicarlos automáticamente. Sin embargo, hacerlo obliga a reiniciar PostgreSQL durante la ejecución del proceso de configuración. Aplique los comandos SQL manualmente si un reinicio de la base de datos a mitad de la configuración no es aceptable en su entorno.
+
 ### Iniciar servicios RX
 
+!!! warning
+    Agregue estas variables únicamente después de haber completado la instalación base de Etendo (el `./gradlew install` inicial y el primer arranque de Tomcat). No las incluya durante esa instalación inicial. Agregarlas antes de que la instalación base esté completa provocará que la propia instalación base falle.
+
 1. Configure las siguientes variables en `Gradle.properties` para habilitar e iniciar los servicios requeridos:
 
     ```groovy title="Gradle.properties"
@@ -77,12 +100,22 @@ Estos comandos son **requisitos previos obligatorios** para que Debezium detecte
 
 4. Cree la conexión entre Connect y Kafka ejecutando:
 
+    !!! info
+        Este comando llama a la REST API de Kafka Connect, que se ejecuta en el puerto 8083 dentro de la red Docker de forma predeterminada. Si Kafka Connect no ha terminado de iniciarse tras `resources.up`, el comando fallará. Espere hasta que todos los servicios Docker estén en estado healthy antes de ejecutarlo (puede verificarlo con `docker ps` o desde su panel de Docker).
+
+        Solo es necesario que Kafka Connect esté en estado healthy para este paso. Los demás servicios RX dockerizados (config, auth, DAS, edge) se inician automáticamente y no requieren ninguna configuración manual en el ERP en este momento — los configurará en la sección **Inicializar servicios RX** que se describe a continuación.
+
     ```bash title="Terminal"
     ./gradlew kafkaConnectSetup --info
     ```
 
 ### Compilar el entorno e iniciar Tomcat
 
+!!! warning
+    **Tomcat no debe estar en ejecución** cuando se ejecute este comando, ya que `update.database` modifica el esquema de la base de datos y fallará o producirá datos inconsistentes si Tomcat está activo.
+
+    - **Tomcat gestionado por Docker** (`docker_com.etendoerp.tomcat=true` en `gradle.properties`): Detenga el contenedor de Tomcat antes de ejecutar el comando (p. ej., `docker stop etendo-tomcat-1`). `smartbuild` reiniciará Tomcat automáticamente cuando finalice la compilación.
+    - **Tomcat instalado localmente** (Tomcat iniciado manualmente en su máquina, no a través de Docker): Detenga el proceso de Tomcat antes de ejecutar el comando y, una vez finalizada la compilación, inícielo de nuevo manualmente.
 
 ```bash title="Terminal"
 ./gradlew update.database compile.complete smartbuild --info
@@ -91,6 +124,9 @@ Estos comandos son **requisitos previos obligatorios** para que Debezium detecte
 ### Inicializar servicios RX
 :material-menu: `Aplicación` > `Etendo RX` > `RX Config`
 
+!!! warning
+    Este paso es obligatorio. Sin él, el módulo de mantenimiento no puede funcionar. El proceso **Inicializar servicios RX** rellena las variables de configuración predeterminadas — incluyendo los puntos de conexión de los servicios y parámetros — que los servicios RX necesitan para comunicarse con Etendo Classic. Omitir este paso provoca que el procesamiento de mantenimientos falle silenciosamente — no se muestra ningún error y no se crea ni procesa ningún mantenimiento.
+
 Una vez que el entorno esté compilado y Tomcat esté en ejecución, con el rol `System Administrator`, navegar a la ventana **RX Config** y ejecutar el proceso **Initialize RX Services** desde la barra de herramientas. Este paso registra los datos de acceso necesarios para la interacción entre los servicios de Etendo RX. Para más detalles, consultar [Configuraciones de Etendo RX](../../../etendo-rx/getting-started.md#etendo-rx-configurations).
 
 ![](../../../../assets/developer-guide/etendo-rx/getting-started/initialize-rx-service.png)
@@ -122,7 +158,7 @@ Un desarrollador, con el rol `System Administrator`, debe definir los tipos de m
 En esta solapa se especifica la tabla observada y el evento (insert o update) que activará la creación del mantenimiento.
 Además, se pueden definir filtros opcionales (JEXL) asociados a los campos de la tabla o incluso filtros avanzados definidos como acciones. 
 
-!!!warning
+!!! warning
     En caso de que se definan múltiples tablas o filtros, debe asegurarse que sean mutuamente excluyentes, ya que podría crearse más de un mantenimiento por evento ocurrido.
 
 **Campos a tener en cuenta:**
@@ -153,7 +189,7 @@ Esta solapa define jobs asíncronos que se ejecutan automáticamente cuando el m
 
 - **Módulo**: El módulo donde se exportará este componente.
 - **Nivel**: Determina el orden de encolado, aunque al ser procesos asíncronos pueden ejecutarse en paralelo.
-- **Job**: Referencia al job que se ejecutará (debería configurarse como asíncrono); para más información, consulte la documentación de [Jobs asíncronos]().
+- **Job**: Referencia al job que se ejecutará (debería configurarse como asíncrono); para más información, consulte la documentación de [Cómo crear Jobs y Acciones](../../how-to-guides/how-to-create-jobs-and-actions.md).
 - **Activo**: Casilla para habilitar o deshabilitar este evento.
 
 ### Configuración de la secuencia del Nº de mantenimiento

mkdocs.yml

@@ -968,17 +968,13 @@ plugins:
             ✨Getting Started: ✨Primeros Pasos
 
   - search:
-      indexing: full
-      prebuild_index: true
       separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
       lang:
         - en
-      exact_phrase: true
-      index_all_content: true  
       pipeline:
         - stemmer
         - stopWordFilter
-        - trimmer    
+        - trimmer
 
   - tags
   - glightbox