Reutilizando um aplicativo existente
Última atualização: 14/10/2026O QV2QS pode ter como destino um aplicativo Qlik Sense existente em vez de criar um novo aplicativo a cada implementação, permitindo o desenvolvimento iterativo e preservando o ID do aplicativo.
Por padrão, o QV2QS cria um novo aplicativo a cada implementação. Em vez disso, direcione para um aplicativo existente para atualizar o aplicativo no local e preservar o ID do aplicativo. Esta abordagem permite o desenvolvimento iterativo e mantém favoritos e links que fazem referência a um ID de aplicativo específico.
Três argumentos apoiam a reutilização:
--appId APP_ID— Especifique o ID do aplicativo diretamente.--appIdFile PATH— Lê o ID do aplicativo da primeira linha de um arquivo de texto.--reuseAppId— Leia o ID do aplicativo decloud/cloud_state.jsonna subpasta do projeto. Este arquivo é gravado automaticamente após cada implementação.
O arquivo cloud/cloud_state.json é armazenado na subpasta do projeto (por exemplo, <outputDir>/Sales/cloud/cloud_state.json). O arquivo registra o ID do aplicativo, o hash de mídia, o mapeamento de ID da pasta, o caminho do arquivo de origem e um carimbo de data/hora. A flag --reuseAppId lê este arquivo automaticamente, de modo que as execuções subsequentes atualizam o mesmo aplicativo sem exigir a entrada manual do ID do aplicativo. No modo em lote, o --reuseAppId funciona por projeto — cada projeto lê o cloud_state.json de sua própria subpasta de saída.
Mapeamento de ID da planilha
Cada documento do QlikView identifica pastas por nomes internos, como Document\SH01, Document\SH02 e assim por diante. O Qlik Sense usa UUIDs para identificar pastas. Quando o QV2QS implanta um aplicativo pela primeira vez, cada pasta convertida recebe um novo UUID. O QV2QS armazena o mapeamento entre o nome da pasta do QlikView e o UUID do Qlik Sense dentro do aplicativo de destino para que o relacionamento seja preservado entre implantações.
Em implantações subsequentes no mesmo aplicativo, o QV2QS lê o mapeamento armazenado e atribui os UUIDs originais do Qlik Sense às pastas convertidas correspondentes. O mapeamento evita que pastas duplicadas apareçam no aplicativo e preserva marcadores, favoritos e links diretos que fazem referência a um ID de pasta específico.
O mapeamento é armazenado em dois locais:
- Dentro do aplicativo Qlik Cloud — Um objeto dedicado dentro do aplicativo contém o mapeamento. O mapeamento acompanha o aplicativo se o aplicativo for movido para um espaço diferente ou exportado como um QVF.
- Na pasta local do projeto — O arquivo
cloud/cloud_state.jsoncontém uma cópia do mesmo mapeamento. A flag--reuseAppIdlê o ID do aplicativo e o mapeamento deste arquivo.
O QV2QS sempre lê o mapeamento do aplicativo da nuvem (não do arquivo local) ao preparar uma reimplantação. O arquivo local é uma conveniência para a flag --reuseAppId localizar o ID do aplicativo.
Otimização de hash de mídia
O QV2QS calcula um hash de todos os arquivos de mídia (planos de fundo de pasta, planos de fundo de objeto, imagens de botão) e armazena o hash junto com o mapeamento de pasta. Em implantações subsequentes, o QV2QS compara o hash atual com o valor armazenado. Se a mídia não tiver sido alterada, a etapa de upload é totalmente ignorada.
Validação de mapping
Antes de preparar as pastas para substituição, o QV2QS valida o mapeamento armazenado em relação ao aplicativo ativo. Se uma pasta foi excluída manualmente do aplicativo Qlik Cloud entre implantações, o QV2QS detecta que a pasta não existe mais, remove a entrada obsoleta do mapeamento e trata a pasta correspondente do QlikView como nova na próxima compilação. O mapeamento atualizado é gravado de volta no aplicativo após a conclusão da compilação.
Pastas adicionadas ou removidas na origem do QlikView
Quando uma pasta é adicionada à origem do QlikView após a implementação inicial, o QV2QS atribui um novo UUID à pasta e adiciona a entrada ao mapeamento. Quando uma pasta é removida da origem do QlikView, a pasta não está mais presente na saída da compilação e é removida do aplicativo do Qlik Cloud durante a compilação. A entrada de mapeamento da pasta removida não é transferida.
Correspondência de pasta do projeto
O QV2QS grava um arquivo marcador .qv2qs_source em cada pasta de saída do projeto após a primeira conversão. O marcador registra o caminho completo do arquivo QVW de origem. Em execuções subsequentes, o QV2QS usa o marcador para localizar a pasta de projeto correta para um determinado arquivo QVW, mesmo quando várias pastas compartilham o mesmo nome base (por exemplo, Sales/, Sales_2/, Sales_3/).
O marcador garante que cada arquivo QVW seja mapeado para exatamente uma pasta de saída. Ao converter um arquivo QVW que foi convertido anteriormente, o QV2QS pesquisa na raiz de saída por uma subpasta cujo marcador corresponda ao caminho de origem. Se uma correspondência for encontrada, o QV2QS reutiliza essa pasta e lê o cloud_state.json dentro dela. Se nenhuma correspondência for encontrada, o QV2QS cria uma nova subpasta com um sufixo numérico.
No assistente, a mesma lógica de correspondência se aplica. Quando Reutilizar aplicativo existente estiver habilitado, o assistente verifica a pasta de saída em busca de um projeto correspondente e preenche o campo AppId automaticamente a partir da implementação anterior. Se nenhuma implementação anterior for encontrada, o campo permanece vazio e aceita entrada manual ou o seletor de navegação.
O arquivo marcador .qv2qs_source é criado automaticamente. Não edite ou exclua o arquivo. Remover o marcador faz com que o QV2QS crie uma nova subpasta de projeto na próxima execução em vez de reutilizar a existente.
Comportamento de reimplantação
O QV2QS usa qlik app build para implementar no aplicativo de destino. O comando build realiza uma substituição completa do modelo de objeto do aplicativo. Todos os objetos definidos na saída da compilação são gravados no aplicativo. Objetos não presentes na saída do build são removidos.
Antes de executar o build, o QV2QS prepara as pastas existentes para substituição. O QV2QS valida o mapeamento de pastas em relação ao aplicativo ativo (consulte Mapeamento de ID de pasta), registra o estado de publicação e a classificação de cada pasta e remove as pastas antigas do aplicativo na nuvem. A saída da compilação local é corrigida com os IDs originais das pastas do Qlik Sense para que os marcadores e links que fazem referência a esses IDs continuem funcionando após a compilação.
Após a conclusão do build, o QV2QS restaura o estado original da pasta. As pastas que foram publicadas anteriormente são republicadas como pastas base, e a classificação original (ordem de exibição) é restaurada. Novas pastas que não existiam na implementação anterior são publicadas como pastas base quando a configuração Publicar pastas está habilitada. Desative a configuração para manter novas planilhas não publicadas.
O conteúdo criado pelo usuário no aplicativo de destino (pastas adicionadas manualmente, marcadores, histórias ou objetos personalizados criados após a implementação anterior) não é preservado durante a reimplementação. O comando qlik app build substitui o conteúdo do aplicativo pela saída da compilação. Faça backup ou publique o aplicativo antes de reimplantar caso ajustes manuais tenham sido feitos.
Backup pré-implementação
Ao reutilizar um aplicativo existente, o QV2QS exporta automaticamente um backup QVF sem dados antes de modificar o aplicativo. O backup captura a estrutura do aplicativo (pastas, objetos, script de carregamento e metadados) sem dados, portanto, exportar é rápido e o arquivo é pequeno.
Os backups são salvos em cloud/backups/ dentro da pasta de saída do projeto. Cada arquivo de backup é nomeado <AppName>_<shortId>_<timestamp>_nodata.qvf. Por exemplo, Sales_a1b2c3d4_20260226-143025_nodata.qvf.
Se exportar o backup falhar (por exemplo, devido a uma interrupção de rede ou permissões insuficientes), o QV2QS registra um aviso e continua com a implementação. A falha não bloqueia a conversão.
Para ignorar o backup automático, passe --noBackup na linha de comando ou ative Ignorar backup pré-implementação no assistente. Ignorar o backup é útil em pipelines de CI/CD onde os backups são gerenciados externamente.
Preservando o script de carregamento do aplicativo de destino
Por padrão, o QV2QS substitui o script de carregamento no aplicativo de destino pelo script de carregamento convertido da origem do QlikView. Use --preserveTargetAppScript para manter o script de carregamento existente no aplicativo de destino inalterado. O script de carregamento convertido é gravado no arquivo build/script.qvs local, mas não é aplicado ao aplicativo na nuvem.
Esta opção requer --appId ou --reuseAppId porque só se aplica ao direcionar para um aplicativo existente. Pode ser combinado com --reload para executar o script existente após atualizar a UI, o que é útil quando o aplicativo de destino já possui conexões de dados do Qlik Cloud funcionando. Também pode ser combinado com --autoBinary para carregar temporariamente dados do arquivo QVW original enquanto mantém o script de destino intacto.
Preservando as variáveis do aplicativo de destino
Por padrão, o QV2QS substitui as variáveis no aplicativo de destino pelas variáveis convertidas da origem do QlikView. Use --preserveTargetAppVariables para manter as variáveis existentes no aplicativo de destino inalteradas. As variáveis convertidas são gravadas no arquivo local variables.json, mas não são aplicadas ao aplicativo na nuvem.
Esta opção requer --appId ou --reuseAppId porque só se aplica ao direcionar para um aplicativo existente. Pode ser combinado com --preserveTargetAppScript para manter intactos tanto o script de carregamento quanto as variáveis do aplicativo de destino.