Como funciona o Construtor de Workflows: contexto, tipos e execução

Construtor de Workflows

Monte, num canvas, um fluxo que encadeia ferramentas do lab (JSON, crypto, regex, datas…) e execute de verdade no navegador. Cada nó tem entradas e saídas tipadas, e o próprio editor aponta erros de configuração antes de você rodar.

Dois grafos no mesmo canvas

O canvas mostra duas relações diferentes entre os nós, e o seletor Ordem / Dados / Ordem + dados escolhe quais aparecem:

A separação é proposital: a ordem diz quando um nó roda, as dependências dizem o que ele lê. Um nó pode ler a saída de qualquer nó que já tenha rodado antes dele no mesmo ramo, não só a do pai imediato. No inspector, a seção Dependências de dados lista o que o nó lê e quem usa as saídas dele.

Origem das entradas

Cada entrada de um nó tem uma origem:

• Input do workflow: um campo declarado no nó Início, pedido quando a execução começa e lido como start.campo.
• Contexto: um caminho na saída de um nó anterior, como jsonQuery.result ou hash.hex. O seletor só lista caminhos disponíveis naquele ponto do fluxo e desabilita os de tipo incompatível.
• Pedir na execução: a execução pausa e pede o valor num formulário.
• Nenhuma: se a entrada for obrigatória, ela vira um input de runtime implícito: o editor avisa e oferece dois atalhos, transformar em input do workflow ou marcar como "pedir na execução".

Contexto previsível

Durante a execução, as saídas de cada nó entram no contexto sob o id do nó:

{
  "start": { "document": "{\"user\":{\"email\":\"ana@exemplo.com\"}}" },
  "jsonQuery": { "result": "ana@exemplo.com", "count": 1 },
  "hash": { "hex": "5f2b…" }
}

Como ainda não há junção de ramos, cada nó tem no máximo um antecessor e o fluxo é uma árvore a partir do Início. Por isso o contexto disponível em cada nó é exatamente o dos seus ancestrais, e o editor sabe, antes de rodar, quais caminhos existem em cada ponto. Um nó num ramo da Condição nunca enxerga o que foi produzido no outro ramo.

Nem toda saída precisa ir para o contexto. No inspector, cada saída tem a opção Exportar para o contexto (ligada por padrão). Uma saída oculta não aparece no canvas nem no seletor de origem, não pode ser lida por outros nós e não entra no log da execução; o nó indica quantas saídas estão ocultas. Ocultar uma saída que alguém usa pede confirmação, e as entradas que a liam passam a mostrar um erro até ganharem outra origem. As saídas do Início e do Pedir input são sempre exportadas.

Tipos

As entradas e saídas usam tipos estruturados: string, number, boolean, any, enum, listas (string[]) e objetos com campos obrigatórios ou opcionais. Eles são verificados em dois momentos:

1. Na edição: o tipo da origem precisa caber no tipo da entrada. Um any só cabe numa entrada any; para ler um campo interno de uma saída livre, declare o formato dela.
2. Na execução: cada saída é conferida contra o tipo declarado. Um valor fora do formato para o fluxo com um erro claro no nó.

As entradas de JSON (Formatar, Consultar, Validar schema, Achatar e JSON → YAML) aceitam o documento como texto JSON ou como um valor já interpretado por outro nó, por exemplo o value do Formatar. Um texto é sempre lido como JSON.

Saídas livres, como o resultado do JSONPath ou o valor convertido do YAML, podem ter o formato declarado no inspector, escrito à mão ou inferido de um exemplo colado em JSON.

Listas

Os nós do grupo Listas operam sobre qualquer lista, e o tipo da saída acompanha a lista ligada na entrada: se chega uma string[], sai uma string[]; o Selecionar campo de year sobre uma lista de { year, month } devolve string[].

Exemplo: Regex: extrair (todas as ocorrências, texto do match) → Remover repetidos → Juntar em texto devolve os e-mails únicos de um texto, um por linha. O Regex também pode entregar só a primeira ocorrência, um grupo de captura ou os grupos nomeados como um objeto tipado pelo padrão.

Validação contínua

A cada edição o workflow é revalidado. Os problemas aparecem no próprio nó, no painel Problemas (clicar leva ao nó) e bloqueiam o botão Executar enquanto houver erro:

Execução

• A árvore é percorrida em largura a partir do Início. A Condição avalia a regra e segue só o ramo escolhido; os nós do outro ramo ficam como pulados.
• Antes de cada nó, as entradas que dependem de valor manual pausam a execução e abrem o formulário. Ao continuar, ela segue de onde parou.
• Passo a passo executa um nó por clique, útil para acompanhar o contexto crescendo.
• O painel de execução mostra o resultado final, cada passo com suas entradas e saídas, e o contexto acumulado.

Salvar, exportar e importar

• Rascunho automático: o workflow aberto é guardado a cada edição, então recarregar a página não perde nada.
• Salvos: guarde vários workflows com nome e alterne entre eles. Trocar com alterações pendentes pede confirmação.
• Exportar / importar: o arquivo JSON (format: "cicerotcv-workflow") pode ser versionado ou compartilhado. Na importação, o formato é validado e os problemas do workflow aparecem antes de executar.

Limites atuais

• Sem junção de ramos: cada nó tem no máximo um antecessor.
• Ainda não há nós de requisição HTTP nem de código.
• Os nós rodam no navegador, sem acesso à rede.