Versão nova do template

Tipo

Como fazer

Para

Parceiro whitelabel, Desenvolvedor

Na tela

HEC › Templates › Linha de Produto › Tenants

Cada tenant fica na versão do template que recebeu na criação. Publicar uma versão nova muda o que os próximos tenants recebem; os que já existem só mudam quando alguém instala a versão nova neles, em lote no HEC ou pela API, um tenant por vez.

Publicar a versão

A versão nova nasce no HEC, a partir do tenant de desenvolvimento:

1. Faça as mudanças no tenant de desenvolvimento.
2. Em HEC › Templates, abra o template e clique em Editar Conteúdo do Template (Nova Versão). Confira as Aplicações e Mesas selecionadas e clique em Salvar Nova Versão (Conteúdo).
3. Na confirmação, marque Definir como versão vigente da linha para que ela passe a ser a Template Vigente. Sem a marca, a versão entra descontinuada, e você a torna vigente depois com Definir Vigente, na Linha de Produto.

Daí em diante, POST /v1/tenants com templateGroupId aplica a versão nova aos tenants criados. Quem cria com templateId continua recebendo o id que mandou, e quem depende do Template Padrão do Cliente recebe o id que está nele. Veja Escolher o template.

Linha de Produto, modos de proteção e o restante do ciclo do template estão em Templates e linhas de produto.

Atualizar vários tenants no HEC

Abra a Linha de Produto em HEC › Templates e vá à aba Tenants. A tabela lista os tenants que usam templates da linha, e os que estão numa versão antiga levam o selo Desatualizado. Marque os tenants e clique em Instalar (N), com N o número de tenants marcados. O HEC pergunta como instalar:

Opção	O que faz
Instalar por cima	Atualiza o que veio do template e mantém o resto do tenant
Espelhar	Deixa o tenant igual ao template e remove o que não está nele. Você confere o que sai antes de executar

Este é o caminho para atualizar a base inteira de uma vez. A API não informa qual versão cada tenant tem, então a lista de desatualizados só existe no HEC.

Atualizar um tenant pela API

Com o Tenant Token, POST /v1/tenant/templates/apply aplica uma versão pelo id. A rota não aceita templateGroupId: pegue o id da versão vigente em GET /v1/tenants/templates, onde ela vem com vigente: true.

Ver antes o que muda

Com preview: true, a API devolve o que o apply faria, sem gravar nada:

curl -X POST https://api.horusbi.com.br/v1/tenant/templates/apply \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateId": 612, "preview": true}'

{
  "success": true,
  "preview": true,
  "agent": { "id": 310, "action": "keep" },
  "changes": {
    "desks": [{ "nome": "Comercial", "type": "application", "action": "keep" }],
    "credentials": [{ "nome": "ERP", "action": "keep" }],
    "variables": [{ "key": "API_KEY", "action": "keep" }],
    "tables": [{ "desk": "Vendas", "nome": "Vendas", "action": "update" }],
    "dataflows": [{ "desk": "Vendas", "nome": "Carga de vendas", "action": "update" }],
    "schedules": [{ "nome": "Diário", "action": "update" }],
    "apps": [{ "desk": "Comercial", "nome": "Funil de Vendas", "action": "update" }]
  },
  "rebuilds": [{ "desk": "Vendas", "table": "Vendas", "reason": "rebuilt" }]
}

Cada item diz create (vai ser criado), update (existe e vai ser reescrito) ou keep (existe e fica como está). Conexões, Mesas e variáveis que já existem ficam. Tabelas, Dataflows, agendamentos e Aplicações do template são reescritos com o conteúdo da versão nova.

Olhe rebuilds com cuidado. Tabela nova, ou com colunas diferentes das da versão anterior, é recriada no apply e fica vazia até a próxima carga, e os Dashboards que leem dela ficam vazios junto. Se o seu cliente final abre o DataViz em horário comercial, aplique fora dele ou dispare a carga logo depois, como em Recarregar as tabelas reconstruídas.

Aplicar

O mesmo pedido, sem preview:

curl -X POST https://api.horusbi.com.br/v1/tenant/templates/apply \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateId": 612}'

A chamada só responde depois de aplicar o template inteiro. Configure o timeout do seu cliente HTTP para pelo menos 2 minutos, como na criação do tenant.

A resposta traz reloadPlan, com as tabelas que o apply criou ou reconstruiu, em ordem de dependência, e as listas credenciaisVazias, variaveisVazias e tabelasVazias. Variável que a versão nova trouxe e o tenant ainda não tinha entra vazia e aparece em variaveisVazias: grave o valor com PUT /v1/tenants, como em Trocar as variáveis depois. Conexão nova entra vazia do mesmo jeito e se preenche como em Preencher as conexões.

Conexões na versão nova

Conexão do template que já tem par no tenant não é recriada. O apply procura o par entre as conexões do mesmo Agente ETL, nesta ordem:

1. a conexão usada na instalação anterior da mesma Linha de Produto;
2. a conexão com o mesmo nome;
3. sem par, cria uma conexão nova, vazia, que aparece em credenciaisVazias.

O par precisa ser do mesmo tipo de banco, com uma exceção: entre os bancos SQL, um tipo substitui o outro. Template feito em Firebird reaproveita a conexão SQL Server do tenant, e o Dataflow passa a extrair no tipo da conexão do tenant. O apply nunca escolhe uma conexão só por ela ser a única do agente.

A prévia compara só pelo nome. Se a conexão do tenant foi renomeada depois da instalação, a prévia mostra create, e o apply reaproveita a da instalação anterior.

Recarregar as tabelas reconstruídas

Mande os itens do reloadPlan para POST /v1/tenant/templates/reload. As cargas saem na ordem certa, e a resposta traz o executionId para acompanhar:

curl -X POST https://api.horusbi.com.br/v1/tenant/templates/reload \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"items": [{ "flowId": 1201, "tokenId": 310 }]}'

Lista vazia responde 400 com Nenhum item para disparar. Com reloadPlan vazio, nenhuma tabela foi recriada e não há o que recarregar.

Espelhar: tirar o que saiu do template

Por padrão, o apply só cria e reescreve. Aplicação, tabela ou Dataflow que existia na versão anterior e saiu da nova continua no tenant. Com espelhar: true, o apply também remove do tenant o conteúdo de template que não existe mais na versão aplicada. Customização feita no tenant, conexões, variáveis, dados de Cadastro e permissões ficam. As regras completas estão em Templates e linhas de produto.

Veja antes o que vai sair, com preview e espelhar juntos:

curl -X POST https://api.horusbi.com.br/v1/tenant/templates/apply \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateId": 612, "preview": true, "espelhar": true}'

A resposta traz, além de changes e rebuilds, o campo plan. Em plan.prune vem cada item que sai, com kind (app, table, flow, schedule, datamart ou desk), nome, deskNome e reason: prune quando o item saiu do template, orphan-cascade quando sai porque tudo o que ele usava saiu. plan.pruneCount e plan.keepCount somam por tipo.

O que o espelho remove vai para a Lixeira do tenant e pode ser restaurado por 90 dias.

CAUTION

O dryRun antigo continua como era: com espelhar, devolve o plano do espelho; sem espelhar, ele instala o template. Para ver antes sem risco, use preview.