KEPLIN Docs

Passos, decisões e esperas

O catálogo dos nós de um workflow — condições, escritas no registo, notificações, emails, scripts, IA, esperas, ciclos, paralelismo e junções.

Esta página percorre todos os tipos de passo que se arrastam da paleta Nós para a tela. Para cada um: o que faz, o que se preenche e o que acontece na execução.

Antes disso, uma peça que se repete em quase todos: a origem de um valor.

De onde vem um valor

Sempre que um passo pede um valor — o lado direito de uma condição, o que se escreve num campo — a interface oferece as mesmas quatro origens:

Origem O que traz
Valor fixo Um texto escrito à mão ("Ganha", "25000").
Campo do registo Um campo do registo de que a execução trata.
Variável Uma das variáveis do processo.
Quem iniciou Quem mandou o processo arrancar — Utilizador (o username) ou Id do utilizador.

É por isto que um processo não precisa de código para a maior parte do que faz: as decisões e as escritas compõem-se com estas quatro peças.

Condição

Abre dois caminhos a partir de uma pergunta. Tem sempre duas saídas fixas: Verdadeiro e Falso.

O diálogo Condições do passo
O diálogo Condições do passo

  1. Selecciona o passo e abre Condições no botão ….
  2. Clica em Acrescentar condição.
  3. Escolhe a origem do lado esquerdo (normalmente Campo do registo), o campo, o operador e o lado direito.

Os operadores são os mesmos dos filtros e das regras de formatação do resto da plataforma:

Operador Significa
eq / neq Igual a / diferente de
gt / gte Maior que / maior ou igual a
lt / lte Menor que / menor ou igual a
contains Contém o texto
startsWith / endsWith Começa por / acaba em
isEmpty / isNotEmpty Está vazio / não está vazio

"Todas têm de se verificar" — várias condições no mesmo passo combinam-se com E, nunca com OU. Para um OU, usa dois passos de condição em cadeia.

Sem condições nenhumas, "segue sempre por «Verdadeiro»" — útil enquanto se desenha, perigoso se ficar assim.

Escrever no registo

Grava campos no registo de que a execução trata. É o passo que fecha o circuito: o processo decidiu, agora a ficha do CRM tem de reflectir isso.

O diálogo Campos a escrever no registo
O diálogo Campos a escrever no registo

  1. Abre Campos a escrever no botão ….
  2. Clica em Acrescentar campo.
  3. Escolhe o Campo e a origem do valor.

No exemplo, o passo Marcar como Ganha escreve fase = "Ganha" (valor fixo) e responsavel = Quem iniciou (o username de quem começou o processo).

Nota

A escrita é feita "pelo mesmo GraphQL da app, com a autorização de quem começou". Ou seja: as permissões contam. Se quem iniciou o processo não pode alterar aquela entidade, o passo falha — e falha bem, porque um processo não é uma porta das traseiras às permissões.

Um passo sem campos nenhuns "não faz nada" — a interface di-lo em vez de o esconder.

Notificar

Manda uma notificação dentro da app — o sino da navegação, em tempo real para quem está com sessão aberta, e na caixa de entrada para quem não está.

Campo Notas
Utilizadores Contas da app, escolhidas à mão.
Papéis Todos os utilizadores com esse papel. Sobrevive a entradas e saídas de pessoas.
Título A linha que aparece na notificação.
Texto O corpo.

No título e no texto podes meter valores do registo ou de variáveis entre chavetas: A oportunidade {titulo} foi rejeitada.

Email

Igual ao Notificar, mas o destino é o email, pelo canal configurado nas definições da app. Tem dois campos a mais: o corpo é HTML, escrito num editor próprio, e pode levar um relatório em anexo.

O passo Email seleccionado, com o painel de propriedades
O passo Email seleccionado, com o painel de propriedades

Campo Notas
Utilizadores / Papéis Os destinatários. Quem não tiver email fica de fora.
Assunto Aceita {campo} como o resto das mensagens.
Texto Abre um editor de HTML no botão … (Corpo do email).
Anexar relatório Um dos relatórios da app, ou Sem anexo.

Sobre o anexo: "o PDF é gerado no momento do envio, para o registo desta execução" — não é um ficheiro guardado, é o documento daquele caso, feito naquele instante. Ver o capítulo Relatórios.

Atenção

Sem canal de email activo e com SMTP completo nas definições da app, o passo não consegue enviar. Configura-o em Definições da app → Notificações antes de pôr o processo a correr.

Correr script

Chama um script Python da app, a meio do processo. É a válvula de escape para tudo o que o desenho não faz: chamar um serviço externo, calcular uma margem, validar contra outro sistema.

O passo Correr script seleccionado
O passo Correr script seleccionado

Campo Notas
Script Um dos scripts da app.
Guardar em A variável onde fica o que o script devolver. Vazio = "deita fora".

O script "recebe o registo, a chave e as variáveis nos argumentos" — não é preciso passá-los à mão. O que ele devolver fica na variável indicada e passa a estar disponível para os passos seguintes.

Se o script falhar, a execução fica em Falhou nesse passo, com o erro guardado no histórico.

IA

Faz um pedido a um modelo de IA da app a meio do processo: classificar um pedido, resumir uma descrição ou tirar os dados de um documento anexado. A resposta fica numa variável, para os passos seguintes a usarem.

Campo Notas
Modelo Um dos modelos de IA de texto da app. Predefinido usa o que está marcado como predefinido nos Modelos de IA da app.
Pedido O que o modelo tem de fazer. Aceita valores do registo e de variáveis entre chavetas: Resume este pedido de suporte: {descricao}.
Instrução Opcional. O papel e as regras do modelo, iguais em todas as execuções.
Ficheiros Opcional. Campos de ficheiro do registo ou variáveis com ficheiros: imagens, PDF e texto, até 20 MB cada.
Resposta em dados Opcional. Um JSON Schema. Com ele, a resposta chega em dados já validados, em vez de texto.
Guardar em A variável onde fica a resposta.
Caminho na resposta Com um JSON Schema, guarda só uma parte da resposta, por exemplo urgente.

O passo tem duas saídas: OK, quando o modelo respondeu, e Erro, quando a chamada falhou. Quando falha, a variável fica com { error, code }, com o mesmo código que os scripts recebem (ver Usar a IA nos scripts).

Para o processo decidir pelo que o modelo respondeu:

  1. Declara uma variável urgente, do tipo Sim/Não.

  2. No passo IA, escreve em Pedido Este pedido de suporte é urgente? {descricao} e, em Resposta em dados, o schema:

    {
      "type": "object",
      "properties": { "urgente": { "type": "boolean" } },
      "required": ["urgente"]
    }
    
  3. Em Guardar em, escolhe urgente. Em Caminho na resposta, escreve urgente.

  4. Liga a saída OK a uma Condição com a variável urgente, o operador eq e o valor fixo true.

Com a Depuração dos Modelos de IA da app ligada, o histórico da execução mostra o texto do pedido e da resposta.

Nota

Um processo corre sem ninguém à espera, por isso o passo IA não mostra a resposta no ecrã enquanto o modelo a escreve. Para isso, ver Respostas em directo no ecrã.

Esperar

Adia o processo por um tempo fixo: Dias e Horas. "Zero em ambos = não espera nada."

É a peça de "avisa-me daqui a três dias se ainda não houver resposta". A execução dorme e é retomada automaticamente à hora certa, mesmo que o servidor tenha sido reiniciado pelo meio.

Esperar evento

Adia o processo até alguém mandar um sinal com um nome combinado.

O passo Esperar evento seleccionado
O passo Esperar evento seleccionado

O único campo é o Nome do sinal (no exemplo, dados-completos). "Quem manda o sinal escreve este nome. Sem hora marcada: se ninguém o mandar, o processo fica à espera."

O sinal manda-se de duas formas:

  • num evento de ecrã (TypeScript): keplin.workflow.signal("dados-completos", id)
  • num script (Python): workflow.signal("dados-completos", key=id)

Sem indicar o registo, o sinal acorda todos os processos parados naquele nome; com o registo, só os desse. Zero acordados não é erro — quer dizer que ninguém estava à espera.

Dica

É comum combinar Esperar evento com uma seta de volta a uma tarefa: a pessoa devolve o caso pedindo mais dados, o processo fica à espera do sinal, e quando o comercial completa a ficha o sinal traz o caso de volta à mesma tarefa. É exactamente o que o exemplo desta documentação faz.

Ciclo

Percorre uma lista, um valor de cada vez. Tem duas saídas: Cada (o corpo do ciclo, que corre uma vez por valor) e No fim (quando a lista acaba).

Campo Notas
Lista A variável com os valores a percorrer. "Um passo de script costuma ser quem a produz."
Guardar cada em A variável que fica com o valor da volta actual.

Sem lista escolhida, o desenho avisa: "Este ciclo não diz que lista percorrer: sai logo por «No fim»."

Paralelo

Arranca vários caminhos ao mesmo tempo. Cada ramo é uma saída do nó.

O diálogo Ramos em paralelo
O diálogo Ramos em paralelo

  1. Abre Ramos em paralelo no botão ….
  2. Cada linha é um ramo, com uma Etiqueta (o que se lê no desenho) e um Identificador.
  3. Liga cada saída ao primeiro passo do ramo respectivo.

No exemplo, o passo Fechar e comunicar abre dois ramos: Registo (que grava a fase) e Cliente (que envia o email). Nenhum espera pelo outro.

Junção

Volta a juntar os ramos de um Paralelo. É o passo que responde a "por quantos é que se espera?".

A Junção seleccionada, com o painel de propriedades
A Junção seleccionada, com o painel de propriedades

Esperar por O que faz
Todos os ramos O processo só segue quando o último ramo chegar.
O primeiro decide Segue com o primeiro que chegar — "os outros ramos são cancelados quando um chega".
Um número deles Segue ao fim de Quantos ramos indicares.

Sub-workflow

Chama outro processo, sobre o mesmo registo.

Campo Notas
Processo a correr Um dos workflows da app.
Esperar que acabe Ligado, este processo pára até o outro terminar. "Desligado, este processo segue em frente e o outro corre por sua conta."

"Corre sobre o MESMO registo, e por isso tem de tratar da mesma entidade" — um processo sobre oportunidades não pode chamar um processo sobre contas. E um processo não se pode chamar a si próprio: "seria uma recursão sem fim", e o desenho acusa-o.

Com Esperar que acabe ligado, este processo segue quando o outro termina — pelo nó de Fim, por ficar sem caminho, ou por falhar. O histórico deste processo diz como o outro acabou; um processo chamado que falha não faz falhar o que o chamou.

Fim

Termina a execução. Tem um único campo, Resultado, um texto curto como aprovado, ganha ou perdida. "Fica no histórico e é o que o widget de estado mostra."

Um processo pode ter vários nós de Fim — um por desfecho — e é isso que se deve fazer: em vez de um Fim genérico, um por resultado, para o histórico dizer alguma coisa a quem o lê meses depois.

Como se lê um passo na tela

Cada caixa na tela mostra três coisas: o nome do passo (o que escreveste em Nome do passo, e o que aparece no histórico), o tipo em letras pequenas por baixo, e as saídas à direita, com o nome de cada uma. Um triângulo âmbar no canto assinala um passo com problemas.

Dica

Dá nomes de negócio aos passos — "Aprovação da direcção", "Marcar como Ganha" — e não nomes técnicos. É esse texto que vais ler no histórico de cada execução quando alguém perguntar "onde é que este caso está parado?".