Desktop Activities

Version: 1.0.0  ·  ID: zoan-packages-desktop  ·  Author: Zoan Software

The Desktop package automates Windows desktop applications: installed programs such as an ERP, an accounting system, a desktop banking application or any Windows app. The bot interacts with its windows and controls—buttons, fields, lists, tables—just like a person with a keyboard and mouse.

Underneath it uses UI Automation (UIA3), Windows’ accessibility technology, which allows you to reliably “see” an app’s controls (not by screen coordinates, but by the actual element). It also supports Java desktop applications.

Desktop or browser?

• For systems used in the browser (web pages, portals), use the Browser package.
• For programs installed on Windows (desktop windows), use this package.

Many concepts parallel Browser: there is a session, selectors, and click, write, read, and wait activities.

Concept 1: the window and the session

To automate an app you must first connect to its window. You have two pieces:

• Open App: launches the application (if it is not open) and returns its process identifier (PID).
• Win Attach: attaches to a window and returns a session (ZoanDesktopSession).

As in Browser, there are two ways to work with the session:

Option A — Win Attach with body

Activities within body inherit the session automatically; you don’t set session to any.

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

Option B — Session in a variable

Win Attach saves the session to a variable; each activity receives it in session, and at the end you close with Win Close.

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

session is optional

Unlike Browser, in Desktop the session parameter is optional in item activities. If you omit it, the selector must include the window node (it is captured by the visual selector). With a session, the selectors are shorter because the window is already pinned. For flows of several actions on the same window, using a session is more convenient and robust.

Concept 2: Desktop Selectors

As in the browser, a selector identifies the control to act with (this button, that field). You capture it with UI Discover, pointing at the element with the mouse; Zoan Automation saves a robust reference based on the UIA properties of the control (its controlType, name, automationId…), which survives changes in position or window size.

read this first

Desktop selectors work the same as web selectors. Two dedicated pages explain them in depth:

• Selectors — UIA attributes, wildcards, expressions and anchors to locate controls without their own name.
• UI Discover › Desktop Mode — how to capture controls (including support for Java apps), pause to navigate the app, and validate.

In this documentation, when we write selector = (botón "Guardar") we refer to “the Save button”, which you will have captured with UI Discover.

Concept 3: interaction methods (UIA vs physical)

Several activities offer two ways to act on a control, and it is important to understand the difference:

Action	”UIA” method (default)	“Physical” method
Win Click	invoke — activates control by its UIA pattern. Reliable, does not need the window to be visible.	mouse — moves the mouse and clicks real.
Win Type	value — maps the text by the UIA Value pattern. Fast and safe.	simulate — simula pulsaciones de teclado.

Start with the default method (invoke/value): it is more reliable. Switch to physical (mouse/simulate) only if a “rogue” control does not respond to the UIA (some custom or key-validating controls).

Activities

Lanzar y conectar

Activity	Type	Output	What it does
Open App	open-app	number	Launch an application and return its PID
Win Attach	win-attach	ZoanDesktopSession	Connects to a window
Win Focus	win-focus	—	Bring a window to the front
Win Close	win-close	—	Close the window and release the session

Interactuar

Activity	Type	Output	What it does
Win Click	win-click	—	Clicks on an item
Win Type	win-type	—	Write text in a field
Win Set Value	win-set-value	—	Assigns the value of a field (Value pattern)
Win Check	win-check	—	Check/uncheck a checkbox or radio
Win Select	win-select	—	Select an item from a combo/list
Win Key Press	win-key-press	—	Send a key or combination
Win Scroll	win-scroll	—	Move an element with scroll

Read data

Activity	Type	Output	What it does
Win Get Text	win-get-text	string	Text or value of an element
Win Get Attribute	win-get-attribute	object	A property of the element (enabled, value…)
Win List Items	win-list-items	string[]	Items available from a combo/list
Win Element Exists	win-element-exists	boolean	Does the element exist and is visible?
Win Extract Table	win-extract-table	DataTable	Extract a table/grid to a DataTable

Esperar y capturar

Activity	Type	Output	What it does
Win Wait For	win-wait-for	boolean	Wait for an element to appear or disappear
Win Screenshot	win-screenshot	—	Capture the window or an element to a file

A typical flow

Open a system, log in and read data:

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

Next steps

• Open App and Win Attach — the starting point.
• Browser — the equivalent package for web (parallel concepts).
• Win Wait For — key to reliable desktop automations.