Formulários

Formulários são as interfaces de entrada de dados vinculadas a tarefas ou usados de forma standalone. Cada tarefa de um processo pode ter um formulário diferente, com campos e regras específicos para aquela etapa.

Como preencher um formulário (visão do usuário)

1. Abra uma tarefa (em Tarefas → Minhas tarefas)
2. O formulário da tarefa é exibido automaticamente dentro do painel da tarefa
3. Preencha os campos conforme as instruções — campos obrigatórios estão marcados com *
4. Clique em Enviar para concluir a tarefa; as respostas viram variáveis de processo automaticamente

TIP

A versão do formulário exibida é a que estava publicada no momento em que a tarefa foi criada. Atualizações posteriores no formulário não afetam tarefas já abertas.

Construtor visual de formulários (admin)

Administradores criam e editam formulários em Formulários na barra lateral, usando o construtor visual drag & drop.

Interface do construtor

O construtor tem três painéis:

Painel	Função
Esquerda — Paleta	Tipos de campo agrupados por categoria; clique para adicionar ao formulário
Centro — Canvas / Pré-visualização	Lista de campos em ordem; arraste para reordenar; aba "Pré-visualização" mostra a renderização real
Direita — Propriedades	Configurações do campo selecionado

Tipos de campo disponíveis

Grupo	Tipo	Descrição
Texto	text	Texto curto livre
Texto	textarea	Texto longo multilinha
Texto	email	Endereço de e-mail (validação automática)
Texto	phone	Telefone
Texto	url	Endereço web (URL)
Numérico	number	Valor numérico
Numérico	currency	Valor monetário (R$)
Numérico	percentage	Percentual (%)
Data/Hora	date	Seletor de data
Data/Hora	datetime	Seletor de data e hora
Data/Hora	time	Seletor de horário
Data/Hora	date-range	Intervalo de datas (data inicial e final)
Documentos BR	cpf	CPF (máscara automática)
Documentos BR	cnpj	CNPJ (máscara automática)
Documentos BR	cep	CEP (máscara automática)
Escolha	select	Dropdown com opções fixas
Escolha	multiselect	Seleção múltipla
Escolha	radio	Opções únicas (radio buttons)
Escolha	checkbox	Múltiplos checkboxes
Escolha	boolean	Sim / Não
Busca	lookup	Busca paginada em API externa (digitação live)
Arquivo	file	Upload de arquivo (configurável: tipos aceitos, múltiplos)
Avaliação	rating	Avaliação por estrelas (1–10)
Layout	heading	Título de seção (H2/H3/H4)
Layout	separator	Separador horizontal

Propriedades gerais de cada campo

Propriedade	Descrição
Rótulo	Texto exibido acima do campo
Chave (key)	Identificador único — vira o nome da variável de processo ao submeter
Tipo	Tipo de campo (veja tabela acima)
Largura	100% / ½ / ⅓ / ¼ — controla a coluna no grid responsivo
Obrigatório	Marca o campo como obrigatório na validação
Placeholder	Texto de exemplo dentro do input
Instrução / Ajuda	Texto descritivo exibido abaixo do rótulo

Grid responsivo

O formulário usa CSS Grid com até 4 colunas. A propriedade Largura de cada campo define quantas colunas ele ocupa:

Largura	Colunas	Visual
full	linha inteira	Ocupa toda a largura
half	2/4	Metade da linha
third	1/3	Um terço da linha
quarter	1/4	Um quarto da linha

Em telas pequenas (mobile), todos os campos ocupam a largura total independentemente da configuração.

Regras condicionais

Cada campo pode ter uma ou mais regras condicionais configuradas no painel de propriedades. Uma regra define:

Propriedade	Descrição
Ação	O que acontece quando a condição é verdadeira
Campo observado	Qual outro campo é monitorado
Operador	Como comparar o valor (=, ≠, contém, vazio, não vazio, >, <)
Valor	Valor a comparar (não necessário para vazio/não vazio)

Ações disponíveis

Ação	Efeito
Mostrar este campo	Campo fica visível quando a condição for verdadeira (padrão: oculto)
Ocultar este campo	Campo fica oculto quando a condição for verdadeira
Habilitar este campo	Campo fica editável quando a condição for verdadeira
Desabilitar este campo	Campo fica bloqueado quando a condição for verdadeira
Tornar obrigatório	Campo vira obrigatório quando a condição for verdadeira
Carregar opções de API	Disponível apenas para campos de escolha (select, multiselect, radio, checkbox). Carrega as opções a partir de uma URL, substituindo {value} pelo valor do campo observado

WARNING

Se um campo tiver regra Tornar obrigatório, o checkbox estático "Obrigatório" fica desabilitado — quem controla a obrigatoriedade são as regras.

Validações

Além da obrigatoriedade, cada campo suporta validações específicas por tipo:

Tipo do campo	Validações disponíveis
Texto curto (text), Texto longo (textarea)	Regex personalizado com mensagem; Mínimo/máximo de caracteres
E-mail (email), Telefone (phone), URL (url)	Mínimo/máximo de caracteres
Número (number), Moeda (currency), Percentual (percentage)	Valor mínimo e máximo
Data (date), Data e Hora (datetime), Horário (time), Intervalo de Datas (date-range)	Data mínima e máxima
CPF, CNPJ, CEP	— formato fixo, sem validações adicionais configuráveis
Seleção, Avaliação, Arquivo, Busca, etc.	— não possuem validações configuráveis

TIP

Campos com formato fixo como CPF (000.000.000-00), CNPJ (00.000.000/0000-00) e CEP (00000-000) já aplicam a máscara automaticamente. Não é necessário configurar regex ou comprimento para eles.

Intervalo de Datas (date-range)

O campo date-range exibe dois seletores de data — inicial e final — em linha. O valor salvo é um objeto { start: "YYYY-MM-DD", end: "YYYY-MM-DD" }. Validação automática garante que a data inicial seja anterior ou igual à data final.

Busca paginada (Lookup)

O campo lookup faz requisições à medida que o usuário digita (mínimo de 2 caracteres). Configure:

Propriedade	Descrição
URL	Endpoint com {search} que será substituído pelo texto digitado
Campo label	Propriedade do JSON de resposta a exibir como texto
Campo valor	Propriedade do JSON de resposta a usar como valor salvo

Exemplo de URL: https://api.empresa.com/clientes?q={search}

Versionamento de formulários

Todo formulário é versionado automaticamente. A cada salvamento, uma nova versão imutável é criada.

Publicar uma versão

1. Acesse o formulário em Formulários → [nome do formulário]
2. Clique na aba 🕑 Histórico
3. Localize a versão desejada e clique em ↑ Publicar esta versão
4. A versão publicada aparece com o badge ✓ Publicada e borda verde

Comportamento de versão em tarefas

• Quando uma tarefa é criada em um processo, o sistema trava automaticamente a versão publicada do formulário naquela tarefa
• Se nenhuma versão foi publicada explicitamente, a versão mais recente é usada
• Publicações futuras não afetam tarefas já criadas — cada tarefa sempre exibe o formulário com o schema que tinha no momento de sua criação
• As respostas submetidas viram variáveis de processo no Flowable

Restaurar uma versão no editor

Na aba 🕑 Histórico, clique em Restaurar no editor para carregar o schema de uma versão antiga no construtor visual. Isso não altera o formulário — é preciso salvar para criar uma nova versão.

Formulários standalone

Além de formulários vinculados a tarefas, o sistema pode ter formulários avulsos para coleta de dados ou início de processos. Acesse-os pela seção Formulários na barra lateral.

Micro-Frontend Plugins (Formulários Externos)

Para casos de uso muito complexos que a ferramenta Low-Code do construtor visual não atenda (ex: renderizações pesadas em 3D, drag and drop de arquivos avançado customizado, integrações de socket ao vivo), o Flow.IA suporta Remote Form Plugins.

Como Funciona: Você pode desenvolver um projeto React/Vite isolado, seguindo a nossa estrutura recomendada (custom-form-boilerplate), fazer o build do componente form e expor essa URL num servidor estático (S3, Vercel, Nginx).

Como Configurar:

1. Abra o Modelador BPMN/CMMN.
2. Na tarefa de usuário (User Task) ou no evento de início (Start Event) do processo, acesse as propriedades.
3. No campo Form Key (ou Start Form Key), insira diretamente a URL do Plugin (ex: http://localhost:3001/assets/plugin.js).
4. Quando o usuário abrir a Tarefa ou Processo que possua uma formKey iniciada com http:// ou https://, o Flow.IA automaticamente reconhecerá como um plugin externo. Ele vai baixar assincronamente o bundle e injetar a interface diretamente na tela, passando variáveis de contexto via props. Não é necessário salvar um schema local no construtor de formulários.

Boilerplate e Validação (React Hook Form + Zod)

O projeto base recomendado (custom-form-boilerplate) já vem pré-configurado com as melhores práticas de mercado utilizando React Hook Form e Zod. Ele implementa a mesma arquitetura lógica do construtor visual nativo do Flow.IA, garantindo estabilidade na injeção e extração de dados:

• Injeção de variáveis (defaultValues): O Flow.IA entrega as variáveis do processo atual através da prop initialVariables. O formulário injeta esses dados nativamente usando o defaultValues do React Hook Form.
• Validação tipada (Schema Zod): Regras complexas de formulário são definidas via código (z.object({...})), garantindo total Type Safety e bloqueando o envio se os dados estiverem inconsistentes.
• Salvamento Parcial e Conclusão (onSave e onComplete): Ao salvar o rascunho (chamando a prop onSave injetada), a validação rígida do Zod pode ser ignorada, capturando os dados atuais com getValues(). Mas ao avançar a tarefa (onComplete), os dados são validados pelo schema e empacotados no exato formato esperado pelo motor de processos.