Riutilizzare un'app esistente
Ultimo aggiornamento: 14/10/2026QV2QS può puntare a un'app Qlik Sense esistente anziché creare una nuova app a ogni distribuzione, consentendo lo sviluppo iterativo e preservando l'ID dell'app.
Per impostazione predefinita, QV2QS crea una nuova app a ogni distribuzione. Specifica invece un'app esistente come destinazione per aggiornare l'app sul posto e mantenere l'ID dell'app. Questo approccio consente lo sviluppo iterativo e mantiene i segnalibri e i collegamenti che fanno riferimento a un ID app specifico.
Tre argomenti supportano il riutilizzo:
--appId APP_ID— Specifica direttamente l'ID dell'app.--appIdFile PATH— Legge l'ID dell'app dalla prima riga di un file di testo.--reuseAppId— Legge l'ID dell'app dacloud/cloud_state.jsonnella sottocartella del progetto. Questo file viene scritto automaticamente dopo ogni distribuzione.
Il file cloud/cloud_state.json è memorizzato nella sottocartella del progetto (ad esempio, <outputDir>/Sales/cloud/cloud_state.json). Il file registra l'ID dell'app, l'hash del file multimediale, la mappatura dell'ID del foglio, il percorso del file di origine e un timestamp. Il flag --reuseAppId legge automaticamente questo file, quindi le esecuzioni successive aggiornano la stessa app senza richiedere l'inserimento manuale dell'ID dell'app. In modalità batch, --reuseAppId funziona per progetto — ciascun progetto legge il cloud_state.json dalla propria sottocartella di output.
Mappatura ID foglio
Ogni documento QlikView identifica i fogli tramite nomi interni come Document\SH01, Document\SH02 e così via. Qlik Sense utilizza gli UUID per identificare i fogli. Quando QV2QS distribuisce un'app per la prima volta, ogni foglio convertito riceve un nuovo UUID. QV2QS memorizza la mappatura tra il nome del foglio QlikView e l'UUID di Qlik Sense all'interno dell'app di destinazione, in modo che la relazione venga preservata tra le distribuzioni.
Nelle distribuzioni successive sulla stessa app, QV2QS legge la mappatura memorizzata e assegna gli UUID originali di Qlik Sense ai corrispondenti fogli convertiti. La mappatura impedisce la comparsa di fogli duplicati nell'app e preserva segnalibri, preferiti e collegamenti diretti che fanno riferimento a uno specifico ID foglio.
La mappatura viene memorizzata in due posizioni:
- All'interno dell'app Qlik Cloud — Un oggetto dedicato all'interno dell'app contiene la mappatura. La mappatura segue l'app se l'app viene spostata in uno spazio diverso o esportata come QVF.
- Nella cartella locale del progetto — Il file
cloud/cloud_state.jsoncontiene una copia della stessa mappatura. Il flag--reuseAppIdlegge l'ID dell'app e la mappatura da questo file.
QV2QS legge sempre la mappatura dall'app cloud (non dal file locale) quando prepara una ridistribuzione. Il file locale è una comodità per il flag --reuseAppId per individuare l'ID dell'app.
Ottimizzazione dell'hash multimediale
QV2QS calcola un hash di tutti i file multimediali (sfondi dei fogli, sfondi degli oggetti, immagini dei pulsanti) e memorizza l'hash insieme alla mappatura del foglio. Nelle distribuzioni successive, QV2QS confronta l'hash corrente con il valore memorizzato. Se il file multimediale non è stato modificato, il passaggio di caricamento viene saltato completamente.
Convalida della mappatura
Prima di preparare i fogli per la sostituzione, QV2QS convalida la mappatura memorizzata rispetto all'app live. Se un foglio è stato eliminato manualmente dall'app Qlik Cloud tra una distribuzione e l'altra, QV2QS rileva che il foglio non esiste più, rimuove la voce obsoleta dalla mappatura e considera il foglio QlikView corrispondente come nuovo alla build successiva. La mappatura aggiornata viene riscritta nell'app al termine della build.
Fogli aggiunti o rimossi nell'origine QlikView
Quando un foglio viene aggiunto all'origine QlikView dopo la distribuzione iniziale, QV2QS assegna un nuovo UUID al foglio e aggiunge la voce alla mappatura. Quando un foglio viene rimosso dall'origine QlikView, il foglio non è più presente nell'output della build e viene rimosso dall'app Qlik Cloud durante la build. La voce di mappatura per il foglio rimosso non viene riportata.
Corrispondenza cartella di progetto
QV2QS scrive un file marcatore .qv2qs_source in ogni cartella di output del progetto dopo la prima conversione. Il marcatore registra il percorso completo del file QVW di origine. Nelle esecuzioni successive, QV2QS utilizza il marcatore per individuare la cartella di progetto corretta per un determinato file QVW, anche quando più cartelle condividono lo stesso nome di base (ad esempio, Sales/, Sales_2/, Sales_3/).
Il marcatore garantisce che ciascun file QVW sia mappato esattamente su una cartella di output. Quando si converte un file QVW precedentemente convertito, QV2QS cerca nella radice di output una sottocartella il cui marcatore corrisponde al percorso di origine. Se viene trovata una corrispondenza, QV2QS riutilizza quella cartella e legge il cloud_state.json al suo interno. Se non viene trovata alcuna corrispondenza, QV2QS crea una nuova sottocartella con un suffisso numerico.
Nella procedura guidata si applica la stessa logica di corrispondenza. Quando Riutilizza app esistente è abilitato, la procedura guidata controlla la cartella di output alla ricerca di un progetto corrispondente e popola automaticamente il campo AppId dalla distribuzione precedente. Se non viene trovata alcuna distribuzione precedente, il campo rimane vuoto e accetta l'immissione manuale o il selettore Sfoglia.
Il file marcatore .qv2qs_source viene creato automaticamente. Non modificare o eliminare il file. La rimozione del marcatore fa sì che QV2QS crei una nuova sottocartella di progetto alla successiva esecuzione, anziché riutilizzare quella esistente.
Comportamento di ridistribuzione
QV2QS utilizza qlik app build per distribuire nell'app di destinazione. Il comando di compilazione esegue una sostituzione completa del modello a oggetti dell'app. Tutti gli oggetti definiti nell'output di compilazione vengono scritti nell'app. Gli oggetti non presenti nell'output di compilazione vengono rimossi.
Prima di eseguire la build, QV2QS prepara i fogli esistenti per la sostituzione. QV2QS convalida la mappatura dei fogli rispetto all'app live (vedere Mappatura ID foglio), registra lo stato di pubblicazione e il rango di ciascun foglio e rimuove i vecchi fogli dall'app cloud. L'output della build locale viene aggiornato con gli ID originali dei fogli Qlik Sense in modo che i segnalibri e i collegamenti che fanno riferimento a tali ID continuino a funzionare dopo la build.
Al termine della build, QV2QS ripristina lo stato originale del foglio. I fogli pubblicati in precedenza vengono ripubblicati come fogli di base e viene ripristinato il rango originale (ordine di visualizzazione). I nuovi fogli che non esistevano nella distribuzione precedente vengono pubblicati come fogli di base quando l'impostazione Pubblica fogli è abilitata. Disattivare l'impostazione per lasciare i nuovi fogli non pubblicati.
I contenuti creati dall'utente nell'app di destinazione (fogli aggiunti manualmente, segnalibri, storie o oggetti personalizzati creati dopo la distribuzione precedente) non vengono conservati durante la ridistribuzione. Il comando qlik app build sostituisce il contenuto dell'app con l'output di compilazione. Esegui il backup o pubblica l'app prima di ridistribuirla se sono state apportate modifiche manuali.
Backup pre-distribuzione
Quando si riutilizza un'app esistente, QV2QS esporta automaticamente un backup QVF senza dati prima di modificare l'app. Il backup acquisisce la struttura dell'app (fogli, oggetti, script di caricamento e metadati) senza dati, quindi l'esportazione è rapida e il file è piccolo.
I backup vengono salvati in cloud/backups/ all'interno della cartella di output del progetto. Ogni file di backup è denominato <AppName>_<shortId>_<timestamp>_nodata.qvf. Ad esempio, Sales_a1b2c3d4_20260226-143025_nodata.qvf.
Se l'esportazione del backup non riesce (ad esempio, a causa di un'interruzione di rete o di autorizzazioni insufficienti), QV2QS registra un avviso e continua con la distribuzione. L'errore non blocca la conversione.
Per ignorare il backup automatico, passare --noBackup sulla riga di comando o abilitare Ignora backup pre-distribuzione nella procedura guidata. Saltare il backup è utile nelle pipeline CI/CD in cui i backup sono gestiti esternamente.
Mantenimento dello script di caricamento dell'app di destinazione
Per impostazione predefinita, QV2QS sostituisce lo script di caricamento nell'app di destinazione con lo script di caricamento convertito dalla sorgente QlikView. Utilizzare --preserveTargetAppScript per mantenere invariato lo script di caricamento esistente nell'app di destinazione. Lo script di caricamento convertito viene scritto nel file locale build/script.qvs ma non viene applicato all'app cloud.
Questa opzione richiede --appId o --reuseAppId perché si applica solo quando la destinazione è un'app esistente. Può essere combinato con --reload per eseguire lo script esistente dopo aver aggiornato l'interfaccia utente, il che è utile quando l'app di destinazione dispone già di connessioni dati Qlik Cloud funzionanti. Può anche essere combinato con --autoBinary per caricare temporaneamente i dati dal file QVW originale mantenendo intatto lo script di destinazione.
Mantenimento delle variabili dell'app di destinazione
Per impostazione predefinita, QV2QS sostituisce le variabili nell'app di destinazione con le variabili convertite dall'origine QlikView. Usa --preserveTargetAppVariables per mantenere invariate le variabili esistenti nell'app di destinazione. Le variabili convertite vengono scritte nel file locale variables.json ma non vengono applicate all'app cloud.
Questa opzione richiede --appId o --reuseAppId perché si applica solo quando la destinazione è un'app esistente. Può essere combinato con --preserveTargetAppScript per mantenere intatti sia lo script di caricamento sia le variabili dell'app di destinazione.