Rutina nocturna: guía de instalación

Script 3.1.1, edición pública. Para Qlik Sense Enterprise client-managed, en Windows.

La rutina nocturna es un script de PowerShell opcional que se ejecuta en el servidor de Qlik Sense, de madrugada. Extrae el script de carga de todas las apps y lo guarda en el mismo repositorio Git que usa la extensión. Es la red de seguridad: lo que alguien cambió sin guardar con Versiona entra en Git de todos modos, en un commit llamado "Autosync", y la mascota invita a explicar el cambio.

Descargar el script (.ps1)

Los comentarios y los mensajes del script están en portugués.

Sin la rutina, Versiona funciona normalmente, y solo entra en Git lo que alguien guarde desde la extensión. No existe rutina para Qlik Cloud. El script es gratuito y se entrega tal como está, sin garantía y sin SLA, según los términos de uso. Lea el script antes de ejecutarlo: es un archivo de texto, y todo lo que hace está escrito en él.

Lo que se necesita

Acceso de administrador al servidor de Qlik Sense (Windows Server, PowerShell 4.0 o más reciente).
Una cuenta de servicio para ejecutar la tarea programada. Puede ser la cuenta del servicio de Qlik.
Git for Windows 2.31 o más reciente, en C:\Program Files\Git.
El módulo Qlik-Cli de PowerShell.
Un repositorio privado en GitLab, uno por servidor Qlik, y permiso para crear un token de acceso en él.
Opcional: un buzón de correo con SMTP autenticado, para el resumen diario.

La rutina fue probada con GitLab. Con GitHub todavía no fue probada.

1. La carpeta del script, con acceso restringido

El script y las credenciales quedan en C:\versiona. Solo el sistema, los administradores y la cuenta de servicio deben alcanzar esa carpeta. En PowerShell, como administrador (cambie SEUDOMINIO\svc_qlik por su cuenta de servicio):

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"

El /inheritance:r quita los permisos heredados, que suelen incluir "Usuarios". Los dos códigos son el sistema y el grupo de administradores, y valen en Windows de cualquier idioma. Copie el script descargado dentro de la carpeta.

2. El repositorio y el token en GitLab

Cree el repositorio, privado. El nombre predeterminado que la rutina busca es scriptqlik_qliksense_<nome da máquina em minúsculas>, dentro del grupo que se indique. Se puede cambiar el nombre en el script.
En el repositorio, abra Settings, Access tokens y cree un Project Access Token:
- nombre: por ejemplo versiona_qlik_dev (el nombre va en el script);
- rol: Developer;
- alcances: solo read_repository y write_repository;
- vigencia: hasta un año. Anote la fecha: también va en el script.
Copie el token en el momento. GitLab lo muestra una sola vez.
En Settings, Repository, Protected branches, deje "Allowed to push and merge" en Developers + Maintainers y el force push desactivado. Con el valor predeterminado (solo Maintainers), el push de la rutina y el de la extensión son rechazados.

Token de proyecto, y no su token personal: solo ve ese repositorio, no deja de funcionar cuando alguien sale de la empresa y no lleva los permisos de usted. Los commits de la extensión siguen saliendo con el login de cada persona.

3. Guardar el token de forma segura (`.cred_gitlab_qlik`)

El token no queda en el script. Lo cifra la DPAPI de Windows, y el archivo cifrado solo puede abrirse con la misma cuenta, en la misma máquina que lo generó. Por eso el comando debe ejecutarse como la cuenta de servicio, en el propio servidor de Qlik.

Abra un PowerShell como la cuenta de servicio:

runas /user:SEUDOMINIO\svc_qlik powershell.exe

Si la cuenta de servicio no puede abrir una sesión interactiva, pida al administrador el permiso solo para este paso, o genere el archivo con una tarea programada de un solo uso. Lo que no se puede es generarlo con otra cuenta.

En la ventana que se abre, verifique con qué cuenta está y grabe la credencial:

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

El Read-Host queda esperando: pegue el token y presione Enter. No aparece en la pantalla ni entra en el historial de comandos. Para verificar que se grabó, sin mostrar el token:

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

El número es la longitud del token. Si da error, el archivo fue generado con otra cuenta o en otra máquina.

No copie el archivo de un servidor a otro: genérelo en cada uno.
No pegue el token en el script, en un correo, en un ticket ni en un chat.
Después de grabar, borre el token del lugar donde lo anotó.

4. Guardar la contraseña del correo (`.cred_smtp`), si se va a usar

El resumen diario por correo es opcional, y el script viene con él desactivado. Para activarlo, la contraseña del SMTP se guarda de la misma manera, en la misma ventana de la cuenta de servicio:

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

Use un buzón solo para alertas, y no el de una persona.
Si el proveedor tiene "contraseña de aplicación" (Gmail la tiene, con la verificación en dos pasos activada), use la contraseña de aplicación, y no la contraseña de la cuenta.
El envío usa TLS en el puerto 587, con el certificado verificado.

5. Ajustar los parámetros del script

Abra el script en un editor y ajuste la sección 1, "Parâmetros do usuário" (parámetros del usuario). El resto no hace falta tocarlo.

Parámetro	Qué poner
`$vServidores`	Una línea por servidor Qlik: el nombre de la máquina (el que muestra el comando `hostname`, en mayúsculas), el entorno, el nombre del token y la fecha en que vence (`aaaa-mm-dd`). De ella sale la alerta de vencimiento.
`$vPastaDestino`	Dónde quedan los archivos extraídos y el repositorio Git local. Carpeta del servidor o recurso compartido de red. La cuenta de servicio necesita permiso de escritura.
`$vGitBaseURL`	La dirección de GitLab, sin `https://`.
`$vGitNamespace`	El grupo donde está el repositorio.
`$vGitRepoNome`	Solo si el repositorio no sigue el nombre predeterminado.
`$vGitAutorNome`, `$vGitAutorEmail`	Cómo aparece la rutina en el historial.
`$vEnviarEmail` y los de SMTP	`$true` y las direcciones, después de grabar el `.cred_smtp`.

El mismo archivo sirve a varios servidores: cada uno se reconoce por el nombre de la máquina. Después de guardar, asegúrese de que el archivo está en UTF-8 con BOM; de lo contrario, PowerShell 4.0 daña los acentos del correo:

$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. Ejecutar la primera vez, a mano

En la ventana de la cuenta de servicio:

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

Lo primero que hace la rutina es verificar el acceso al repositorio, antes de extraer cualquier cosa. Si el token está mal, se detiene ahí y dice el motivo. La primera extracción demora: es una app a la vez. Al final, verifique en GitLab las carpetas de los streams, la carpeta __Trabalho y el archivo _indice_apps.jsonl.

7. Programar

En el Programador de tareas, cree una tarea que se ejecute con la cuenta de servicio, "tanto si el usuario inició sesión como si no":

Programa	`powershell.exe`
Argumentos	`-NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "C:\versiona\Versiona_RotinaNoturna_QlikSense.ps1"`
Iniciar en	`C:\versiona`
Frecuencia	Diaria, de madrugada, fuera del horario de las recargas.

La rutina termina con código 1 cuando algo falla, para que el monitoreo de la tarea lo detecte. Si la tarea se repite el mismo día, no extrae de nuevo: solo sincroniza.

8. Avisar a la extensión

Si todavía no tiene la extensión, instale Versiona. En ella, en Servidores, edite el servidor y marque "Este entorno ejecuta la rutina nocturna de versionado". Con la rutina, la carpeta del servidor en el repositorio queda en blanco: la rutina graba en la raíz.

Renovar el token

A partir de 30 días antes de la fecha puesta en TokenExpira, el correo de la rutina empieza a avisar en el asunto. Para renovar: genere otro token en GitLab, repita el paso 3 en el servidor y actualice el nombre y la fecha en $vServidores.

Si algo sale mal

Qué aparece	Qué suele ser
"Falha ao ler credencial" (error al leer la credencial)	El archivo fue generado con otra cuenta o en otra máquina. Repita el paso 3 como la cuenta que ejecuta la tarea.
"Sem acesso ao repositório" (sin acceso al repositorio)	Token vencido o revocado, sin rol Developer, sin los dos alcances, o el repositorio no existe con ese nombre.
Push rechazado, "protected branch"	La branch protegida solo acepta Maintainers. Vea el paso 2.
Error de certificado en Git	Falta la autoridad certificadora en la máquina. Corríjalo en la máquina; no desactive la verificación.
"Certificado QlikClient não encontrado" (no se encontró el certificado QlikClient)	La rutina debe ejecutarse en un nodo de Qlik Sense, con el certificado de cliente instalado.
Acentos alterados en el correo	El archivo perdió el BOM. Ejecute el comando del final del paso 5.

Lo que la rutina no hace

No altera ninguna app: solo lee el script de carga.
No borra de Git el archivo de una app eliminada o renombrada.
No fuerza el push y no reescribe el historial.
No envía nada a Cubotimize: se comunica solo con su Qlik, su Git y su servidor de correo.

Dudas, sugerencias o problemas: [email protected]. No envíe tokens, contraseñas ni scripts de carga por correo electrónico.

Créditos: Cubotimize | CuboPlus y Mario Soares.