Rotina noturna: guia de instalação

Script 3.1.1, edição pública. Para Qlik Sense Enterprise client-managed, em Windows.

A rotina noturna é um script PowerShell opcional que roda no servidor do Qlik Sense, de madrugada. Ela extrai o script de carga de todos os apps e guarda no mesmo repositório Git que a extensão usa. É a rede de segurança: o que alguém mudou sem salvar pelo Versiona entra no Git do mesmo jeito, num commit chamado "Autosync", e o mascote convida a explicar a mudança.

Baixar o script (.ps1)

Sem a rotina, o Versiona funciona normalmente, e só entra no Git o que alguém salvar pela extensão. Não existe rotina para o Qlik Cloud. O script é gratuito e fornecido como está, sem garantia e sem SLA, nos termos de uso. Leia o script antes de rodar: ele é um arquivo de texto, e tudo o que faz está escrito nele.

O que você precisa

Acesso de administrador ao servidor do Qlik Sense (Windows Server, PowerShell 4.0 ou mais novo).
Uma conta de serviço para executar a tarefa agendada. Pode ser a conta do serviço do Qlik.
Git for Windows 2.31 ou mais novo, em C:\Program Files\Git.
O módulo Qlik-Cli do PowerShell.
Um repositório privado no GitLab, um por servidor Qlik, e permissão para criar um token de acesso nele.
Opcional: uma caixa de e-mail com SMTP autenticado, para o resumo diário.

A rotina foi testada com GitLab. Com GitHub ela ainda não foi testada.

1. A pasta do script, com acesso restrito

O script e as credenciais ficam em C:\versiona. Só o sistema, os administradores e a conta de serviço devem alcançar essa pasta. No PowerShell, como administrador (troque SEUDOMINIO\svc_qlik pela sua conta de serviço):

New-Item -ItemType Directory -Force -Path C:\versiona
icacls C:\versiona /inheritance:r /grant:r "*S-1-5-18:(OI)(CI)F" "*S-1-5-32-544:(OI)(CI)F" "SEUDOMINIO\svc_qlik:(OI)(CI)M"

O /inheritance:r tira as permissões herdadas, que costumam incluir "Usuários". Os dois códigos são o sistema e o grupo de administradores, e valem em Windows de qualquer idioma. Copie o script baixado para dentro da pasta.

2. O repositório e o token no GitLab

Crie o repositório, privado. O nome padrão que a rotina procura é scriptqlik_qliksense_<nome da máquina em minúsculas>, dentro do grupo que você indicar. Dá para trocar o nome no script.
No repositório, abra Settings, Access tokens e crie um Project Access Token:
- nome: por exemplo versiona_qlik_dev (o nome entra no script);
- papel: Developer;
- escopos: só read_repository e write_repository;
- validade: até um ano. Anote a data: ela também entra no script.
Copie o token na hora. O GitLab mostra uma vez só.
Em Settings, Repository, Protected branches, deixe "Allowed to push and merge" em Developers + Maintainers e o force push desligado. Com o padrão (só Maintainers), o push da rotina e o da extensão são recusados.

Token de projeto, e não o seu token pessoal: ele só enxerga aquele repositório, não cai quando alguém sai da empresa e não carrega as suas permissões. Os commits da extensão continuam saindo com o login de cada pessoa.

3. Guardar o token com segurança (`.cred_gitlab_qlik`)

O token não fica no script. Ele é cifrado pela DPAPI do Windows, e o arquivo cifrado só pode ser aberto pela mesma conta, na mesma máquina que o gerou. Por isso o comando precisa ser rodado como a conta de serviço, no próprio servidor do Qlik.

Abra um PowerShell como a conta de serviço:

runas /user:SEUDOMINIO\svc_qlik powershell.exe

Se a conta de serviço não puder abrir sessão interativa, peça ao administrador a permissão só para este passo, ou gere o arquivo por uma tarefa agendada de uso único. O que não pode é gerar com outra conta.

Na janela que abrir, confira quem você é e grave a credencial:

whoami
Read-Host -AsSecureString | ConvertFrom-SecureString | Out-File "C:\versiona\.cred_gitlab_qlik"

O Read-Host fica esperando: cole o token e aperte Enter. Ele não aparece na tela nem entra no histórico de comandos. Para conferir que gravou, sem mostrar o token:

(Get-Content "C:\versiona\.cred_gitlab_qlik" | ConvertTo-SecureString).Length

O número é o tamanho do token. Se der erro, o arquivo foi gerado por outra conta ou em outra máquina.

Não copie o arquivo de um servidor para outro: gere em cada um.
Não cole o token no script, em e-mail, em chamado nem em chat.
Depois de gravar, apague o token de onde você o anotou.

4. Guardar a senha do e-mail (`.cred_smtp`), se for usar

O resumo diário por e-mail é opcional, e o script vem com ele desligado. Para ligar, a senha do SMTP é guardada do mesmo jeito, na mesma janela da conta de serviço:

Read-Host -AsSecureString | ConvertFrom-SecureString | Out-File "C:\versiona\.cred_smtp"

Use uma caixa só para alertas, e não a de uma pessoa.
Se o provedor tem "senha de app" (o Gmail tem, com a verificação em duas etapas ligada), use a senha de app, e não a senha da conta.
O envio usa TLS na porta 587, com o certificado conferido.

5. Ajustar os parâmetros do script

Abra o script num editor e ajuste a seção 1, "Parâmetros do usuário". O resto não precisa mexer.

Parâmetro	O que pôr
`$vServidores`	Uma linha por servidor Qlik: o nome da máquina (o que o comando `hostname` mostra, em maiúsculas), o ambiente, o nome do token e a data em que ele vence (`aaaa-mm-dd`). É dela que sai o alerta de vencimento.
`$vPastaDestino`	Onde ficam os arquivos extraídos e o repositório Git local. Pasta do servidor ou compartilhamento de rede. A conta de serviço precisa de escrita.
`$vGitBaseURL`	O endereço do GitLab, sem `https://`.
`$vGitNamespace`	O grupo onde o repositório está.
`$vGitRepoNome`	Só se o repositório não seguir o nome padrão.
`$vGitAutorNome`, `$vGitAutorEmail`	Como a rotina aparece no histórico.
`$vEnviarEmail` e os de SMTP	`$true` e os endereços, depois de gravar o `.cred_smtp`.

O mesmo arquivo serve a vários servidores: cada um se reconhece pelo nome da máquina. Depois de salvar, garanta que o arquivo está em UTF-8 com BOM, senão o PowerShell 4.0 quebra os acentos do e-mail:

$p = "C:\versiona\Versiona_RotinaNoturna_QlikSense.ps1"
$c = [IO.File]::ReadAllText($p, [Text.Encoding]::UTF8)
[IO.File]::WriteAllText($p, $c, (New-Object Text.UTF8Encoding($true)))

6. Rodar a primeira vez, à mão

Na janela da conta de serviço:

cd C:\versiona
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\Versiona_RotinaNoturna_QlikSense.ps1

A primeira coisa que a rotina faz é conferir o acesso ao repositório, antes de extrair qualquer coisa. Se o token estiver errado, ela para ali e diz o motivo. A primeira extração demora: é um app de cada vez. No fim, confira no GitLab as pastas dos fluxos, a pasta __Trabalho e o arquivo _indice_apps.jsonl.

7. Agendar

No Agendador de Tarefas, crie uma tarefa que roda com a conta de serviço, "estando o usuário conectado ou não":

Programa	`powershell.exe`
Argumentos	`-NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "C:\versiona\Versiona_RotinaNoturna_QlikSense.ps1"`
Iniciar em	`C:\versiona`
Frequência	Diária, de madrugada, fora do horário das cargas.

A rotina termina com código 1 quando algo falha, para o monitoramento da tarefa enxergar. Se a tarefa repetir no mesmo dia, ela não extrai de novo: só sincroniza.

8. Avisar a extensão

Se ainda não tem a extensão, instale o Versiona. Nele, em Servidores, edite o servidor e marque "Este ambiente roda a rotina noturna de versionamento". Com a rotina, a pasta do servidor no repositório fica em branco: a rotina grava na raiz.

Renovar o token

A partir de 30 dias antes da data que você pôs em TokenExpira, o e-mail da rotina passa a avisar no assunto. Para renovar: gere outro token no GitLab, repita o passo 3 no servidor e atualize o nome e a data em $vServidores.

Se algo der errado

O que aparece	O que costuma ser
"Falha ao ler credencial"	O arquivo foi gerado por outra conta ou em outra máquina. Refaça o passo 3 como a conta que executa a tarefa.
"Sem acesso ao repositório"	Token vencido ou revogado, sem papel Developer, sem os dois escopos, ou o repositório não existe com aquele nome.
Push recusado, "protected branch"	A branch protegida só aceita Maintainers. Veja o passo 2.
Erro de certificado no Git	Falta a autoridade certificadora na máquina. Corrija na máquina; não desligue a verificação.
"Certificado QlikClient não encontrado"	A rotina precisa rodar num nó do Qlik Sense, com o certificado de cliente instalado.
Acentos trocados no e-mail	O arquivo perdeu o BOM. Rode o comando do fim do passo 5.

O que a rotina não faz

Não altera nenhum app: só lê o script de carga.
Não apaga do Git o arquivo de um app excluído ou renomeado.
Não força o push e não reescreve o histórico.
Não envia nada para a Cubotimize: fala só com o seu Qlik, o seu Git e o seu servidor de e-mail.

Dúvida, sugestão ou problema: [email protected]. Não mande token, senha nem script de carga por e-mail.

Créditos: Cubotimize | CuboPlus e Mario Soares.