Templates Globais

Nível de acesso requerido

Super Admin

O módulo de Templates Globais permite que o Super Admin configure elementos que serão compartilhados e reutilizados por todos os Tenants da plataforma.

Isso garante a padronização e escalabilidade do sistema. Ao alterar um template global, as atualizações são refletidas em processos correspondentes em todos os ambientes.

Elementos Globais

A plataforma atualmente suporta os seguintes elementos no nível global:

1. Definições de Processos Globais

Processos BPMN e Casos CMMN que não pertencem a um tenant específico. Estes modelos de processos servem como base e podem ser instanciados dentro do contexto de qualquer tenant.

TIP

Ao criar um novo template global, o upload do arquivo XML (.bpmn ou .cmmn) é opcional. Se nenhum arquivo for fornecido, a plataforma gera automaticamente um esquema padrão válido baseado no tipo selecionado.

2. Tipos Documentais Globais

Para formulários e processos que exigem upload de documentos, você pode criar Tipos Documentais globais (ex: "RG", "Comprovante de Residência", "Contrato de Prestação de Serviço"). Ao gerenciar tipos documentais nesta área:

• O sistema vincula o tipo ao processo global.
• O Tipo Documental fica disponível para os formulários que usam esse template.

3. Anexos Globais

Os modelos de documentos (arquivos físicos, templates de contratos e relatórios) atrelados a processos globais não ficam amarrados ao tenant tenantId. Em vez disso, o sistema utiliza uma flag is_global e armazena os arquivos fisicamente na pasta global/ no provedor de armazenamento (S3, disco local, etc). Isso garante isolamento e evita vazamento de dados de tenants para diretórios públicos.

4. Variáveis e Formulários Globais

As variáveis configuradas no contexto dos Templates Globais formam o vocabulário base de dados para formulários (ex: SmartDocs e FlowableForms) usados através da plataforma para um processo específico.

5. Agentes de IA Globais

Um template global carrega os próprios agentes de IA, na aba Agentes de IA. É o mesmo cadastro da tela do tenant — nome, descrição, system prompt, modelo, temperatura e as ferramentas que o agente pode usar — só que preso ao processo global em vez de a um tenant.

Existe para eliminar duplicação. Sem isso, um template global cujo BPMN aponta para um agente obrigaria cada tenant inscrito a recadastrar o mesmo agente, com o mesmo prompt, um por um — e qualquer ajuste de prompt teria de ser repetido em todos.

Como a etapa de IA encontra o agente, em tempo de execução. O BPMN aponta um agentId. A plataforma procura primeiro no tenant que está executando; não achando, procura na camada global. Se não achar em nenhuma das duas, a etapa falha dizendo qual id não existe.

É busca em cascata por id, não união. A consequência prática importa:

O agente global não aparece na lista do tenant

A tela de agentes do tenant mostra apenas os agentes daquele tenant. Um agente global executa para o tenant inscrito, mas não é listado ali — diferente das Bases de Conhecimento globais, que aparecem marcadas como Global e somente leitura.

Então, se um processo global usa IA e o administrador do tenant abre a aba de agentes e não vê nada, isso não quer dizer que não há agente: quer dizer que o agente é da plataforma. Quem edita esse agente é o Super Admin, aqui.

Quem pode mexer: só o Super Admin. Os endpoints ficam sob /api/admin/global-templates/{processKey}/ai-agents e exigem SUPER_ADMIN; a tela do tenant não oferece a opção de marcar um agente como global — a mesma separação que vale para as bases de conhecimento.

O que o agente global carrega junto. As regras de alcance continuam valendo para ele como para qualquer agente: os hosts que ele pode chamar são declarados no próprio agente, e o segredo que ele usa nunca é exibido a ele (ver Agentes). Ser global amplia quem o executa, não o que ele alcança.

Nível dos documentos das bases globais. O nível de cada documento de uma base global (Público, Secreto, Ultrassecreto) é definido pelo Super Admin e vale para todo tenant inscrito: a busca do tenant aplica o nível da plataforma, e a tela do tenant mostra os níveis sem permitir alterá-los. Um tenant que queira um documento mais restrito não vincula a base, ou copia o documento para uma base própria. Veja Quem pode ler cada documento.

6. Documentação Global do Processo

Cada template global carrega sua própria documentação em Markdown — o texto que explica o processo para quem vai operá-lo. Ela é escrita aqui, na aba Documentação, com editor Escrever | Pré-visualizar.

Todo tenant inscrito no template lê esse mesmo texto na aba Documentação da definição, sem poder editá-lo, com uma faixa indicando que veio do template global. É o mesmo princípio dos demais elementos globais: o tenant herda, não bifurca. Alterar o texto aqui alcança todos os inscritos na hora, sem republicar o processo.

Inscrevendo um tenant no template

Um template global é um pacote: além do BPMN/CMMN, ele carrega tabelas de decisão (DMN), formulários, papéis e documentação. Inscrever um tenant instala o pacote inteiro no ambiente dele.

A instalação é tudo ou nada

Se qualquer tabela de decisão vinculada não puder ser implantada — XML inválido, chave duplicada, hit policy incorreta —, a inscrição é recusada e a mensagem de erro nomeia cada tabela que ficou de fora. Nenhuma assinatura é gravada: o tenant não aparece como inscrito na versão do template.

Isso é proposital. Antes, a inscrição respondia sucesso e mostrava o tenant inscrito na versão do template mesmo sem a tabela de decisão existir no motor — e a falha só aparecia semanas depois, quando a primeira instância chegava à tarefa de regra de negócio. Corrija o DMN no template e inscreva o tenant de novo.

O template passa pelas mesmas travas de uma publicação

Antes de instalar, a plataforma confere o processo como se o próprio tenant o estivesse publicando: cada etapa de agente precisa declarar o que grava e o que consulta, e nenhum agente pode depender de um modelo aposentado sem substituto. A conferência é feita no tenant que recebe — um mesmo template pode entrar num tenant e ser recusado em outro, se o agente ou o modelo resolvido for diferente. Na recusa, a mensagem nomeia o template, o tenant e o motivo, e nada é implantado. No auto-provisionamento de um tenant novo, a recusa aparece como a linha daquele template no erro do tenant.

Quando a inscrição é aceita, a lista de assinaturas mostra a versão implantada, e essa versão vale para o pacote completo.

Como Gerenciar

1. Navegue até Catálogo global → Templates Globais na barra lateral.
2. Selecione o Processo desejado.
3. Utilize as abas para gerenciar:
   • Geral: Definições base do processo.
   • BPMN/CMMN: Visualizador do diagrama do modelo (se aplicável).
   • Tipos Documentais: Criar, editar, ativar ou suspender tipos de documentos necessários nesse processo.
   • Variáveis: Definir os campos de dados e tipagens esperadas pelos formulários globais.
   • Base de Conhecimento: Documentos que servem de contexto para os Agentes de IA globais deste template.
   • Agentes de IA: Cadastrar e editar os agentes que os tenants inscritos vão executar sem precisar recadastrá-los.
   • Documentação: Escrever, em Markdown, o texto que todos os tenants inscritos vão ler sobre esse processo.

O botão Editor Visual abre o modelador sobre o diagrama do template. Ao salvar, o modelador só fecha depois que o servidor confirma a gravação. Se o salvamento for recusado, ele continua aberto com o diagrama que você desenhou e mostra o motivo sob a barra superior, em Não foi possível publicar — corrija e salve de novo, sem perder o desenho.

TIP

Somente o perfil Super Admin consegue gerenciar recursos globais — os grupos Plataforma e Catálogo global da barra lateral não existem para os demais. Usuários com perfil Admin (tenant) gerenciam apenas seus processos locais, através do menu Desenho de processos → Catálogo de Processos.