Variáveis e segredos (Variáveis de Tenant)

Nível de acesso requerido

• Variáveis de processo (aba Variáveis da definição): Admin, Modelador ou Super Admin.
• Variáveis e segredos da empresa (menu Administração → Variáveis e segredos): Admin ou Super Admin.

Esta página cobre os dois lugares onde se guarda uma variável: a aba Variáveis de cada processo e o item de menu Administração → Variáveis e segredos, que guarda o que vale para a empresa inteira.

As Variáveis de Tenant guardam chaves e valores estáticos que a plataforma injeta como variáveis de processo toda vez que uma instância é iniciada. Elas pertencem a um processo de cada vez: cada variável é gravada junto com a chave do processo a que pertence, e a mesma chave — taxa_cambio, por exemplo — pode existir com valores diferentes em processos diferentes.

A variável de processo não vale para o Tenant inteiro

A variável cadastrada num processo vale para aquele processo: ela é armazenada com a chave dele, e a plataforma só a carrega ao iniciar uma instância daquele processo. Se cinco processos precisam do "E-mail do SAC", o valor tem de ser cadastrado nos cinco — o que você cadastrou no processo A simplesmente não existe para o processo B.

O que é da empresa inteira — a senha de uma caixa IMAP, o token de um ERP que vários robôs usam — vai em Variáveis e segredos, descrito logo abaixo.

Variáveis e segredos da empresa (fora de processo)

Uma caixa de entrada e um robô não são processos, mas precisam de credencial: a senha do IMAP, o token do ERP. Para isso existe a tela Administração → Variáveis e segredos (endereço /admin/variables), que guarda variáveis do Tenant inteiro, sem processo nenhum.

1. Acesse Administração → Variáveis e segredos e clique em Nova variável.
2. Informe a chave — começa com letra ou _ e usa só letras, números, _, . e -. É ela que vai dentro de ${var.chave}.
3. Escolha o tipo, informe o valor e ligue Secreta quando for senha ou token.
4. Salve. A partir daí a caixa de entrada ou o robô aponta para ela com ${var.chave}.

Um segredo nunca mais aparece depois de salvo. A lista mostra ********, a resposta da API também, e ao editar o campo de valor vem vazio: deixe em branco para manter o valor guardado, ou digite um novo para trocar. O valor é gravado cifrado no banco.

Criar não sobrescreve. Criar uma variável com uma chave que já existe é recusado nomeando a chave — para trocar o valor, use Editar na linha dela. Antes, criar com a chave de um segredo existente trocava o valor dele em silêncio.

Os campos de senha da caixa de entrada e os parâmetros secretos dos robôs mostram o botão Criar variável só quando a variável apontada ainda não existe. Ele abre a mesma janela de criação por cima da tela em que você está, com a chave da referência preenchida e Secreta ligada, e não perde o que você estava editando.

Se a lista não carregar, a tela mostra o erro — e não "nenhuma variável ainda", que daria a impressão de que elas sumiram.

A referência é conferida ao salvar

Ao salvar uma caixa de entrada ou os parâmetros de um robô, a plataforma confere se cada ${var.chave} existe. Se não existe, o salvamento é recusado com uma mensagem que diz qual variável falta e manda você para Variáveis e segredos — o erro aparece na hora, e não na próxima leitura da caixa ou na próxima execução de madrugada.

Guardar no cofre em vez de guardar o valor

Quando a instalação tem um cofre ligado (ver Cofre externo), uma variável secreta ganha a escolha Valor guardado / Referência ao cofre. Em Referência ao cofre você digita onde o segredo mora, por exemplo vault://kv/flowi/tenants/<seu-tenant>/erp#password, e a plataforma lê o valor no cofre no momento do uso — o banco guarda só a referência.

• A lista mostra a referência com a etiqueta Cofre; o valor nunca aparece.
• Ao salvar, a plataforma busca a referência uma vez para conferir: se ela não existe no cofre, ou se aponta para fora do prefixo do seu Tenant, o salvamento é recusado nomeando a referência. Se o cofre estiver fora do ar nesse momento, a variável é salva assim mesmo e conferida no primeiro uso.
• Referência só vale em variável marcada Secreta, e tem no máximo 900 caracteres.
• Um segredo guardado como referência nunca é copiado para dentro da instância, mesmo com a injeção de segredos ligada: use ${secrets.get(execution, 'chave')}, {{secret:chave}} ou ${var.chave}.
• Sem cofre ligado a escolha não aparece, e um valor que começa com vault:// é recusado ao salvar.

Quem vence quando a mesma chave existe nos dois lugares

• Dentro de um processo, a variável do processo vence. Um processo que define a própria apiKey usa a dele; um processo que não define cai na apiKey da empresa — mas só pela leitura de segredo (${secrets.get(execution, 'apiKey')} e {{secret:apiKey}}). A variável da empresa não é copiada para dentro das instâncias, para não espalhar a senha do IMAP por todo processo que roda.
• Caixa de entrada e robô usam primeiro a variável da empresa. Se ela não existe, valem as variáveis cadastradas dentro de processos, como antes: uma única com aquela chave resolve; duas com valores diferentes são recusadas, nomeando os processos.

Quem administra a tela é o Admin do Tenant, e o Super Admin com o Tenant selecionado. O Modelador não a vê: credencial da empresa é administração, não desenho de processo.

Para que servem?

Imagine um processo de faturamento que depende do "E-mail do SAC" ou da "Taxa de Câmbio Padrão". Em vez de cravar esse valor no diagrama BPMN — o que obriga a publicar uma versão nova do processo toda vez que ele muda —, crie uma variável email_sac ou taxa_cambio na configuração daquele processo.

Se a taxa mudar amanhã, você altera o valor na tela e as novas instâncias já nascem com ele, sem republicar nada. As instâncias em andamento mantêm o valor que receberam: a variável é copiada para dentro da instância no momento do start, não relida a cada etapa.

Gerenciando Variáveis

As variáveis moram dentro do processo, e não num item próprio de menu. Quem reúne a configuração de um processo é Catálogo de Processos, e é de lá que se chega a tudo: variáveis, template de business key, política de anexos, bases de conhecimento, agentes e autoaprendizado.

1. Acesse Desenho de processos → Catálogo de Processos e abra o processo desejado.
2. Vá até a aba Variáveis.
3. Informe um identificador único dentro daquele processo (sem espaços, preferencialmente snake_case) e o valor.
4. Escolha o tipo (STRING, INTEGER, DECIMAL, BOOLEAN, DATE) — ele determina como o valor chega ao processo: um INTEGER entra como número, não como texto.
5. Marque Secreto quando o valor não deve aparecer na tela nem ser devolvido pela API pública que pré-preenche formulários.

Variáveis secretas e os agentes de IA

Uma variável marcada como Secreta não chega ao agente de IA como valor. No prompt do agente, um {{minha_chave}} que aponta para uma variável secreta é renderizado como {{secret:minha_chave}} — o agente vê o nome, nunca o conteúdo.

Para usar a credencial numa chamada de API, o agente escreve o mesmo identificador na ferramenta de requisição HTTP, por exemplo no cabeçalho:

Authorization: Bearer {{secret:minha_chave}}

A plataforma substitui pelo valor real no último instante, já saindo para a rede. O valor não entra no prompt, não é enviado ao provedor do modelo, não fica no histórico da conversa e não aparece no log — que registra o método, a URL, os nomes dos cabeçalhos e o tamanho do corpo.

Escreva o prompt com o nome, não com o valor: um prompt que diz "autentique com {{minha_chave}}" funciona — a chamada é feita, a credencial chega ao destino, e o modelo em nenhum momento vê o valor.

Nas telas, a variável secreta é exibida como ******** também na instância e na tarefa, e não só na tela de variáveis. Quem abre a instância enxerga que a variável existe, nunca o seu conteúdo.

O que isso não protege

O agente só alcança os hosts que o agente dele declarar — veja Até onde o agente pode chamar em Agentes de IA. Sem lista declarada, o comportamento depende da política da instalação (AI_HTTP_TOOL_DEFAULT_POLICY), e endereço interno da rede é sempre bloqueado.

O segredo do app do Microsoft 365

A conexão que sincroniza bases de conhecimento com SharePoint e OneDrive (veja Bases de Conhecimento) não tem campo de segredo. O segredo do app registrado no Entra fica numa variável secreta do escopo da empresa — o valor, ou uma referência vault:// —, e a conexão só guarda o nome dela. Trocar o segredo é trocar o valor desta variável; a conexão passa a usá-lo no próximo token.

A credencial de uma base de conhecimento externa

Uma base externa (Elasticsearch ou OpenSearch) autentica com uma variável secreta da empresa — a lista de variáveis fora de processo. Crie a variável aqui (o valor pode ser uma referência de cofre) e, na base, escolha o nome dela: nenhum campo da base aceita o valor. Para chave de API, guarde a chave codificada que o Elasticsearch mostra; para usuário e senha, guarde usuário:senha. A plataforma lê o segredo a cada consulta, no tenant da busca, e ele só existe no cabeçalho da requisição — não vai ao log, à resposta da API, ao prompt nem à auditoria.

Usando um segredo numa expressão do processo

Uma variável secreta pode ser lida no momento do uso, sem ser copiada para dentro da instância:

${secrets.get(execution, 'minha_chave')}

O valor é buscado na hora, usado, e não fica gravado em lugar nenhum — nem nas variáveis da instância, nem no histórico.

A cópia para dentro da instância, e como desligá-la

Por compatibilidade, variáveis secretas também são copiadas para as variáveis da instância no início do processo — e o Flowable grava variável de instância em texto claro, inclusive no histórico, que sobrevive ao término.

Uma instalação nova deve subir com SECRETS_INJECT_INTO_PROCESS_VARIABLES=false. Aí o segredo não entra na instância, e as expressões precisam usar a forma acima. Cada variável não injetada é registrada no log pelo nome, para você enxergar o que ficou de fora.

Uso nos Processos

A variável entra na instância com o nome puro, exatamente como você a cadastrou. Para uma variável chamada minha_variavel, a expressão no BPMN é:

${minha_variavel}

${tenant.minha_variavel} não resolve

Use sempre o nome puro. A plataforma não cria nenhum objeto chamado tenant no escopo do processo, então ${tenant.minha_variavel} não devolve o valor da variável — ela falha ou chega vazia ao seu fluxo, e o diagrama é publicado sem reclamar.

Se algum ponto do seu BPMN usa o prefixo, troque ${tenant.x} por ${x} em todos eles.