Tenant automático

Com o Client Token, POST /v1/tenants cria o tenant de um cliente final a partir de um template, com os valores daquele cliente nas variáveis. O tenant novo já vem com os Dataflows, as tabelas, os Dashboards e os agendamentos do template. Usuários e login seguem como em qualquer tenant.

Template, Agente ETL e Client Token você prepara uma vez. A criação se repete para cada cliente final.

O que você prepara uma vez

Um template. Você monta o produto num tenant de desenvolvimento, com Dataflows, tabelas, Dashboards e agendamentos, e empacota tudo num template no HEC. O passo a passo está em Templates e Linhas de Produto.

Um Agente ETL. O agente executa as cargas do tenant. Ele pode atender todos os tenants ou um só:

Modo	Quando usar	Na criação do tenant
Um agente na nuvem para todos os tenants	A origem é uma API ou um sistema acessível pela internet	Mande o token do agente em token. O token fica em ETL → Agentes
Um agente por tenant	A origem é um banco na rede do cliente final, como um SQL Server	Crie o tenant sem token. A API cria um agente só para ele, e você instala esse agente na rede do cliente com o token que aparece em ETL → Agentes do tenant novo

Veja Agentes.

O Client Token. Fica no HEC, no cadastro do Cliente, aba Desenvolvedor.

Parametrizar o template por variável

O template leva a estrutura do produto e deixa de fora o que muda de um cliente final para outro: chave de API, CNPJ, URL do ERP. Esses valores ficam nas variáveis globais do tenant, que os Dataflows leem entre chaves. Um HTTP Request escreve {API_KEY} no cabeçalho, e cada tenant põe ali o valor dele na hora da carga.

GET https://api.seusistema.com.br/pedidos
Authorization: Bearer {API_KEY}

Crie as variáveis no tenant de desenvolvimento, em Variáveis Globais do editor de Dataflows. O template leva só os nomes. Os valores de cada cliente final chegam pela API, em development_variables, quando o tenant é criado. Veja Variáveis globais.

IMPORTANT

Para o provisionamento ser 100% automático, todo acesso à origem tem que vir de variável. Credencial de banco do template (uma conexão PostgreSQL, por exemplo) nasce vazia no tenant novo, e a API não tem como preenchê-la. Com credencial no template, alguém precisa abrir o ETL daquele tenant e preencher a conexão antes da primeira carga.

Escolher o template

curl https://api.horusbi.com.br/v1/tenants/templates \
  -H "Authorization: Bearer $CLIENT_TOKEN"

{
  "status": "success",
  "data": [
    { "id": 540, "nome": "Produto BI" },
    { "id": 512, "nome": "Produto BI" }
  ]
}

A lista traz todos os templates do Cliente, até as versões descontinuadas de uma Linha de Produto, só com id e nome. Por ela não dá para saber qual versão é a vigente. Veja isso no HEC, na tela da Linha de Produto, e guarde o id da vigente na configuração do seu sistema.

O Cliente também tem um Template Padrão, campo do cadastro do Cliente no HEC, que POST /v1/tenants aplica quando não recebe templateId. Ele aponta para um id fixo e não segue a Linha de Produto. Ao publicar uma versão nova, atualize o Template Padrão, ou os tenants novos nascem na versão antiga.

Criar o tenant

curl -X POST https://api.horusbi.com.br/v1/tenants \
  -H "Authorization: Bearer $CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Comercial Silva (cliente 1234)",
    "ativo": true,
    "dominio": "bi.suaempresa.com.br",
    "templateId": 540,
    "token": "<token do Agente ETL>",
    "development_variables": {
      "API_KEY": "chave-da-api-deste-cliente",
      "CNPJ_EMPRESA": "12345678000190"
    }
  }'

Campo	Obrigatório	O que é
nome	sim	Nome do tenant. Precisa ser único na plataforma inteira, então inclua o ID do cliente no seu sistema
ativo	sim	true para o tenant já aceitar login
dominio	não	Domínio do DataViz que a URL de login usa. Sem ele, o tenant fica em dataviz.horusbi.com.br
templateId	não	Template a aplicar. Sem ele, vale o Template Padrão do Cliente, e sem os dois o tenant nasce vazio
token	não	Token do Agente ETL na nuvem que vai executar as cargas. Sem ele, a API cria um agente só para este tenant
development_variables	não	Valores das variáveis globais do template, como objeto {"NOME": "valor"}
config	não	Configurações avançadas do tenant. Deixe de fora se não souber o que mandar

Sem token, os Dataflows do template ficam presos ao agente criado só para o tenant, e as cargas rodam quando esse agente for instalado. Se a ideia era usar o agente na nuvem, confira o token: sem ele, as cargas não rodam e a API não avisa. Token que não existe é recusado com Token inválido!.

Preencha todo valor de development_variables. Um valor vazio recusa a criação inteira com Invalid development_variables format. Variável do template que você não mandar entra vazia no tenant, e o Dataflow que usa ela falha na primeira carga.

Se o Cliente tem domínio principal configurado no HEC, ele vale no lugar do dominio que você mandar.

A resposta

Configure o timeout do seu cliente HTTP para pelo menos 2 minutos. A chamada só responde depois de criar o tenant e aplicar o template inteiro, e com template grande isso leva dezenas de segundos.

{
  "status": "success",
  "data": {
    "id": 2048,
    "nome": "Comercial Silva (cliente 1234)",
    "dominio": "bi.suaempresa.com.br",
    "ativo": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "development_variables": [
      { "key": "API_KEY", "value": "chave-da-api-deste-cliente" },
      { "key": "CNPJ_EMPRESA", "value": "12345678000190" }
    ],
    "bi_desks": [{ "id": 7, "nome": "Comercial" }],
    "bi_apps": [{ "id": 42, "nome": "Funil de Vendas", "deskId": 7 }],
    "dw_tables": [{ "id": 3407, "nome": "Vendas", "deskId": 3 }]
  }
}

Guarde data.token junto do cadastro do cliente no seu sistema. É o Tenant Token do tenant novo, e é com ele que você cria usuários e gera login. As variáveis voltam como lista de key e value, mesmo que tenham ido como objeto.

Se a criação falhar no meio

O tenant é gravado antes de o template ser aplicado. Se o apply falha, sobra um tenant incompleto, e tentar de novo com o mesmo nome dá Nome do Tenant indisponível. Antes de tentar de novo, procure o tenant em GET /v1/tenants. Se ele estiver lá, aplique o template nele com POST /v1/tenant/templates/apply, usando o token que veio na listagem.

Disparar a primeira carga

A criação não dispara carga, e as tabelas do tenant nascem vazias. Sem fazer nada, os Dashboards ficam vazios até o primeiro horário do agendamento. Para carregar já, rode os agendamentos que o template criou, com o Tenant Token:

curl https://api.horusbi.com.br/v1/tenant/etl-schedules \
  -H "Authorization: Bearer $TENANT_TOKEN"

curl -X POST https://api.horusbi.com.br/v1/tenant/etl-schedules/run \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"scheduleId": 3301}'

O agendamento roda os Dataflows dele na ordem configurada. A resposta "data": true só confirma que o pedido saiu para os agentes: a carga roda depois, em segundo plano.

Saber se a carga terminou

A API não diz se uma carga está rodando ou se deu certo, nem quando foi a última ou quantas linhas uma tabela tem. Para acompanhar, use o status dos agendamentos no HorusETL do tenant. Veja Execução e Agendamento.

Cadastrar o usuário e abrir o BI

Com o Tenant Token em mãos, o resto é igual a qualquer tenant: criar o usuário e gerar o login transparente.

Atualizar os tenants quando o template muda

Versão nova do template não chega sozinha aos tenants que já existem. Para atualizar vários de uma vez, use a migração em lote da Linha de Produto no HEC. Para atualizar um tenant pela API, aplique o id da versão nova com o Tenant Token:

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 resposta traz o reloadPlan, com as tabelas que o apply criou ou reconstruiu e que ficaram vazias, em ordem de dependência. Mande esses itens para POST /v1/tenant/templates/reload, e as cargas saem na ordem certa.

Desativar e excluir

PUT /v1/tenants com "ativo": false bloqueia o login de todos os usuários do tenant e mantém a cobrança. DELETE /v1/tenants exclui o tenant e encerra a cobrança na competência seguinte. Os detalhes estão na referência da API.