Tarefas para pessoas

Um workflow que só escreve campos e manda emails podia ser um script. O que faz dele um processo de negócio é a Tarefa: um passo que fica à espera de uma pessoa, com botões próprios, prazo e um ecrã para ela decidir.

Esta página trata das tarefas, de quem manda o processo arrancar e de como se acompanha o que está a correr.

#O passo Tarefa

Arrasta Tarefa da paleta para a tela e selecciona-a. O painel da direita mostra tudo o que uma tarefa precisa:

Campo	O que faz
Nome do passo	O que a pessoa lê na lista de tarefas e o que fica no histórico.
Utilizadores	Contas da app escolhidas à mão.
Papéis	Todos os utilizadores com esse papel.
Ecrã a abrir	O ecrã que a pessoa abre para decidir. Recebe a chave do registo como parâmetro. Nenhum = decide-se só pelos botões.
Prazo (dias)	Dias a contar do momento em que a tarefa nasce. 0 = sem prazo.
Decisões	Os botões que a pessoa vê. Ver abaixo.

Sobre os destinatários: "quem fica com a tarefa é resolvido quando ela nasce — mudar de papel depois não tira a tarefa a quem já a tinha". Uma tarefa atribuída na segunda-feira a quem tinha o papel direcao continua com essas pessoas mesmo que o papel mude na quarta.

#Decisões — os botões e os caminhos

Uma decisão é, ao mesmo tempo, um botão no ecrã e uma saída no desenho. Declara-se uma vez.

1. Abre Decisões no botão ….
2. Cada linha tem uma Etiqueta (o que a pessoa lê: "Aprovar") e um Identificador (o que o código usa: aprovar).
3. Clica em Acrescentar decisão para as que faltarem.
4. Fecha e liga, na tela, cada saída ao passo que lhe corresponde.

No exemplo, a tarefa Aprovação da direcção tem três: Aprovar, Rejeitar e Pedir mais dados. Cada uma leva o processo por um caminho diferente — a primeira fecha o negócio, a segunda marca-o como perdido, a terceira devolve o caso ao comercial e espera pelo sinal dele.

#O que a pessoa vê na app

Do lado de quem usa a aplicação, uma tarefa aparece por dois widgets do construtor de ecrãs:

Widget	O que mostra
As minhas tarefas	A caixa de entrada de quem tem sessão: as tarefas abertas dele, com os botões de decisão de cada uma.
Estado do processo	Onde está o processo de um registo — "Agora em", os últimos saltos, e (opcionalmente) os botões de decisão.

Propriedades que valem a pena conhecer:

• Mostrar botões de decisão — "só aparecem quando a tarefa aberta está atribuída a quem está a ver". Ninguém decide por outra pessoa.
• Abrir o ecrã da tarefa — ao clicar numa tarefa, abre o ecrã que ela indica, já com a chave do registo.
• Saltos a mostrar (no Estado do processo) — quantos passos do histórico se vêem.
• Entidade e Chave do registo — que registo o widget está a seguir.

Quando a pessoa carrega num botão, a tarefa fecha-se e o processo segue pela saída correspondente — de imediato, sem ninguém ter de ir "correr" nada.

Em código, o mesmo faz-se com o SDK dos ecrãs (TypeScript):

const minhas = await keplin.workflow.tasks();
await keplin.workflow.complete(minhas[0].id, "aprovar", { nota: "ok" });

#Formas de arranque

Um workflow não sabe quem o arranca — e é de propósito. Quem decide é o ecrã, o código ou o processo pai. São quatro as formas:

Forma	Como se faz
Botão ou evento de um ecrã	Num evento TypeScript: await keplin.workflow.start("wf_4ef9ed11", id).
Script Python	workflow.start("Aprovação de oportunidade", 42) — aceita o nome ou o identificador.
Sub-workflow	Um passo Sub-workflow noutro processo, sobre o mesmo registo.
Sinal	Um processo já a correr, parado num Esperar evento, é retomado com signal(...).

Em qualquer delas, a chave do registo é obrigatória: toda a execução trata de um registo. O arranque responde "assim que o motor encontra a primeira espera — nunca fica à espera que o processo acabe", e devolve o identificador da execução criada.

O identificador do processo (wf_…) copia-se no cabeçalho do desenho, com um clique — é o que se cola no código.

#Acompanhar as execuções

No separador Execuções do processo vê-se tudo o que já correu:

No topo, um filtro por estado (Todos os estados), a contagem de execuções e o botão Apagar as terminadas. Um processo que ainda não correu mostra "Este processo ainda não correu nenhuma vez.".

Os estados de uma execução:

Estado	Significa
A correr	Está a executar passos neste momento.
À espera	Parada — numa tarefa, num Esperar ou num Esperar evento.
Concluída	Chegou a um Fim.
Falhou	Um passo deu erro (um script que rebentou, uma escrita recusada).
Cancelada	Foi terminada antes do fim.

Cada linha mostra o registo, o estado, quando começou e quantos passos deu. Abrindo a linha vê-se o histórico — uma entrada por acontecimento, com o nome do passo tal como está no desenho:

Acontecimento	Quando aparece
arrancou	No início da execução.
passo	Cada passo executado.
decisão	Uma condição que escolheu um caminho, ou uma tarefa decidida.
esperou / retomou	Entrou numa espera / foi acordada.
acabou / falhou / cancelada	O desfecho.

O botão Ver o caminho no desenho é o mais útil de todos: acende, na tela, os passos por onde aquela execução passou, numerados pela ordem em que aconteceram. Volta-se ao normal em apagar o caminho, ao lado dos separadores.

#Limpar o histórico

Apagar as terminadas "apaga as execuções concluídas, falhadas e canceladas deste processo, com o histórico delas. As que estão a correr ou à espera ficam. Não há como voltar atrás."

Para uma política automática, usa a Rotação de registos nas definições da app: as fichas de workflow terminadas são apagadas ao fim do prazo que definires, "as que ainda correm ou esperam por alguém nunca são apagadas", e "as que falharam ficam o dobro do tempo".

#Perguntas frequentes

A pessoa não vê a tarefa dela. Por ordem de probabilidade: o ecrã onde está o widget As minhas tarefas não está acessível a ela; a tarefa foi atribuída a um papel que ela não tem; ou a conta da app não é a mesma pessoa que julgas — as contas da app são independentes das contas da plataforma (ver Utilizadores da app).

Posso reatribuir uma tarefa a outra pessoa? A atribuição fica fixada no momento em que a tarefa nasce. Para casos de substituição, desenha o processo com Papéis em vez de utilizadores: basta dar o papel a quem substitui.

O prazo faz alguma coisa sozinho? O prazo marca a tarefa e mostra-se a quem a tem. Para agir sobre um atraso — avisar o chefe, escalar — desenha esse caminho: um Paralelo com um ramo que segue para um Esperar de N dias e daí para um Notificar.

Uma execução falhou. Consigo retomá-la? Uma execução falhada fica registada com o passo e o erro. O caminho normal é corrigir a causa (o script, a permissão) e arrancar o processo outra vez sobre o mesmo registo — se a concorrência estiver em Só uma de cada vez, confirma antes que a execução falhada já não conta como viva.