Desktop Activities

Versión: 1.0.9  ·  ID: zoan-packages-desktop  ·  Autor: Zoan Software

El paquete Desktop automatiza aplicaciones de escritorio de Windows: programas instalados como un ERP, un sistema contable, una aplicación bancaria de escritorio o cualquier app de Windows. El bot interactúa con sus ventanas y controles —botones, campos, listas, tablas— igual que una persona con el teclado y el mouse.

Por debajo usa UI Automation (UIA3), la tecnología de accesibilidad de Windows, que le permite “ver” los controles de una aplicación de forma fiable (no por coordenadas de pantalla, sino por el elemento real). También soporta aplicaciones Java de escritorio (Swing).

¿Escritorio o navegador?

• Para sistemas que se usan en el navegador (páginas web, portales), usa el paquete Browser.
• Para programas instalados en Windows (ventanas de escritorio), usa este paquete.

Muchos conceptos son paralelos a Browser: hay una sesión, selectores y actividades de clic, escribir, leer y esperar.

Necesita un escritorio de Windows

Todas las actividades de este paquete trabajan sobre un escritorio interactivo: en ejecuciones desatendidas, el robot lo obtiene con una sesión de robot. Los robots sin pantalla (headless) de Zoan Cloud no tienen escritorio, y el Designer oculta estas actividades en los proyectos de esa plataforma.

Concepto 1: la ventana y la sesión

Para automatizar una app primero hay que conectarse a su ventana. Tienes dos piezas:

• Open App: lanza la aplicación (si no está abierta) y devuelve su identificador de proceso (PID).
• Win Attach: se conecta a una ventana y devuelve una sesión (ZoanDesktopSession).

Como en Browser, hay dos formas de trabajar con la sesión:

Opción A — Win Attach con body

Las actividades dentro del body heredan la sesión automáticamente; no configuras session en ninguna.

Win Attach   selector = (ventana "Calculadora")
 └─ body:
      Win Click   selector = (botón "5")
      Win Click   selector = (botón "+")
      Win Get Text   selector = (display)   → output: resultado

Opción B — Sesión en una variable

Win Attach guarda la sesión en una variable; cada actividad la recibe en session, y al final cierras con Win Close.

Win Attach   selector = (ventana "ERP")   → output: app
Win Type   session = app   selector = (campo "Usuario")   text = "admin"
Win Close  session = app

El session es opcional

A diferencia de Browser, en Desktop el parámetro session es opcional en las actividades de elemento. Si lo omites (y no estás dentro del body de un Win Attach), el selector debe incluir el nodo de la ventana (wnd, lo captura el selector visual). Con una sesión, los selectores son más cortos porque la ventana ya está fijada. Para flujos de varias acciones sobre la misma ventana, usar una sesión es más cómodo y robusto.

Con sesión, la búsqueda ocurre dentro de su ventana

Cuando hay sesión (la de session o la heredada del body), el nodo wnd del selector se ignora y el control se busca dentro de la ventana de la sesión. Para actuar sobre otra ventana de nivel superior (por ejemplo, la ventana principal que aparece tras un inicio de sesión), cierra el body y conéctate a ella con otro Win Attach.

Concepto 2: los selectores de escritorio

Como en el navegador, un selector identifica el control con el que actuar (este botón, aquel campo). Lo capturas con UI Discover, señalando el elemento con el mouse; Zoan Automation guarda una referencia robusta basada en las propiedades UIA del control (su controlType, name, automationId…), que sobrevive a cambios de posición o tamaño de la ventana.

Un selector de escritorio es una lista de nodos de la ventana al control:

Nodo	Qué representa	Atributos que se usan al buscar
wnd	La ventana de nivel superior de la aplicación	process (nombre del proceso, con o sin .exe), title (título de la ventana), cls (clase de ventana)
ctrl	Cada control desde la ventana hasta el objetivo	controlType, automationId, name, cls, idx (posición entre hermanos, desde 1)

Cómo se resuelve:

• Ventanas: solo se consideran ventanas visibles; gana la primera que cumpla todos los atributos del nodo wnd.
• Coincidencia de valores: sin distinguir mayúsculas; admite comodines * y ? (Factura *) y expresiones regulares entre barras (/^Pedido-\d+$/).
• Valores dinámicos: escribe {{ expresión }} dentro de un valor (por ejemplo Fila {{ indice }}) y se resuelve al ejecutar.
• Sin adivinar: si varios controles coinciden y nada los distingue, o ninguno cumple las anclas, la actividad no elige uno al azar: falla y el diagnóstico dice por qué (agrega un ancla o un idx).
• Reintentos: la búsqueda se repite cada 250 ms hasta agotar el timeout, también ante errores momentáneos de UI Automation (una app ocupada abriendo un diálogo).

Lee esto primero

Dos páginas dedicadas explican los selectores a fondo:

• Selectores — atributos, comodines, anclas y buenas prácticas para localizar controles sin nombre propio.
• UI Discover › Modo escritorio — cómo capturar controles (incluido el soporte para apps Java), pausar para navegar la app y validar.

En esta documentación, cuando escribimos selector = (botón "Guardar") nos referimos a “el botón Guardar”, que tú habrás capturado con UI Discover.

Aplicaciones Java

Cuando Win Attach se conecta a una aplicación Java, conecta además un puente propio con Swing (espera hasta 30 s a que esté listo) para ver sus controles aunque Windows no los exponga. Necesita en la máquina un Java con el módulo jdk.attach; si no se puede conectar, el registro lo avisa y se intenta con Java Access Bridge.

Concepto 3: métodos de interacción (UIA vs físico)

Varias actividades ofrecen dos formas de actuar sobre un control, y conviene entender la diferencia:

Acción	Método “UIA” (por defecto)	Método “físico”
Win Click	invoke — en botones, los activa sin mover el mouse (un botón que abre un diálogo no bloquea el flujo). En otros controles hace un clic real.	mouse — mueve el mouse y hace clic real.
Win Type	value — asigna el texto por el patrón Value de UIA. Rápido y seguro.	simulate — enfoca el campo y simula pulsaciones de teclado.

Empieza con el método por defecto (invoke/value): es más fiable. Cambia al físico (mouse/simulate) solo si un control “rebelde” no responde al UIA (algunos controles personalizados o que validan cada tecla).

Antes de actuar, las actividades de interacción (clic, escribir, marcar, seleccionar, desplazar) traen la ventana al frente y, si el control quedó fuera del área visible, intentan desplazarlo a la vista; si no lo logran, fallan en vez de actuar sobre otra cosa. En aplicaciones Java el clic, la escritura y la selección siempre son físicos.

Concepto 4: esperas y tiempos de espera

• Buscar el elemento: cada actividad espera hasta timeout ms a que su elemento exista. Si la dejas vacía, usa el tiempo de espera de interfaz de la configuración del proyecto o, si el proyecto no lo define, 30000 ms.
• Comprobaciones instantáneas: Win Element Exists no espera por defecto (0); dale un timeout si quieres que espere.
• Traer la ventana al frente: Win Focus espera hasta 15000 ms (o el tiempo del proyecto); Win Key Press con selector, hasta 3 s.
• Abrir una aplicación: Open App da a Windows 30000 ms (o el tiempo del proyecto, si es mayor).
• Retardos: los retardos antes y después de cada acción del proyecto se aplican a todas las actividades de elemento.

Para esperar a que algo aparezca o desaparezca, usa Win Wait For en vez de un Delay fijo.

Errores comunes de las actividades de elemento

Estos mensajes los comparten todas las actividades que buscan un control. Los de cada actividad están en su página.

Mensaje	Causa y solución
No se encontró el elemento con el selector {…}. seguido de Diagnóstico: …	El elemento no apareció dentro de timeout. El diagnóstico dice en qué nodo se perdió. Comprueba que la ventana esté abierta, valida el selector en UI Discover o espera antes con Win Wait For.
… elementos coinciden con el selector y nada los distingue, así que no se eligió ninguno (no se adivina). Agrega un ancla o un índice en el selector. (en el diagnóstico)	El selector es ambiguo. Agrega un automationId, un idx o un ancla.
'selector' es obligatorio y debe ser un selector de escritorio válido.	Falta el selector o no es de escritorio (por ejemplo, uno de navegador). Captúralo de nuevo con UI Discover.
El selector debe contener un nodo 'wnd' cuando no hay sesión.	Sin sesión, el selector necesita la ventana. Usa la actividad dentro de un Win Attach o pásale session.
El elemento está fuera del área visible y no se pudo desplazar hasta él, …	El control está oculto por el desplazamiento de su contenedor. Agrega un Win Scroll antes.
No se pudo localizar el control Java sin ambigüedad, así que no se hizo nada. …	En una app Java, el puente no distinguió el control. Recaptura el selector o agrega un ancla.

Para reintentar ante fallos momentáneos, envuelve los pasos en un Retry o un Try / Catch.

Actividades

Lanzar, conectar y recuperar

Actividad	Tipo	Salida	Qué hace
Open App	open-app	int	Lanza una aplicación y devuelve su PID
Kill Process	kill-process	int	Termina procesos por nombre o PID (una app colgada)
Win Attach	win-attach	ZoanDesktopSession	Se conecta a una ventana
Win Focus	win-focus	—	Trae una ventana al frente
Win Close	win-close	—	Cierra la ventana y libera la sesión

Interactuar

Actividad	Tipo	Salida	Qué hace
Win Click	win-click	—	Hace clic en un elemento
Win Type	win-type	—	Escribe texto en un campo
Win Set Value	win-set-value	—	Asigna el valor de un campo (patrón Value)
Win Check	win-check	—	Marca/desmarca un checkbox
Win Select	win-select	—	Selecciona un ítem de un combo/lista
Win Key Press	win-key-press	—	Envía una tecla, una combinación o una secuencia de teclas
Win Scroll	win-scroll	—	Desplaza un elemento con scroll

Leer datos

Actividad	Tipo	Salida	Qué hace
Win Get Text	win-get-text	string	Texto o valor de un elemento
Win Get Attribute	win-get-attribute	object	Una propiedad del elemento (enabled, value…)
Win List Items	win-list-items	string[]	Ítems disponibles de un combo/lista
Win Element Exists	win-element-exists	boolean	¿Existe el elemento?
Win Extract Table	win-extract-table	DataTable	Extrae una tabla de una ventana a una DataTable

Esperar y capturar

Actividad	Tipo	Salida	Qué hace
Win Wait For	win-wait-for	boolean	Espera a que un elemento aparezca o desaparezca
Win Screenshot	win-screenshot	—	Captura la ventana o un elemento a un archivo
Take Screenshot	take-screenshot	string	Captura todo el escritorio a un archivo y devuelve su ruta

Un flujo típico

Abrir un sistema, iniciar sesión y leer un dato:

Open App   path = "C:/ERP/erp.exe"   → output: pid
Win Attach   selector = (ventana "ERP — Login")
 └─ body:
      Win Type   selector = (campo "Usuario")   text = credential("erp")["user"]
      Win Type   selector = (campo "Clave")     text = credential("erp")["password"]
      Win Click  selector = (botón "Ingresar")
Win Attach   selector = (ventana "ERP — Inicio")      // espera hasta timeout a que aparezca
 └─ body:
      Win Get Text   selector = (etiqueta "Saldo")   → output: saldo

Y si la aplicación se cuelga, la recuperación habitual es dejar evidencia con Take Screenshot, terminarla con Kill Process y volver a abrirla. Las plantillas incluidas ya traen ese patrón en su playbook Recuperar.

Siguientes pasos

• Open App y Win Attach — el punto de partida.
• Browser — el paquete equivalente para web (conceptos paralelos).
• Win Wait For — clave para automatizaciones de escritorio fiables.