Templates e Linhas de Produto

Templates são a forma de criar produtos de BI auto-contidos que podem ser replicados para múltiplos tenants. Eles permitem padronizar, distribuir e atualizar soluções completas de Business Intelligence.

TIP

Templates são ideais para clientes whitelabel que precisam escalar um BI embarcado para dezenas ou centenas de clientes finais.

📦 O que é um Template?

Um Template é um "snapshot" completo de um ambiente de BI. Ao criar um template, você seleciona as Mesas de Aplicações que deseja empacotar.

Empacotamento Inteligente

O sistema identifica automaticamente todas as dependências a partir das aplicações selecionadas:

1. Aplicações → O ponto de partida: Dashboards, Widgets, filtros, expressões e configurações de IA
2. Tabelas → Identificadas a partir das aplicações que as utilizam
3. Dataflows → Derivados das tabelas necessárias, incluindo relacionamentos entre fluxos para tratamento em camadas
4. Agendamentos → Gatilhos de execução vinculados aos Dataflows
5. Variáveis Globais → Parâmetros configuráveis usados pelos Dataflows
6. Credenciais → Referências a conexões de banco (sem dados sensíveis)

NOTE

Tabelas que não são utilizadas por nenhuma aplicação não entram no template. O sistema empacota apenas o que é efetivamente necessário para o funcionamento das aplicações selecionadas.

WARNING

Dataflows seguem as tabelas. Um Dataflow só é empacotado se produzir uma tabela que é usada por alguma aplicação de uma mesa selecionada. Um Dataflow novo "solto" (que ainda não alimenta uma tabela em uso por um dashboard) não entra no template, mesmo que tenha sido criado e validado.

Se um Dataflow precisa ir junto, garanta que a tabela que ele gera seja efetivamente consumida por uma aplicação dentro de uma das mesas selecionadas.

NOTE

Cadastros viajam no template — estrutura, sem dados. Quando um Cadastro de uma mesa selecionada faz parte do template, vão junto seus campos, validações e referências (chaves externas). Os registros (dados) não são empacotados: cada tenant começa com o Cadastro vazio, pronto para ser preenchido.

---

🔄 Ciclo de Vida do Template

1. Criação

Templates são criados a partir de um tenant de desenvolvimento (também chamado de "tenant base"):

1. Desenvolva suas aplicações, Dataflows e tabelas no tenant de desenvolvimento
2. Teste e valide todo o conteúdo
3. Acesse HEC → Templates e clique em Criar novo Template
4. Selecione as mesas que farão parte do template
5. Dê um nome e descrição ao template

NOTE

O template captura o estado atual do conteúdo. Alterações posteriores no tenant de desenvolvimento não afetam templates já criados.

2. Instalação

Templates podem ser instalados em novos tenants de duas formas:

Durante a criação do tenant:

• Ao criar um novo tenant, você pode selecionar um template
• As variáveis globais do template serão solicitadas neste momento
• Isso permite criar templates parametrizáveis (URL de API, chave de integração)

Em tenants existentes:

• Acesse a edição do tenant
• Na aba HEC → Templates, clique em Instalar Template
• Selecione o template e configure as variáveis

3. Atualização

Quando você precisa atualizar um template:

1. Faça as alterações necessárias no tenant de desenvolvimento
2. Em HEC → Templates, localize o template existente
3. Clique em Atualizar para criar uma nova versão
4. A nova versão pode ser aplicada aos tenants instalados

---

4. Espelhar Template (Estado Canônico)

Por padrão, aplicar um template (instalar ou atualizar) é uma operação aditiva: cria e atualiza o que o template define, mas nunca remove nada do tenant. Com o tempo isso faz o tenant acumular conteúdo que não pertence mais ao template — linhas de produto descontinuadas, forks órfãos, restos de templates antigos.

A opção Espelhar template, disponível na hora de aplicar, resolve isso: além do apply aditivo de sempre, ela executa uma fase de poda, removendo do tenant o conteúdo de produto que não existe no template — deixando o tenant em estado canônico, um espelho exato do que o template define.

NOTE

Espelhar é desativado por padrão. Sem marcar a opção, o apply continua exatamente aditivo, como sempre foi.

O que é espelhado

Estes recursos são conteúdo de produto: o que casa por nome (e Mesa) com o template é mantido/atualizado normalmente; o que não casa é removido.

Recurso	Quando é removido
Aplicações	Não existe Aplicação de mesmo nome, na mesma Mesa, no template
Tabelas (exceto Cadastros)	Não existe Tabela de mesmo nome, na mesma Mesa, no template
Dataflows	Não existe Dataflow de mesmo nome, na mesma Mesa, no template
Mesas (de Aplicação e de Dados)	Ficou vazia depois que os itens acima foram removidos

O que é sempre preservado

O estado pessoal/operacional do tenant nunca é alvo da poda — só desaparece em cascata, se o recurso ao qual pertence for removido:

• Credenciais de conexão
• Variáveis do tenant
• Cadastros — a estrutura (campos, validações) pode vir do template, mas os dados digitados pelo tenant nunca são tocados
• Permissões e grants (grupos de usuário, acesso a Mesas)
• Alertas configurados pelos usuários (com uma exceção — veja abaixo)
• Bookmarks
• Dashboards pessoais

Cascata: Agendamentos e Datamarts órfãos

Agendamentos e Datamarts não são avaliados por nome — eles seguem o destino do que referenciam:

• Um Agendamento só é removido quando todos os Dataflows que ele dispara foram podados. Se restar pelo menos um Dataflow vivo, o agendamento continua valendo.
• Um Datamart só é removido quando nenhuma das Tabelas que ele expõe sobreviveu. Basta uma Tabela sobrevivente para o Datamart ser mantido.

TIP

Tags de Dataflow seguem o Dataflow (somem se ele for podado); a definição da tag em si permanece disponível para uso futuro.

Exceção: Alertas de uma Aplicação removida

Alertas são, em regra, estado pessoal preservado. A exceção: quando uma Aplicação inteira é podada (por não existir no template), os Alertas vinculados a ela são removidos junto — um Alerta é um job ativo, e deixá-lo apontando para uma Aplicação inexistente geraria disparos com erro.

Bookmarks e Dashboards pessoais da mesma Aplicação não seguem essa regra: ficam preservados como estado inerte e voltam a funcionar normalmente se a Aplicação for restaurada do Arquivo.

Preview obrigatório

Antes de confirmar um apply com Espelhar ativado, o sistema sempre mostra um preview com o que será removido (por tipo e nome), para revisão antes de confirmar.

CAUTION

O preview é uma estimativa conservadora. Ele pode listar Mesas, Agendamentos ou Datamarts como candidatos à remoção mesmo quando, depois que o próprio apply recriar o conteúdo do template, esses recursos acabem sobrevivendo de fato. Ou seja: o preview pode superestimar o que será removido, mas nunca esconde uma remoção real — revise sempre antes de confirmar.

Recuperação

Toda remoção feita por Espelhar é uma exclusão reversível (soft-delete), seguindo as mesmas regras de qualquer exclusão no Horus — sem apagamento físico dos dados. Aplicações, Dataflows e Tabelas removidos aparecem no Arquivo e podem ser restaurados em até 90 dias.

Interação com Fork e Customizações

O fluxo de Fork cria os ativos customizados em uma Mesa "Customizações" separada, propositalmente fora do template. Por não pertencer ao template, essa Mesa é podada quando você espelha — é o mesmo "preço da segurança" que o fluxo de Fork já assume: o template nunca toca uma customização para atualizá-la, mas também não a reconhece como própria. Por isso o preview e a recuperação via Arquivo existem: revise o que será removido antes de confirmar.

Mesas protegidas e tenants com múltiplos templates

A opção "Proteger mesas criadas via templates" bloqueia apenas a edição manual do usuário — ela não isenta uma Mesa da poda do Espelhar. Mesas do template continuam casando por nome e sobrevivem normalmente; uma Mesa protegida que não pertence ao template sendo aplicado (por exemplo, de uma linha de produto antiga, ou de outro template instalado no mesmo tenant) é podada como qualquer outra Mesa fora do template.

Se o tenant tem mais de um template instalado, Espelhar remove o conteúdo de produto que não pertence ao template que está sendo aplicado, mesmo que pertença a outra linha de produto também instalada ali. É um comportamento proposital — e, como qualquer remoção, aparece no preview antes de confirmar.

---

🛡️ Governança e Customização

Um dos maiores desafios em produtos de dados em escala é: como entregar um produto padrão (Template) e ainda permitir customizações para clientes específicos?

A solução do HEC combina dois conceitos: Mesas Protegidas (Segurança) e Fork (Operação).

1. Mesas Protegidas

O sistema permite proteger os ativos instalados pelo template para que ninguém os edite acidentalmente.

• Aviso: Se a opção "Proteger mesas criadas via templates" estiver ativa, as mesas do template ficam bloqueadas para edição/exclusão
• Objetivo: Garantir que o cliente final não "quebre" o produto padrão e que futuras atualizações funcionem sem conflitos

2. A Solução: Fork (Clonar e Renomear)

Como as mesas oficiais estão bloqueadas (ou devem ser tratadas como tal), a única forma de customizar é clonar o ativo.

Sempre que precisar customizar um Dashboard, tabela ou ativo padrão do produto, siga este fluxo:

1. Acesse o ambiente do cliente.
2. Localize o ativo padrão (Dataflow Fato_Vendas ou Aplicação Sales Dashboard).
3. Utilize a função Clonar para Minha Mesa.
4. Renomeie o clone para algo único (Fato_Vendas_Custom ou Sales Dashboard (Custom)).
5. Publique este novo ativo em uma Mesa Customizada (uma mesa que não pertence ao template, "Customizações").

TIP

Por que isso funciona?

• O Template gerencia os ativos originais (protegidos). Quando você lançar a V2, o Fato_Vendas será atualizado automaticamente.
• O seu Fato_Vendas_Custom é um ativo independente ("órfão") e não será tocado pela atualização, preservando a customização do cliente.

Exemplo Prático: Adicionar campo novo

Cenário: Você precisa adicionar uma coluna Regra_X na tabela de Vendas apenas para o Cliente A.

1. Clone o Dataflow: Clone o Fato_Vendas original para sua mesa.
2. Edite: Adicione a coluna Regra_X no novo flow.
3. Renomeie: Salve como Fato_Vendas_Custom.
4. Publique: Publique na mesa "Customizações".
5. Clone a Aplicação: Se precisar mostrar esse dado, clone também a Aplicação de Vendas.
6. Re-vincule: Na nova aplicação, aponte os gráficos para usarem a tabela gerada pelo Fato_Vendas_Custom.

Isso cria uma redundância deliberada (o dado original e o customizado coexistem), que é o preço da segurança de atualização.

---

⚙️ Variáveis Globais

Templates podem ser parametrizáveis através de variáveis globais. Isso permite criar templates genéricos que se adaptam a diferentes clientes.

Exemplos de uso

Variável	Uso
URL_API	Endpoint da API do cliente
CHAVE_INTEGRACAO	Token de autenticação
CNPJ_EMPRESA	Identificador para filtro de select

Como configurar

1. No tenant de desenvolvimento, acesse ETL → Edição de Dataflows → Variáveis Globais
2. Crie as variáveis necessárias (valores não serão levados para o template)
3. Ao criar o template, as variáveis são incluídas automaticamente
4. Durante a instalação em um novo tenant, o usuário informará os valores específicos

---

📊 Linhas de Produto

Conforme você cria múltiplas versões de templates, fica difícil gerenciar qual é a versão vigente e quais tenants estão desatualizados. Linhas de Produto resolvem esse problema.

O que são Linhas de Produto

Uma Linha de Produto agrupa templates relacionados, permitindo:

• Versionamento: Definir qual versão é a "vigente" (atual)
• Histórico: Manter versões anteriores como "descontinuadas"
• Changelog: Documentar mudanças entre versões
• Visualização: Ver rapidamente quais tenants estão desatualizados
• Migração em lote: Atualizar múltiplos tenants de uma vez

Criando uma Linha de Produto

1. Acesse HEC → Templates
2. Clique em Criar Linha de Produto
3. Dê um nome ("Pacote Financeiro", "Módulo RH")
4. Vincule templates existentes à linha

Gerenciando Versões

Na tela de detalhes da Linha de Produto:

• Template Vigente: A versão recomendada para novas instalações
• Templates Descontinuados: Versões antigas mantidas para referência
• Tenants Desatualizados: Lista de tenants usando versões antigas

Migração em Lote

Para atualizar múltiplos tenants para a versão vigente:

1. Acesse a Linha de Produto
2. Selecione os tenants desatualizados
3. Clique em Migrar Selecionados
4. Acompanhe o progresso da migração

---

💡 Casos de Uso

BI Embarcado para Whitelabel

Uma software-house que oferece BI embarcado pode:

1. Desenvolver um template completo com Dashboards padrão
2. Criar variáveis para personalização (API do cliente, cnpj)
3. Instalar o template em cada novo cliente
4. Usar Linhas de Produto para gerenciar atualizações
5. Ativar proteção de mesas para preservar customizações

---

✅ Boas Práticas

IMPORTANT

• Sempre teste templates em um tenant de homologação antes de distribuir
• Use variáveis globais para evitar hardcode de configurações
• Documente as mudanças entre versões no changelog
• Ative a proteção de mesas para clientes que não devem editar o conteúdo base