Workflows
Overview
A workflow is an automation that starts from a trigger and carries data through a chain of steps until it produces an effect — writing rows, sending an email, calling an external system. Each step reads the data the workflow has gathered so far, does one job, and passes the result to the next step, so what one step produces the next can consume.
Workflows replace repetitive manual work and ad-hoc scripts: importing a batch of documents, reacting to a status change, syncing data with an external system, or pausing for someone to check something before it's applied.
Workflows are managed in the Automações section of design mode. The sidebar has Início (the library), Execuções, Revisões, Ligações and Modelos, each with its own address (/workflows-v2, /workflows-v2/runs, /workflows-v2/reviews, /workflows-v2/connections, /workflows-v2/templates), and below them the searchable list of automations with the Arquivadas button (/workflows-v2/archived).
Triggers
A workflow has exactly one trigger. Available triggers:
| Trigger | Fires when | Configuration |
|---|---|---|
| Manual (a pedido) | Someone fires it by hand, from one of four scopes: Genérico (no context — e.g. a dashboard button), Linha (a single record), Feature (several/all records of a feature), Vista (the rows currently visible in a view) | The scope, plus a source feature (Linha/Feature) or a view (Vista) |
| Upload de ficheiro | Documents are uploaded through the workflow's own upload dialog — one run per file | Accepted file extensions |
| Webhook | An external system sends a POST request to the workflow's own URL | The URL/token is generated for you (copy it, or regenerate to invalidate the old one), plus an optional description |
| Agendado (cron) | On a schedule, or when a row's date arrives | A simple interval (every N minutes/hours/days), a calendar schedule (daily/weekly/monthly/yearly/once, or a raw cron expression) with timezone, or the Data mode: a table, a date column, days before/after and the time |
| Registo (Mudança) | A row in a chosen feature is created, updated and/or deleted — a single trigger, with one or more change types ticked | Feature to watch, the change types (at least one) and a filter on the row's data; with "Alterado" ticked it also accepts a filter on the previous state (to model a transition, e.g. pending → paid) and a list of columns that must have changed |
When the Registo (Mudança) trigger watches deleted rows, the filter sees the values the row had before it was deleted, plus who created it and when (the "Criado por" and "Criado em" columns).
In the filter of the Registo (Mudança) trigger, the Origem (Origin) field (Utilizador, Modelo, Importação, Automação, API or Portal) limits the automation to rows that came from that origin: with Portal, it runs only for the rows that clients create from a portal.
Scheduled by date
In Data mode, the scheduled trigger runs the automation once for each row of a table whose date column reaches the day, at the chosen time, in the workspace time zone. Dias antes/depois shifts the day: -3 runs three days before the date, 2 runs two days after, 0 on the day itself. An optional filter narrows the rows. It works with date and date-time columns; a date-time counts on its day in the workspace time zone.
Each row runs once per date, even if you publish a new version of the automation that day. If the row's date changes, it runs again on the new date. The automation receives the row as with the Registo (Mudança) trigger, plus the variables event (date), rowId, dateColumn and dueOn (the day it fired).
The run happens within the hour after the set time. A row whose date becomes today after that hour does not run that day. To try it without waiting, open Testar and pick a row: the run behaves as if its date were today.
Steps
Steps are grouped into five roles. The step palette (opened from the + on the canvas) is organized the same way, and the canvas colors each step's connector by role.
Sources — bring data in
| Step | Reads |
|---|---|
| CSV — ler ficheiro | An uploaded CSV (delimiter, header row) |
| Excel — ler folha | An uploaded Excel sheet |
| JSON — ler lista | A JSON array/object from a file or a variable |
| OCR — extrair documento | Structured fields from a document (PDF/image) via AI, per a schema you define |
| HTTP fetch | An external API's JSON response, turned into records — optionally through an HTTP connection |
| Ler feature (linhas) | Existing rows from a feature (filters, sort, limit) — the base for reconciliation workflows |
Transforms — reshape the data
| Step | Does |
|---|---|
| Mapear → colunas | Maps source fields to target feature columns, plus fixed values |
| Deduplicar | Compares each record against existing rows by one or more key fields and marks it insert / update / skip |
| Conciliar (match) | Reconciles two sets of records against each other (exact/numeric/date/fuzzy rules) and scores each match — e.g. bank movements vs invoices |
| Agente (emit-only) | Sends the current data to an AI agent with a prompt and a schema; the result merges into the workflow's variables (e.g. to classify a document type). The agent only proposes — it never writes anything itself |
| Agente (Autónomo) | An AI agent investigates the data with read tools and proposes a result (text, structured data, proposed rows or a report); a later step does the writing. It reads the reference corpus attached to the step, the chosen organization sources and, with Pesquisa na web (Web search) on, the web; each search and each page read costs credits on top |
Control — decide the path
| Step | Does |
|---|---|
| Condição (if/else) | Branches on a variable, record count, or the shape of the data |
| Agente escolhe a rota | An AI agent picks exactly one of several named routes you define (at least two); each route becomes its own lane on the canvas |
| Sub-workflow | Runs another workflow as a single step. By default it fires once with the current data (fire-and-forget); it can instead spawn one child run per record and wait for all of them to finish before continuing |
Gates — pause for a person
| Step | Does |
|---|---|
| Revisão humana | Pauses the run and shows the proposed data for someone to edit, approve, or reject. Rendering adapts to the data: plain fields (default), a table when the records map to a feature, a document viewer, email fields, or a single text block — set via "Formato de revisão". An optional confidence threshold can auto-approve records above it |
| Aprovação | A simple approve/reject checkpoint with a custom title and message — no records shown |
On Revisão humana, each record gets an insert / update / skip decision plus a reject toggle; approving writes the batch and resumes the run. If every record ends up rejected, the dialog instead offers Rejeitar e repetir (start a fresh run from the same source data) or Rejeitar e retomar (end this run without writing anything). On the Reviews page the Pendentes, Minhas (those addressed to you) and Resolvidas pills split the list; you can also filter by automation and, for pending ones, by age. On a wide screen the data review opens next to the list (approvals and conversations still open in a dialog), and leaving with unsaved changes asks for confirmation. The indicators show pending, resolved and rejected reviews in the last 7 days and the average time to decision, counted from the start of the run.
Sinks — the effect
| Step | Does |
|---|---|
| Importar (upsert) | Writes the approved records into the target feature: insert new ones, update matches (by the same key as Deduplicar), or skip. Safe to resume after a pause — it won't write the same record twice |
| Enviar email | Sends an email (recipients/subject/body), optionally with the workflow's files attached — via the global mail transport or a specific SMTP connection |
| Gerar relatório | Generates the PDF of a saved report, block or HTML, for the record of the trigger row (or another one you set) and with the values you give the report's inputs; you also choose the file name and the language (Portuguese or English). The PDF is added to the workflow's files, so Enviar email can attach it with "Attach run files", and the step gives {{vars.report.fileName}} and {{vars.report.pages}} to the steps that follow. The PDF comes out A4 and in the light theme. Each table goes into the document with its 2000 newest rows, plus the record and the rows linked to it; when a table has more, the step warns in {{vars.report.warnings}} |
| Chamar tool MCP | Calls a tool on an external MCP server (e.g. an invoicing system) through an MCP connection |
Referencing data from other steps
Field values in a step's configuration can reference the data the workflow has gathered up to that point:
| Reference | Points to |
|---|---|
{{record.field}} | The current record of the working set |
{{records.2.field}} | A specific record, by index |
{{vars.name}} | A workflow variable |
{{vars.trigger.column}} | The row that fired the workflow |
{{vars.write.rowId}}, {{vars.write.record.column}} | The result of the last Escrever registo - also inserted, updated, rowIds. It is always the most recent write step: in a chain with several, use {{vars.steps.<id>.write...}} instead to point at one specific step |
{{vars.steps.<id>.<output>...}} | The output of a specific step, by its id - unambiguous when the chain has two identical steps |
{{sys.now}}, {{sys.today}} | The current date and time / today's date |
Every configuration field that accepts {{...}} has, on the field itself, a {} button that opens a searchable, grouped menu - Gatilho, Variáveis, Saídas por passo, Registos, Ficheiros, Sistema - listing each column's label (not its technical name) and its type; picking an entry inserts the token at that field's cursor position. Composite outputs, such as the record written by Escrever registo, come already expanded column by column, with the label and the type of each one: deep paths no longer have to be typed by hand.
A token that points to a value that doesn't exist at that point of the flow doesn't pass silently: Escrever registo adds a warning to the run log saying which values were missing, which column they were bound to, in how many records, and whether the column ended up empty, incomplete or with the {{...}} unresolved, for example "cliente" ← {{record.cliente}}. It is a warning, not an error: the records are still written. The warning shows on the step's own line, under its name, and not only inside the step data. A value that exists and is empty raises no warning.
If Escrever registo fails because it received no records (for example a manual trigger with the "Genérico" scope wired straight to the step), the message states the rule and the ways out: use the "Linha" scope or a record trigger, put a step that produces records before it (such as Ler registos), or, to write to the row that started the flow, use the "Atualizar o registo do gatilho" mode. The message names the mode the step ran in.
In the filters of the Ler registos step, each rule has a {{}} toggle that swaps the typed value (the same per-type editor as the filters of a table view) for a free-text field - with the same {} button - so the column can be compared against a variable instead of a fixed value.
Most steps show two panels in the configuration rail: Recebe, at the top, with what arrives from the previous step (or from the trigger); and Produz, at the bottom, with what that step adds for the steps that follow.
Connections
Ligações (Automações → Ligações) are reusable, pre-configured access to an external service, referenced by name from steps. Secrets are encrypted in the vault and can't be read back once saved, only replaced.
| Type | Stores | Used by |
|---|---|---|
| HTTP | Base URL, headers, auth, named endpoints | HTTP fetch |
| MCP | Server URL, auth (none / bearer token / custom header) | Chamar tool MCP |
| SMTP | Host, port, user, sender address, TLS | Enviar email |
| AI Provider | Provider, model, base URL (bring your own key) | OCR, agent steps |
AI steps (OCR, agent) work out of the box with the organization's configured AI settings — an AI Provider connection is only needed to use a different provider or key for a specific step.
The Ligações page shows each connection as a card, with its type, the automations that use it and its health. Base connections sit in one section and those created from templates in another; the header counts the connections and how many have an error.
| Status | Meaning |
|---|---|
| Por testar | Nobody has tested it or run with it yet |
| Ligada | The last test or run went through |
| Chave expirada | The service answered 401 or 403: renew the key |
| Com erro | Any other failure, with the message on the card |
Health updates with Testar, on the card (or Testar ligação in the edit dialog), and also when a run uses the connection in an HTTP fetch step. AI Provider connections have no status.
Nova ligação opens a picker with the type (HTTP, MCP, Email, AI): pick one and the next step asks only for that type's fields. The Email (SMTP) connection is for sending email on behalf of the organization.
Library
Início shows every automation that is not archived, grouped by the trigger's table (those without one, such as scheduled, webhook and email automations, sit under Sem tabela). Each card says what the automation does in one sentence, "Quando…, então…", and shows the trigger, the number of steps, whether it has human review, the runs of the last 7 days and the last run, with the step where it failed.
The switch on each card activates or pauses the automation; pausing asks first and the automation stays in the library as Pausada. An automation the system switched off shows Auto-desativada with the reason. An automation that is still only a draft shows Aplicar, which opens the flow where it is applied. Each card's menu has Editar, Duplicar, Renomear and Arquivar.
Inside each table, the automation that ran last comes first and those that never ran sit at the end. The Estado and Gatilho filters and the search combine; Cartões | Lista switches the cards to a list. The Execuções entry in the sidebar shows how many runs failed. The Dono and Etiqueta filters show one person's automations, those without an owner, or those with a tag. The card shows the owner, the tags and who edited last.
Creating a workflow
Nova automação (or + in the sidebar) asks for the name, the starting point, the trigger and, for record and manual triggers, the table (required for the record trigger). It also asks for the Dono (you by default) and the Etiquetas. The automation is born as a draft and only fires after you apply and activate it. The starting points:
- Começar do zero — an empty chain, built step by step.
- Importar CSV — CSV → map → dedupe → review → import.
- Importar documentos (OCR) — OCR → map → dedupe → review → import.
- Importar CSV (condicional) — the same CSV import, but review only kicks in above a record-count threshold.
- Agente revisor (confiança) — one agent drafts a reply, a second scores its confidence, and only low-confidence results go to human review before sending.
Templates that need a table (tell the team about a new client, approve invoices, classify requests with AI and others) live on the Modelos page.
Templates
Modelos (/workflows-v2/templates) is a gallery with search and two sections. Os teus modelos are the automations you or your team saved, those of the organization and those of this workspace. Modelos da casa are the ready-made ones, by family (Notificações, Documentos e OCR, Aprovações, Dados e cálculos, Integrações), with a family filter. Each card shows the trigger, the number of steps and what the template needs (an HTTP connection, a mailbox, AI credits). Importar pacote brings templates in from a file.
Ver shows the template's flow with the same cards as the editor (the trigger, the steps and the branches side by side) and what you will configure when using it. Usar asks the template's questions: the table (suggested when one has a similar name; if it lacks a column the template uses, the dialog warns you) and the values the template left open. Usar modelo creates the automation as a draft and opens it. In Usar, the cards follow your answers; a step that still has a problem is marked. On a narrow screen the flow shows as a list.
Save as a template
In the ⋯ menu of an automation, Guardar como modelo saves it for reuse. You pick the name, the family and where it is available: this workspace or the whole organization. Under Ao usar o modelo, pede-se, each configurable value has a mode:
- Obrigatório (required): whoever uses the template must fill it in.
- Com valor por omissão (with default): prefilled with today's value and can be changed.
- Fixo (fixed): stays as it is and is not asked.
The template stores the version applied at the moment you save; later changes to the automation do not alter it. An automation with no applied version yet cannot be saved as a template. On one of your own templates, ⋯ lets you edit the name and description, export the package or delete it; deleting removes it from Modelos and does not affect automations already created from it.
Create with AI
Criar com IA (in the Home bar, the Modelos bar and in Nova automação) works in two steps, in the same dialog. It is the only text entry.
- Describe. You write what you want to automate, for example «Quando uma fatura é aprovada, enviar um email ao fornecedor»; there are examples from the workspace's tables. Pré-visualizar asks the AI for an outline, built on the workspace's tables and columns. If you already typed a name in Nova automação, it carries over to the outline.
- Preview. It shows the Nome, the Tabela, the outline as the editor's cards (steps with problems are marked) and what is left to configure. The AI names the columns it uses; if you swap the table, the outline is validated again and warns about missing columns. To change the outline, type the request in Pedir uma alteração ao esboço… («instead of notifying, create a task for the owner»); each change produces a new outline and redraws the cards. Criar rascunho creates the automation and opens the editor at the first problem.
Each preview spends AI credits: the dialog shows the organization's balance before and the total spent after. Nothing is created before Criar rascunho, and the automation is born as a draft. Offline or without credits, the dialog says why. Ou usa um modelo goes to the Modelos page, which works offline.
The editor
The editor shows steps as cards on a grey dotted ground. The trigger is the first card, followed by the step chain: click the square + on the connecting thread to open the step picker and insert a step there, click a card to edit its configuration. Each card shows the step number, title, a summary and chips for its consequences, run status and duration. A card can be collapsed to a single line (the card chevron, double tap or the ⋮ menu); Recolher passos / Expandir passos, next to Recolher todos os ramos, does the same for all of them. Branching steps (if/else, AI-routed) fork the canvas into side-by-side lanes that merge back.
To get around a large flow: Ctrl/⌘ + wheel (or a trackpad pinch) zooms between 50 % and 200 %; dragging the background, space + drag or a two-finger scroll pans the canvas. The − 100 % + buttons in the bottom-left corner adjust the zoom, and Centrar no fluxo fits the whole flow into the visible area.
Changes are a draft until Guardar nova versão — saving creates a new version; earlier versions and their run history stay intact. A warnings band above the canvas flags incomplete configuration (e.g. a missing target feature); Executar is disabled while there are unsaved changes or unresolved errors.
Configuration
Each automation's configuration opens in a dialog, from the edit button that shows on the automation's row in the sidebar (on hover) or from Configurar in the automation's header. It has the sections Identidade (name, description, table, trigger, steps), Dono e etiquetas (the Dono and the Etiquetas), Avisos (Avisar o dono quando falha; the email arrives in a later update), Onde aparece and Versões. Changes are saved with Guardar; they are no longer applied as you type. Onde aparece says whether the automation shows as a button on records (only manual ones with a table). Versões lists the applied versions with the author, date and runs of each, read-only: there is still one active version, one draft and one Aplicar.
Running a workflow
Manually, where the button appears depends on the trigger's scope:
- Genérico, Feature, Vista — the Ações entry in the toolbar of the six record views (table, kanban, list, cards, calendar and gantt), in three groups: Genéricas (every view), Da tabela (that table's views) and Desta vista (only the view chosen in the trigger). Configurar → Ações picks which ones show; by default every eligible one does. Workflows the app runs on its own (timer hooks, a managed table's refresh) are left out.
- Linha — the table's selection bar: with rows selected, Ações runs the workflow once per row.
- The Workflow component, on a form or a table column, and the record detail panel's actions menu also fire Genérico, Linha and Feature. The component refuses a Vista-scoped workflow and points you to the view's Ações entry.
Automatically, a workflow fires on its own once its trigger condition is met: a matching record change, a scheduled slot, or an incoming webhook call — no user action needed.
To test a workflow before wiring up its real trigger, use the editor's Testar button: for file.upload it opens the real upload dialog; for every other trigger it opens a simulation dialog where you pick a real row or type JSON by hand. Modo teste starts on: write steps write nothing and only log what they would do (AI steps still run and spend credits).
After launching, the dialog stays open and follows the run: each step with its status and duration, the error of the step that failed and, for each step that writes to a table, O que teria sido escrito with the first rows. Correr de novo repeats it with the same data. On a draft that ran green, Aplicar e ativar applies the changes and turns the automation on. You can close it at any time: the run carries on and stays in Execuções.
Runs
The Runs page lists the workspace's runs, newest first. It opens on today; change the period to 7 or 30 days, and filter further by automation and trigger. The pills at the top (Todas, Falhadas, Em curso, Com revisão) show how many runs are in each status and filter the list; they count the whole period, not just what is loaded (above 1000 they show "1000+"). The list refreshes by itself while any run is in progress.
Each row shows the automation, the status, the origin (the record, schedule or file that triggered it), the start, the steps and the duration. The list loads 25 at a time: at the bottom it says "A mostrar X de Y" and carregar mais brings the next ones.
Tapping a row opens the detail next to the list (on a narrow screen, in a dialog): how it was started, the origin, the version, the steps with their timings and Dados do passo. In Dados do passo the steps show as the editor's cards, each with what happened to it in this run (done and how long it took, failed and why, or did not run), with </> to see its input and output. If the automation changed since the run, or on a narrow screen, the steps show as a list. A failed run shows the step where it failed and offers Repetir execução; a run waiting for review offers Rever. If the same connection failed in two or more runs in the last 24 hours, the detail says so and links to Ligações to renew the key. Exportar CSV downloads up to 1000 rows of the current filter.
Each automation's Runs tab shows the same table for that automation only, with a column for the version each run used, runs per day, failures per step and who triggers them.
Activity, in your avatar menu, has three tabs: About my records (runs on records you created or own), Este workspace (runs as rows) and À minha espera (the reviews addressed to you, with Rever).
Test runs carry the Simulação mark and stay out of the indicators, the library chart and the failed count; the reviews they ask for still count.
Runs are read from the server: offline, the page says they can only be read online.
| Status | Meaning |
|---|---|
| Pendente | Queued, not picked up yet |
| A correr | In progress |
| A rever / A aprovar | Paused at a Gate, waiting for a person |
| A aguardar | Paused waiting on a webhook, schedule, or child runs |
| Sucesso | Completed |
| Falhou | Failed — hover the error icon for the reason |
| Cancelado / Rejeitado | Stopped, or rejected at a Gate |
Selecting a run highlights where it is on the canvas, and adds a Rever/Aprovar button directly on the paused step. Each run's history icon opens a step-by-step timeline: each step's name, status, duration and (via the </> button) the exact input and output data, for debugging.
A transient failure (e.g. a flaky external call) doesn't show as Falhou — the run goes back to Pendente and picks up automatically from where it stopped, up to a retry limit; the error icon shows the attempt count and the last failure reason.
Cancel a run
A queued, running or waiting run can be cancelled with Cancel, on the row or in the detail. A queued or waiting run stops at once. A running one stops before the next step: the step already running finishes what it started, so what it already wrote stays written. Cancelling needs a network connection.
What an automation changed
A record's history says when an automation changed it, with View run. A run's detail lists under Changes made the records it created or updated (deletes do not show yet).
Running an automation from a record asks for confirmation.
Failure notice
If the automation has an owner and the failure notice turned on, the owner gets an "Automation failed" notification in the bell for each failed run, on the record it ran on (consecutive failures of the same automation within 15 minutes are grouped into one notice, with the count). Tapping the notice opens the run. Test runs send no notice.
Tips
- A workflow needs a trigger and at least one step — an empty chain can't run.
file.uploadneeds a target feature configured on amapstep before it lets you upload.- Auto-approval on Revisão humana is fail-closed: a missing confidence value, or one below the threshold, still goes to a person.
- Aprovação has no per-approver assignment — anyone who opens the run can approve or reject it.
- Nested Sub-workflow calls are capped at 5 levels, to avoid runaway recursion.
- Archiving a workflow stops it from firing and keeps its run history. In Arquivadas, Restaurar returns it to the library paused, and Apagar de vez asks for the workflow's name and also deletes the history.