First steps

This guide takes you from zero knowledge to having your first automation up and running. It’s intended for someone who has never used Zoan Automation — and almost no one has touched RPA before. Each step explains what you will see, what you have to do, and what common errors may appear.

Al terminar vas a tener:

• A Zoan Automation account on your own subdomain.
• The Agent installed and connected on your Windows machine.
• Your first playbook designed, published and successfully executed.
• Execution logs visible in the portal.

Estimated time: 30 to 45 minutes the first time. Then, creating a new automation takes minutes.

What do you need?

• A machine with Windows 10 or 11 (or Windows Server 2016+) where you want your bots to run.
• administrator permissions on that machine (to install the Agent and register it as a service).
• A stable internet connection.
• 15 minutes of patience with the installation wizard.

Flow Overview

Before putting your hands in, this is what the complete path looks like:

1. You request your Zoan Cloud account — we receive your email and activate your tenant (a subdomain for your organization).
2. You activate your account — from the invitation you get by email you set your password and sign in to https://your-company.cloud.zoansoftware.com.
3. You create an environment (“Production” or “Tests”) and inside you create an agent, which generates a Machine Key.
4. You download the Zoan Platform Setup and install it with the wizard — it includes Designer and Agent in a single package.
5. Open Zoan Agent, paste the URL and Machine Key, and connect.
6. You open Zoan Designer, create a project, drag activities to the canvas and configure parameters.
7. You publish the playbook to the portal, associate it with a process in the environment, and run it.
8. You see the logs in real time from the portal.

From here we take you step by step.

---

1. Get your Zoan Cloud account

For now, Zoan Automation is delivered with accompaniment: there is no automatic registration from the web. This allows us to ensure that you receive the tenant configured correctly, with your assigned plan and an open support channel from day one.

1. Solicita tu cuenta

   Write to contacto@zoansoftware.com or fill out the form at zoansoftware.com/contacto. Indicates:

   • Name of your organization.
   • Subdomain you want to use (e.g. acme → acme.cloud.zoansoftware.com).
   • Interest plan (Free, Starter, Pro).
   • Name and email of the first administrator user.

2. Wait for activation

   In less than one business day, the first administrator receives an invitation to your organization with the Activar cuenta (Activate account) button. The link is valid for 72 hours: opening it lets you set your password and sign in to your portal (https://your-company.cloud.zoansoftware.com). The installer is downloaded from the portal, with Descargar aplicaciones (Download apps).

   

---

2. First sign-in to the portal

1. Click “Activar cuenta” (Activate account) in the invitation email. Your portal’s activation page opens.

2. Complete your profile and set your password. Use a strong password: the portal stores sensitive credentials of your systems.

3. Sign in to https://your-company.cloud.zoansoftware.com with your email and the password you set.

   

4. You land on Inicio (Home). You’ll see an empty summary — there are no environments or runs yet.

   

---

3. Create your first environment

An environment is an isolated space where resources live: agents, processes, credentials, executions. The typical thing is to have Producción, Pruebas and Desarrollo separate, but to start with one is enough.

1. Open Administración › Ambientes (Administration › Environments), at the bottom of the menu rail; see The Zoan Cloud menu.

2. Click on “New environment” (button at the top right).

   

3. Fill out the form:

   • Name: Pruebas (changeable later).
   • Description: optional.

   

4. Keep. The environment is created and you go directly into its detail.

---

4. Create a machine within the environment

The agent represents the physical or virtual machine where the bots will run. When you create it in the portal, it returns a Machine Key — a key that the Agent (the desktop app) uses to identify itself against Zoan Cloud.

1. With the environment picked at the top right, open Centro › Máquinas (Center › Machines).

2. Click “Nueva máquina” (New machine).

   

3. Enter a name for the agent and keep the platform on Windows. Convention: identifiable name of the machine (e.g. WIN-CONTABILIDAD-01, VM-AUTOMATION-EU-01).

   

4. Click “Crear máquina” (Create machine). The Credenciales del agente (Agent credentials) modal appears with the URL, the Agent ID and the Machine Key:

   

   Important!

   The Machine Key is only displayed once. Copy it using the button to the right of each field and paste it in a temporary safe place (notepad, password manager) — you need it in the next step. If you lose it, you have to regenerate it and reconfigure the Agent.

5. Copy the Machine Key with the copy button. Also write down the agentId (it is used to reference the agent from the API).

6. Click “Entendido” (Got it). The agent is listed with status offline — nothing is connected yet on the machine side.

---

5. Download and install Zoan Platform

Zoan Platform is a single installer that includes the Designer + the Agent. There are no separate installers.

1. Download the installer

   Hay dos formas:

   • From the portal: There is a download link in the tenant header or on each agent page.
   • From the activation email: includes the direct link.

   The file is ZoanPlatformSetup.exe, approximately 80–120 MB.

   

2. Run as administrator

   Double click on ZoanPlatformSetup.exe. Windows asks if you want to allow changes — click Yes.

   Tip

   If the machine is shared and you want the Agent to run as a service (so it automatically boots with Windows), you need to run it as administrator. If only you are going to use it in your session, you can choose “Current user only” in the wizard and you do not need admin.

3. Automatic dependency checking

   Before showing the wizard, the installer checks two things:

   • .NET 8 Desktop Runtime (required for Windows apps to work).
   • Microsoft Edge WebView2 Runtime (embedded browser engine that uses the UI).

   If something is missing, the installer asks you if you want to download it. Accept — the installation is transparent.

4. Installation wizard (5 steps)

   Step 1: Welcome

   Welcome screen with a link to the Terms of Service and the Privacy Policy. Click Get started.

   

   Step 2: Install location
   • All users: for every Windows user, requires admin and allows the Windows service for unattended runs. Folder: C:\Program Files\Zoan.
   • Current user only: only your account, no admin; the Agent starts in the tray when you sign in. Folder: %LOCALAPPDATA%\Zoan.

   

   Click Next.

   Step 3: Components
   • Zoan Designer — visual playbook editor (checked).
   • Zoan Agent — connects the machine to Zoan Cloud and runs the bots (checked).
   • Zoan Agent Service — the Agent as a Windows service for unattended runs (unchecked; only with All users).
   • Zoan UI Discover — the browser extension to capture web selectors (checked).

   For this tutorial keep Designer and Agent checked.

   

   Click Install.

   Step 4: Installing

   Progress bar with the detail of what is being copied. It takes 30 to 90 seconds.

   

   Step 5: Finish

   Green check. The Zoan Designer and Zoan Agent shortcuts are in the Start menu and on the Desktop. Click Launch Designer or close the installer.

   

---

6. Connect the Agent to Zoan Cloud

Here you use the Machine Key that you copied in step 4.

1. Open Zoan Agent from the Start menu or desktop icon.

2. Linking screen

   The first time you open the Agent, you are greeted with this screen. There are two fields:

   • Zoan Cloud URL — the URL of your portal (e.g. https://acme.cloud.zoansoftware.com).
   • Machine Key — the key you copied from the portal.

   

3. Paste the values and click “Vincular este equipo” (Link this computer)

   The Agent validates the URL, contacts Zoan Cloud, registers the connection, and saves the configuration. If everything goes well, in 2-3 seconds it switches to the main screen.

   

4. Verify that it appears as online in the portal

   Return to the tenant portal and open Centro › Máquinas (Center › Machines) in the environment. The agent you created earlier should now have an online (green) status instead of offline.

   

Errores comunes

• “Could not connect”: verify that the URL is exact (with https:// and without trailing slash), that there is no firewall blocking port 443 from your machine to Zoan Cloud, and that the Machine Key is correctly copied (without spaces at the beginning or end).
• “Invalid Machine Key”: the key has already been used, was regenerated in the portal, or the agent was deleted. Return to the portal and regenerate the key.
• The Agent appears online but returns offline after a few seconds: possible corporate proxy problem. Contact support.

---

7. Design your first playbook

Now comes the fun part: putting together an automation.

For this tutorial we are going to make something simple: a playbook that opens Wikipedia, searches for “Robotic process automation” and saves the first paragraph in a variable.

1. Open Zoan Designer from the Start menu.

   

2. Create a new project

   Click on New project. The Designer asks you:

   • Nombre del proyecto: Tutorial Wikipedia
   • Location: By default it suggests Documentos\Zoan\Proyectos\ — leave it that way or change it.

   

3. Get to know the Designer interface

   When you open the project you will see 4 areas:

   • Palette (left) — all available activities, grouped by package.
   • Canvas (center) — where you drag the activities to build the flow.
   • Properties panel (right) — parameters of the selected activity.
   • Panel de variables (abajo) — variables del playbook.

   

4. Arrastra tu primera actividad

   In the palette, type browser in the search engine. The activities from the Browser package appear. Drag Open Browser to the canvas.

   

5. Configure Open Browser

   Click on the browser-open node that you just placed. The properties panel on the right opens with the parameters:

   • Browser: deja chrome.
   • URL: "https://es.wikipedia.org/wiki/Automatización_robótica_de_procesos" (in quotes: it is fixed text)
   • Headless: false (we want to see the browser for this tutorial).
   • Save result to (Output): type page — this saves the browser session to a variable called page.

   

6. Add an activity to wait for the content

   In the palette, look for page-wait-for. Drag Wait For below the Open Browser.

   Configure:

   • Page: page (references the variable you created in the previous step with an expression).
   • Selector: #mw-content-text p >> nth=0 (the article’s first paragraph: #mw-content-text p matches several and the activity needs exactly one; >> nth=0 keeps the first).
   • Timeout: 10000 (10 segundos).

   

7. Extract the text from the first paragraph

   Drag Get Text below.

   Configure:

   • Page: page
   • Selector: #mw-content-text p >> nth=0
   • Save result to (Output): firstParagraph

8. Record the result in a log

   Arrastra Log (del paquete Core).

   Configure:

   • Level: info
   • Message: "Primer párrafo: " + firstParagraph

9. Close the browser at the end

   Drag Close Browser and set session: page.

10. Your playbook should look like this

    

---

8. Run locally to validate

Before publishing the playbook to Zoan Cloud, it is a good idea to test it on your own machine. The Designer can execute against your local Agent.

1. Verify that the Agent is online (check the icon in the system tray — it should have a green circle).

2. Click on “Run” in the Designer toolbar (button with play icon).

3. Look at the logs panel (bottom). You will see messages in real time:

   [INFO] Iniciando ejecución
   [INFO] browser-open: chrome → es.wikipedia.org
   [INFO] page-wait-for: selector encontrado
   [INFO] page-get-text: 487 caracteres extraídos
   [INFO] Primer párrafo: La automatización robótica de procesos...
   [INFO] browser-close
   [OK]   Ejecución completada — 4.2s

   

4. If something fails, the log panel shows the error. The most frequent causes for this playbook would be:

   • Wikipedia changed its layout and the #mw-content-text p >> nth=0 selector no longer exists — update it.
   • You don’t have Chrome installed — install Chrome or change to edge in the Browser parameter.
   • Agent is not running — open it from the Start menu.

---

9. Publish the playbook to Zoan Cloud

Once it’s running locally, you publish it to the portal so it can run unattended.

1. In the Designer, click “Publish” in the toolbar.

2. Fill in the version information

   The Designer asks you:

   • Version (semantics): 1.0.0 for the first publication.
   • Release Notes: Optional, but useful for history.

   

3. Confirm. The Designer packages the project into a .zoan file, uploads it to the Zoan Cloud portal and associates it with your tenant.

4. In the portal, open Centro › Paquetes (Center › Packages). You will see your Tutorial Wikipedia v1.0.0 package listed.

   

---

10. Create a process and run from the portal

A process associates a package (at a specific version) with an environment. It is what the agent executes when he receives an order.

1. With the environment picked, open Centro › Robots › Procesos (Center › Robots › Processes).

2. Click on “New process”.

3. Select package and version:

   • Package: Tutorial Wikipedia
   • Version: 1.0.0
   • Process name: Tutorial Wikipedia (autocomplete, you can change it).

   

4. Guardar.

5. Open Centro › Robots › Ejecuciones (Center › Robots › Executions) and click Iniciar ejecución (Start execution).

6. Select:

   • Process: Tutorial Wikipedia
   • Agent: the one you created (Zoan Cloud selects one online automatically).

7. Confirm. The execution goes to state queued and, in seconds, to running.

8. See the logs in real time from the same screen.

   

9. When finished it remains at completed (green) or failed (red). Click on the execution to see the details: complete logs, duration, exit code.

   

---

Congratulations! 🎉

Your first bot is running in production. From here you can:

• Try other catalog activities — Excel, Outlook, OCR, databases, SFTP.
• Program the bot with a trigger to run automatically every day/week.
• Use credentials to allow your bots to access systems that require login without exposing passwords in the code.
• Learn about key concepts in more detail.

Did something go wrong?

Problema	Where to look
The installer fails	Agent Troubleshooting
Agent does not connect	Agent States
Designer does not open	Re-run the installer with the “Repair” option
The playbook fails in production	Execution logs
Otra cosa	Concepts or write to soporte@zoansoftware.com