Catálogo de Processos

Nível de acesso requerido

Admin ou Super Admin

O que é uma definição?

Uma definição é o modelo de processo (BPMN) ou caso (CMMN) publicado na plataforma. A plataforma os divide entre escopo Global e Local.

Definições Locais (Processos do Tenant): O Admin do Tenant vê e gerencia as configurações daquele processo dentro da sua empresa, em Modelagem → Catálogo de Processos. Abrir um processo dá acesso às abas Diagrama, Documentação, Versões, Configurações, Variáveis, Base de Conhecimento, Agentes IA, Formulários, Auto-Aprendizado e Consumo de IA.

A aba Consumo de IA mostra o que aquele processo gastou no período, em tokens, por etapa e por modelo. Ao lado dos números há três colunas que dizem por quê: Iterações (quantas idas ao modelo cada execução levou), Contexto (quanto do prompt é texto recuperado das bases) e Desperdício (tokens gastos em chamadas que não responderam nada). Uma etapa marcada com o aviso é uma que vale olhar — e as três colunas apontam correções diferentes: prompt e ferramentas, escopo da base de conhecimento, ou tratamento de erro. Trocar por um modelo mais barato não corrige nenhuma das três. A aba é visível para quem administra e para quem modela.

Catálogo de Processos Globais: O Admin do Tenant também vê, na mesma lista, os processos globais disponíveis na plataforma:

• Ele não pode criar, editar modelos ou visualizar as configurações internas de desenvolvimento dos templates globais.
• Ele pode ativar ou desativar (usando o toggle switch) qualquer processo global para o seu próprio ambiente. Um processo desativado não aparecerá para os usuários iniciarem instâncias no portal ou via API naquele tenant específico.
• Rascunhos: Processos globais que ainda não foram oficialmente publicados aparecerão com o toggle desabilitado. O Admin não conseguirá utilizá-los até que o Super Admin finalize a publicação.

Publicando uma nova definição

Criar uma definição e desenhá-la são dois passos, nesta ordem.

Passo 1 — Criar a definição vazia

1. Acesse Modelagem → Catálogo de Processos
2. Clique em Nova Definição e escolha o tipo — BPMN, DMN Template ou CMMN
3. Informe a chave e o nome, e confirme

A definição é implantada na hora, com o desenho mínimo do tipo escolhido: para BPMN, um evento de início; para CMMN, o plano do caso vazio. Nenhum modelador abre nesse momento — a primeira versão aparece na aba Versões como Disponível, e publicar é um passo à parte.

Passo 2 — Desenhar no modelador

1. Abra a definição na lista
2. Clique em Editar / Nova versão — o modelador abre com o XML da versão atual carregado
3. Modele, e clique em Nova versão para publicar

Em BPMN, o modelador traz também Revisar com IA, que analisa o desenho antes de publicar.

Caminho alternativo — enviar um XML pronto

Quem já tem o arquivo desenhado não precisa passar pelos dois passos acima.

1. Acesse Modelagem → Catálogo de Processos
2. Clique em Importar XML, no alto da tela, ao lado de Nova Definição
3. Escolha o arquivo — são aceitos .bpmn, .bpmn20.xml, .cmmn, .cmmn.xml e .dmn

O arquivo é implantado assim que você confirma a escolha; não há uma janela de confirmação. Se o XML for recusado, a mensagem do servidor aparece no aviso vermelho logo abaixo do cabeçalho.

O mesmo envio continua disponível pela API, em POST /api/a/definitions/deploy com o arquivo no campo file — veja Referência da API.

No modelador CMMN, o painel de propriedades muda conforme o que você seleciona:

Selecionado	O que o painel oferece
Plano do caso (retângulo externo)	Auto-complete e o formulário de início do caso
Tarefa humana	Formulário, responsável, usuários candidatos, papéis candidatos, prazo e prioridade
Estágio interno	Auto-complete
Tarefa de serviço	Implementação (classe, delegate, expressão ou ✨ Agente de IA), variável de resultado, execução em segundo plano e os parâmetros do delegate
Tarefa de serviço com Agente de IA	Agente, instrução, variável de retorno, ferramentas desta etapa e bases desta etapa — os mesmos controles do modelador BPMN

Responsável e candidatos aceitam tanto uma pessoa da lista quanto uma expressão como ${gestor} — nesse caso, quem preenche o valor é o formulário de início.

O que o painel não edita, o modelador não apaga mais

Um caso pode chamar um processo ou outro caso e passar variáveis para ele — o bloco <flowable:in> / <flowable:out>, escrito à mão no XML. O painel continua sem campo para isso: quem quiser essa ligação escreve no arquivo e faz upload. O que mudou é que abrir e salvar o mesmo caso no modelador preserva esse trecho — antes ele desaparecia calado, e o caso voltava a rodar sem receber variável nenhuma.

A opção DMN Template faz coisas diferentes conforme o papel

Para o Super Admin, ela cria um template DMN global — a base a partir da qual cada tenant implanta a sua própria tabela de decisão. Para o Admin do tenant, ela implanta uma tabela de decisão diretamente no tenant, que passa a aparecer em Decisões DMN.

Editando uma definição existente

Para criar uma nova versão de uma definição já publicada:

1. Abra a definição e vá à aba Versões
2. Clique em Editar / Novo na linha da versão que serve de ponto de partida
3. O modelador abre com o XML daquela versão pré-carregado
4. Faça as alterações e clique em Nova versão para publicar

Na mesma aba, cada linha mostra o estado da versão — Publicada, Disponível ou Suspensa — e uma versão ainda não publicada traz o botão Publicar.

Versionamento

Ao publicar um arquivo com a mesma chave de processo, uma nova versão é criada automaticamente. Instâncias em andamento continuam na versão anterior; novas instâncias usam a versão mais recente.

Assistente de IA no modelador

O modelador tem um assistente que trabalha sobre o processo aberto. Além de desenhar o diagrama, ele configura o que existe em volta dele: pode criar e alterar formulários, criar bases de conhecimento e ligá-las ao processo, criar coleções de CMS, criar agentes de IA e vinculá-los a uma etapa.

Quatro coisas valem saber antes de usar:

• Ele diz o que fez. Cada formulário, base ou agente criado aparece listado na conversa, com nome e link. Quando uma instrução não pôde ser aplicada — uma conexão cujos elementos não existem, por exemplo — ele avisa em vez de seguir em silêncio.
• Ele não publica. Nada do que o assistente cria entra em um processo em execução: publicar a definição é uma ação sua, e é onde você confere o resultado rodando uma instância.
• Ele não edita um agente existente. Um agente já usado por um processo publicado passaria a valer na próxima execução sem publicação e sem teste. Para mudar de comportamento, crie outro agente e vincule a etapa a ele.
• A conversa sobrevive ao recarregamento. O histórico fica guardado por processo, neste navegador. Ele não vai para o servidor, não é compartilhado com outra pessoa e desaparece se você limpar os dados do site — é o raciocínio que você acabou de ter, não um registro de auditoria.

O assistente lê a descrição do processo antes de propor qualquer coisa, e pode propor uma descrição nova ao fim da conversa. A proposta é exibida ao lado do texto atual — a descrição só muda quando você aceita, porque ela não tem histórico de versões para desfazer.

Escopo

O assistente trabalha no escopo em que você está. Editando um Template Global, ele lê e escreve os dados globais; dentro de um tenant, os do tenant. Ele não mistura os dois na mesma conversa.

Lendo o XML de uma versão

Na lista do Catálogo de Processos, cada linha traz Exportar XML, ao lado de Detalhes. O arquivo é baixado com a chave da definição no nome e a extensão do tipo — .bpmn, .cmmn ou .dmn. É o mesmo conteúdo que o modelador carrega quando você abre a versão em Editar / Novo, e é a versão que a lista está exibindo.

O botão exige o mesmo papel do resto da tela: Admin do tenant ou Super Admin. Pela API, o endereço é GET /api/a/definitions/{chave}/versions/{id}/xml.

Exportar e Importar XML formam o par que move um processo entre ambientes: exporte no tenant de homologação, importe no de produção.

Documentação do processo

A aba Documentação, logo depois do Diagrama, guarda um texto em Markdown escrito para pessoas: para que serve o processo, quem são os envolvidos, o que dispara cada caminho, o que fazer quando algo dá errado.

O diagrama mostra a forma do fluxo e não diz nada sobre a intenção. Sem esse texto, quem entra na equipe herda um desenho sem a razão dele.

O editor tem duas abas, Escrever e Pré-visualizar. O texto é salvo na hora e vale imediatamente — não depende de publicar versão nova nem de novo deploy. Documentação muda mais do que diagrama, e exigir um deploy para corrigir uma frase seria a troca errada.

Não confunda com Base de Conhecimento

Esta documentação é lida por pessoas. Ela não é enviada para a IA, não é fatiada em trechos e não é recuperada por busca vetorial. O que alimenta o agente são as Bases de Conhecimento — veja Bases de Conhecimento (RAG) mais abaixo.

Processos vindos de template global

Se o processo veio de um template global, a documentação é escrita pelo Super Admin no painel de Templates Globais e aparece aqui somente para leitura, com uma faixa indicando a origem. Não há editor, e isso é proposital: um processo global também não tem diagrama, agentes nem formulários editáveis pelo tenant. Um texto local que divergisse descreveria um fluxo que ninguém pode alterar.

Se o template ainda não traz documentação, a aba diz isso — em vez de convidar você a escrever algo que não seria salvo.

Quem pode escrever

Apenas Administrador ou Gerente do tenant. Os demais usuários leem. Quem não pode escrever não vê o editor desabilitado: simplesmente não vê editor.

Papéis de processo

Cada processo pode declarar papéis específicos (ex.: Solicitante, Aprovador). Após publicar a definição, você pode visualizar os papéis extraídos automaticamente do arquivo BPMN/CMMN.

Esses papéis são usados para atribuir tarefas às pessoas corretas em cada execução. Membros do tenant com o papel de processo correspondente receberão as tarefas automaticamente.

Template de Business Key

A Business Key é o identificador de negócio da instância — o número da nota, o código do pedido, o que liga a execução ao documento que a originou. Na aba Configurações da definição você define um template com variáveis do processo, por exemplo ${tipoDoc}-${emissao}-${cnpjEmissor}.

Variável ausente não vira chave

Se as variáveis do template não forem enviadas ao iniciar a instância, a instância não é criada: a plataforma responde 422 dizendo quais variáveis do template faltaram.

Recusar na entrada é deliberado. Uma instância que nascesse sem chave rodaria inteira e produziria resultado, e só muito depois se descobriria que não há como referenciá-la — nem responder se aquele documento já foi processado. O erro imediato e legível custa menos que semanas de instâncias órfãs.

A recusa vale para qualquer variável do template que não resolva, não só para o caso de todas faltarem. Uma chave como NFSE--, com só o tipo do documento preenchido, é igual para toda nota daquele tipo — ela colide por construção, e uma chave que colide não é chave.

Duas saídas quando a variável pode legitimamente faltar:

• dê um valor padrão no próprio template: ${cnpjEmissor:-SEM-CNPJ};
• ou envie businessKey diretamente na criação, que dispensa o template.

Definição sem template também ganha chave. A plataforma aplica um padrão embutido, DOC-${date:yyyyMMdd}-${random:4}, e toda instância iniciada sem businessKey explícito nasce com algo como DOC-20260813-A7K2. Não existe instância sem chave por omissão.

Esse padrão nunca cai na recusa acima, porque data e sufixo aleatório sempre resolvem. Ele só não significa nada para o negócio: se você quer uma chave que identifique o documento, declare o template; caso contrário a plataforma garante ao menos um identificador datado.

Política de anexos

Na aba Configurações da definição, abaixo do template de Business Key, você define como os anexos daquele processo se comportam.

Como os anexos chegam

Modo	O que acontece
Ad hoc (padrão)	Além do formulário, quem tiver permissão pode anexar direto pelo painel de anexos da tarefa.
Somente formulário	O arquivo entra exclusivamente por um campo de arquivo do formulário. O painel fica só para leitura.

Somente formulário exige campo de arquivo

Nesse modo, um processo cujo formulário não tem campo de arquivo não aceita anexo nenhum. E como a tela de instância não tem formulário, ela deixa de oferecer qualquer caminho de upload — os arquivos passam a entrar apenas durante o preenchimento de uma tarefa.

Quem pode o quê

Três listas, todas preenchidas com papéis de processo:

• Papéis que podem visualizar — quem pode abrir a pré-visualização e baixar.
• Papéis que podem substituir — quem pode trocar um arquivo por uma versão nova.
• Papéis que podem anexar pelo painel — só aparece no modo Ad hoc.

Lista vazia significa "qualquer pessoa com algum papel neste processo" — não significa "todo mundo". Quem não tem papel nenhum na definição não acessa os anexos dela. Administradores sempre passam por todas as verificações.

Excluir não é uma opção

Não existe exclusão de anexo de processo, para nenhum papel, nem para administradores. Corrigir um arquivo é substituí-lo: o anterior sai da lista e permanece como histórico.

Bases de Conhecimento (RAG)

Na página de detalhes de um processo, você terá acesso à aba Base de Conhecimento. Nela, é possível visualizar todas as bases geradas pelos administradores (KBs Globais ou restritas ao Tenant) e habilitá-las para este processo específico.

Ao fazer essa vinculação explícita (Toggling), qualquer agente de IA que atuar nesse processo passará a ter seu System Prompt retroalimentado com as regras das bases habilitadas. Isso previne que a IA aplique regras do setor financeiro num processo do RH, por exemplo.

A base é do processo; a etapa escolhe dentro dele

O vínculo pertence ao processo, e não ao agente: trocar o agente de uma etapa não muda quais bases estão ao alcance dela.

O que o vínculo define é o conjunto disponível. Cada Service Task escolhe dentro dele pelo campo aiKnowledgeBases, e escolhe também as suas ferramentas — duas etapas do mesmo processo podem enxergar bases diferentes. Veja O que é do agente e o que é da etapa e, sobre dividir o prompt entre mais de um agente, Um agente por domínio.

Etapa que chama um Java Delegate

Nem toda etapa precisa de IA. Quando a regra é determinística — ler um layout conhecido, calcular um dígito verificador, normalizar um documento com formato fixo —, um Java Delegate faz o trabalho de forma exata, sem custo de token e sem risco de o modelo inventar um valor.

No modelador, selecione a Service Task e escolha o delegate no campo delegateExpression. A lista traz os delegates que a plataforma tem carregados naquele momento, com o nome da classe ao lado para desempatar nomes parecidos.

Se o delegate existe no ambiente de destino mas não neste, use Digitar manualmente e escreva a expressão à mão. A lista é o caminho padrão, não uma jaula.

Escolher da lista não é só conveniência

O nome do delegate nem sempre é óbvio: vem do @Component("nome") quando a classe tem a anotação, e do nome simples da classe com inicial minúscula quando não tem. Digitar errado publicaria um processo que aceita trabalho e trava na etapa. Por isso a plataforma também recusa o deploy de um processo que cite delegate inexistente, mesmo que o XML tenha vindo de fora do modelador.

Parâmetros

Um delegate pode declarar parâmetros. Quando declara, os campos aparecem logo abaixo da seleção, já preenchidos com o valor padrão que o autor definiu.

O valor pode ser literal (nfse-v2) ou vir de uma variável do processo, bastando escrevê-la como ${minhaVariavel} — a plataforma reconhece a forma e grava do jeito certo no XML.

Parâmetro marcado como obrigatório e deixado vazio bloqueia o salvamento da definição, nomeando o parâmetro que falta. A checagem acontece no modelador, onde ainda dá para corrigir na hora.

Um parâmetro não guarda segredo: senha, token e chave de API pertencem às variáveis do tenant, pelo motivo em Java Delegates.

Num caso, o delegate é de outro tipo

O motor de casos não executa JavaDelegate. Uma tarefa de serviço dentro de um CMMN precisa de uma classe que implemente PlanItemJavaDelegate (ou PlanItemFutureJavaDelegate); apontar para um JavaDelegate publica um caso que trava na etapa, sem erro no modelador.

Por isso a lista do modelador CMMN mostra apenas os delegates que o motor de casos consegue rodar, e o painel avisa em vermelho quando o caso já aponta para um delegate que só o BPMN executa — situação normal em arquivo escrito à mão ou copiado de um processo.

A seção Tarefa de serviço do painel grava flowable:type="java" junto com a implementação escolhida. Sem esse atributo o Flowable ignora a tarefa inteira, e era exatamente o que acontecia com quem editava o XML à mão e esquecia dele.

A própria plataforma traz um delegate de caso: o da etapa de IA. Escolha ✨ Agente de IA na implementação e o painel passa a pedir agente, instrução, variável de retorno, ferramentas e bases — os mesmos campos do modelador BPMN. Ele não aparece na lista de delegates porque essa lista mostra o que este tenant enviou, e a etapa de IA é da plataforma. Veja Agentes de IA.

Quando o delegate muda

Se você trocar o delegate selecionado, os parâmetros de mesmo nome são preservados e os demais ficam marcados como desconhecidos, em vez de desaparecerem. O mesmo vale para uma expressão que aponta para um delegate que não está carregado neste ambiente: ela continua ali, sinalizada — apagar seria descartar em silêncio uma decisão que alguém tomou de propósito.

Autoaprendizado

Um processo publicado aprende com o próprio histórico: a plataforma conta o que foi decidido em cada campo, em situações comparáveis, e usa essa contagem para sugerir o preenchimento das próximas tarefas. Isso é configurado na aba Autoaprendizado da definição.

Como Funciona

Uma vez por dia, a plataforma percorre o histórico de tarefas concluídas e conta, campo a campo, o que foi decidido em situações comparáveis. É daí que saem as sugestões com índice de confiança e a explicação "34 de 38 casos". Não passa por IA: são contagens sobre decisões reais. O detalhe do funcionamento está em Autocompletar Inteligente.

Quando o usuário pede sugestões numa tarefa, os campos com padrão qualificado são preenchidos pela contagem, sem chamar IA nenhuma. A camada 2 é oferecida, com um botão para aplicar e a etiqueta Caso anterior ao lado.

A sugestão é montada em duas camadas, e cada uma só é alcançada quando a de cima não tem resposta para aquele campo:

1. Contagem — campos de escolha (seleção, rádio, checkbox, booleano, lookup, avaliação) e também áreas de texto que se repetem. Se um campo de texto longo tem poucos valores distintos no período, ele é um texto-modelo, não prosa, e entra na contagem normalmente. Custa zero.
2. Caso anterior — para campo de texto sem padrão qualificado, a plataforma devolve o valor passado mais frequente naquele mesmo contexto, literal, para você editar. Também custa zero, e é rastreável: dá para dizer de quantos casos anteriores ele veio. Contar frequência só significa alguma coisa sobre categorias — um parecer diferente a cada documento aparece uma vez só, então sua confiança seria sempre baixa demais para virar sugestão.

O autopreenchimento não chama IA nenhuma

As duas camadas são contagem sobre decisões reais, então o Autopreencher não consome cota de IA. Se um campo de texto genuinamente único não tiver caso anterior parecido, ele simplesmente não recebe sugestão, em vez de receber uma sugestão gerada.

Ficam fora dos dois caminhos, sempre:

• Campos pessoais por tipo declarado — CPF, CNPJ, CEP, e-mail e telefone. Vale o tipo escolhido no construtor de formulários, não o nome do campo: um campo chamado solicitante declarado como texto continua protegido se você declará-lo corretamente, e um nomeDoProduto declarado como seleção é aprendido normalmente.
• Anexos e elementos visuais — arquivo, título, separador e visualizador de markdown não carregam valor sugerível.
• Variáveis internas da plataforma — as que começam com _ ou ai_, além de tenantId.

Campos numéricos, monetários e de data não viram sugestão, mas continuam servindo de condição ("quando o tipo de documento for X..."). Variáveis que o processo cria por fora do formulário seguem a mesma regra: nunca são sugeridas, porque não existem na tela do usuário, mas podem condicionar.

Nada disso vai para a IA também: o campo excluído é removido do que o modelo enxerga, não mascarado.

Não há uma tela onde se escolha o que aprender: quem decide é o tipo escolhido ao montar o formulário.

Tipo do campo	Entra no aprendizado
Escolha, rádio, checkbox, booleano, lookup, avaliação	Sempre
Texto de uma linha	Enquanto o valor tiver até 512 caracteres
Área de texto	Só com até 20 valores distintos no período; acima disso é prosa
Data, número, moeda	Nunca viram sugestão; só condicionam com até 20 valores distintos
CPF, CNPJ, CEP, e-mail, telefone, senha	Nunca — removidos do que o modelo enxerga
Arquivo, título, separador, visualizador de markdown	Nunca — não carregam valor sugerível

Se um campo deveria ser aprendido e não está, o mais provável é que ele esteja declarado como texto livre quando deveria ser uma seleção.

Nome de pessoa e endereço não são protegidos por tipo

A proteção automática da última linha vale por tipo declarado, e não existe tipo "nome de pessoa" nem "endereço" no construtor de formulários — um campo nomeCompleto ou enderecoEntrega declarado como texto é aprendido normalmente.

Para esses, use Campos excluídos do aprendizado. É a única proteção que funciona.

Há uma exceção parcial que não deve ser confundida com garantia: campos que o formulário não declara — as variáveis que o processo cria por fora da tela — passam por uma verificação pelo nome (nome, endereco, nascimento, rg, idade e outros). Isso pega alguns casos e erra nos dois sentidos, e a verificação nunca é consultada para um campo que o formulário declara.

Para excluir um campo específico, liste o nome dele em Campos excluídos do aprendizado, separando por vírgula. É uma lista de exclusão: tudo o mais continua sendo aprendido, e campo novo no formulário passa a ser aprendido sozinho. Ela não reabilita o que já é excluído por tipo — um campo CPF continua fora mesmo que você não o liste.

Não existe gatilho por lote. A micro-análise não dispara ao acumular N tarefas concluídas: contar conclusões pula ou dispara duas vezes quando duas pessoas concluem ao mesmo tempo, e o contador não teria como zerar de forma confiável. Tudo acontece na execução diária.

Os campos da aba

A aba Autoaprendizado fica na própria definição do processo, ao lado das outras. O formulário do Agente de IA não tem nenhum campo de aprendizado — procurar por lá é procurar onde não existe.

A consequência prática vale registrar: um processo com vários agentes tem uma só configuração de aprendizado, válida para todos eles. Trocar o agente de uma etapa não muda o que aquele processo aprende, nem separa o aprendizado por especialidade.

Os campos da tela:

• Autoaprendizado Ativo: Habilita ou desabilita o aprendizado das tarefas. Desligado, a contagem de padrões não é atualizada e nenhuma sugestão nova aparece.
• Janela Temporal (Meses): Quantos meses de histórico recente entram na conta (padrão: 3). Serve para o processo esquecer decisões obsoletas quando a regra de negócio muda.
• Campos excluídos do aprendizado: Lista de nomes de campos, separados por vírgula, que este processo não deve aprender nem enviar à IA. É uma lista de bloqueio: todo o resto continua sendo aprendido, e um campo acrescentado ao formulário depois passa a ser aprendido sozinho. Ela não reabilita o que já está excluído por tipo — um campo de CPF fica de fora esteja ele listado ou não.

Cada processo publicado tem a sua configuração, e ela vale só para ele. Desligar o aprendizado de um processo não afeta os demais.

Saúde do aprendizado

Abaixo da configuração, na mesma aba, fica a tabela Saúde do aprendizado: cada padrão em uso, com a confiança que ele afirma e a taxa com que os usuários realmente o aceitaram, lado a lado.

Ler as duas colunas juntas é o ponto. Confiança é o que o histórico diz; aceitação é o que as pessoas fizeram quando viram a sugestão. Enquanto as duas andam próximas, o padrão continua valendo. Quando a aceitação despenca e a confiança permanece alta, quase sempre a regra de negócio mudou e o histórico ainda não percebeu — esses padrões aparecem destacados e no topo.

Uma linha só recebe veredicto depois de dez exposições. Antes disso ela mostra "dados insuficientes", porque um padrão recusado duas vezes não é um padrão ruim.

O rodapé informa quantas sugestões foram retidas de propósito (o sorteio explicado em Autocompletar Inteligente). Essa retenção é o que mantém a coluna de confiança confiável: sem pessoas decidindo sem ver sugestão, não haveria com o que comparar.