Desktop Activities

Versión: 1.0.0  ·  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.

¿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.

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, el selector debe incluir el nodo de la ventana (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.

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 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.

Lee esto primero

Los selectores de escritorio funcionan igual que los de web. Dos páginas dedicadas los explican a fondo:

• Selectores — atributos UIA, comodines, expresiones y anclas 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.

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 — activa el control por su patrón UIA. Fiable, no necesita que la ventana esté visible.	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 — 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).

Actividades

Lanzar y conectar

Actividad	Tipo	Salida	Qué hace
Open App	open-app	number	Lanza una aplicación y devuelve su PID
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 o radio
Win Select	win-select	—	Selecciona un ítem de un combo/lista
Win Key Press	win-key-press	—	Envía una tecla o combinación
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 y es visible el elemento?
Win Extract Table	win-extract-table	DataTable	Extrae una tabla/grid 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

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 Wait For   selector = (ventana "ERP — Inicio")   state = visible
      Win Get Text   selector = (etiqueta "Saldo")   → output: saldo

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.