Reusing an existing app
QV2QS can target an existing Qlik Sense app instead of creating a new app on each deployment, enabling iterative development and preserving the app ID.
By default, QV2QS creates a new app on each deployment. Target an existing app instead to update the app in place and preserve the app ID. This approach allows iterative development and maintains bookmarks and links that reference a specific app ID.
Three arguments support reuse:
--appId APP_ID— Specify the app ID directly.--appIdFile PATH— Read the app ID from the first line of a text file.--reuseAppId— Read the app ID fromcloud/cloud_state.jsonin the project subfolder. This file is written automatically after each deployment.
The cloud/cloud_state.json file is stored in the project subfolder (for example, <outputDir>/Sales/cloud/cloud_state.json). The file records the app ID, media hash, sheet ID mapping, source file path, and a timestamp. The --reuseAppId flag reads this file automatically, so subsequent runs update the same app without requiring manual app ID entry. In batch mode, --reuseAppId works per project — each project reads the cloud_state.json from its own output subfolder.
Sheet ID mapping
Each QlikView document identifies sheets by internal names such as Document\SH01, Document\SH02, and so on. Qlik Sense uses UUIDs to identify sheets. When QV2QS deploys an app for the first time, each converted sheet receives a new UUID. QV2QS stores the mapping between the QlikView sheet name and the Qlik Sense UUID inside the target app so the relationship is preserved across deployments.
On subsequent deployments to the same app, QV2QS reads the stored mapping and assigns the original Qlik Sense UUIDs to the corresponding converted sheets. The mapping prevents duplicate sheets from appearing in the app and preserves bookmarks, favorites, and direct links that reference a specific sheet ID.
The mapping is stored in two locations:
- Inside the Qlik Cloud app — A dedicated object within the app holds the mapping. The mapping travels with the app if the app is moved to a different space or exported as a QVF.
- In the local project folder — The
cloud/cloud_state.jsonfile contains a copy of the same mapping. The--reuseAppIdflag reads the app ID and mapping from this file.
QV2QS always reads the mapping from the cloud app (not the local file) when preparing a redeployment. The local file is a convenience for the --reuseAppId flag to locate the app ID.
Media hash optimization
QV2QS computes a hash of all media files (sheet backgrounds, object backgrounds, button images) and stores the hash alongside the sheet mapping. On subsequent deployments, QV2QS compares the current hash against the stored value. If the media has not changed, the upload step is skipped entirely.
Mapping validation
Before preparing sheets for replacement, QV2QS validates the stored mapping against the live app. If a sheet was deleted manually from the Qlik Cloud app between deployments, QV2QS detects that the sheet no longer exists, removes the stale entry from the mapping, and treats the corresponding QlikView sheet as new on the next build. The updated mapping is written back to the app after the build completes.
Sheets added or removed in the QlikView source
When a sheet is added to the QlikView source after the initial deployment, QV2QS assigns a new UUID to the sheet and adds the entry to the mapping. When a sheet is removed from the QlikView source, the sheet is no longer present in the build output and is removed from the Qlik Cloud app during the build. The mapping entry for the removed sheet is not carried forward.
Project folder matching
QV2QS writes a .qv2qs_source marker file to each project output folder after the first conversion. The marker records the full path of the source QVW file. On subsequent runs, QV2QS uses the marker to locate the correct project folder for a given QVW file, even when multiple folders share the same base name (for example, Sales/, Sales_2/, Sales_3/).
The marker ensures that each QVW file maps to exactly one output folder. When converting a QVW file that was previously converted, QV2QS searches the output root for a subfolder whose marker matches the source path. If a match is found, QV2QS reuses that folder and reads the cloud_state.json inside it. If no match is found, QV2QS creates a new subfolder with a numeric suffix.
In the wizard, the same matching logic applies. When Reuse existing app is enabled, the wizard checks the output folder for a matching project and populates the AppId field automatically from the previous deployment. If no previous deployment is found, the field remains empty and accepts manual entry or the browse picker.
The .qv2qs_source marker file is created automatically. Do not edit or delete the file. Removing the marker causes QV2QS to create a new project subfolder on the next run instead of reusing the existing one.
Redeployment behavior
QV2QS uses qlik app build to deploy to the target app. The build command performs a full replacement of the app object model. All objects defined in the build output are written to the app. Objects not present in the build output are removed.
Before running the build, QV2QS prepares existing sheets for replacement. QV2QS validates the sheet mapping against the live app (see Sheet ID mapping), records the publish state and rank of each sheet, and removes the old sheets from the cloud app. The local build output is patched with the original Qlik Sense sheet IDs so that bookmarks and links referencing those IDs continue to work after the build.
After the build completes, QV2QS restores the original sheet state. Sheets that were previously published are re-published as base sheets, and the original rank (display order) is restored. New sheets that did not exist in the previous deployment are published as base sheets when the Publish sheets setting is enabled. Disable the setting to leave new sheets unpublished.
User-created content in the target app (manually added sheets, bookmarks, stories, or custom objects created after the previous deployment) is not preserved during redeployment. The qlik app build command replaces the app content with the build output. Back up or publish the app before redeploying if manual adjustments have been made.
Pre-deploy backup
When reusing an existing app, QV2QS automatically exports a no-data QVF backup before modifying the app. The backup captures the app structure (sheets, objects, load script, and metadata) without data, so the export is fast and the file is small.
Backups are saved to cloud/backups/ inside the project output folder. Each backup file is named <AppName>_<shortId>_<timestamp>_nodata.qvf. For example, Sales_a1b2c3d4_20260226-143025_nodata.qvf.
If the backup export fails (for example, due to a network interruption or insufficient permissions), QV2QS logs a warning and continues with the deployment. The failure does not block the conversion.
To skip the automatic backup, pass --noBackup on the command line or enable Skip pre-deploy backup in the wizard. Skipping the backup is useful in CI/CD pipelines where backups are managed externally.
Preserving the target app load script
By default, QV2QS replaces the load script in the target app with the converted load script from the QlikView source. Use --preserveTargetAppScript to keep the existing load script in the target app unchanged. The converted load script is written to the local build/script.qvs file but is not applied to the cloud app.
This option requires --appId or --reuseAppId because it only applies when targeting an existing app. It can be combined with --reload to execute the existing script after updating the UI, which is useful when the target app already has working Qlik Cloud data connections. It can also be combined with --autoBinary to temporarily load data from the original QVW file while keeping the target script intact.
Preserving the target app variables
By default, QV2QS replaces the variables in the target app with the converted variables from the QlikView source. Use --preserveTargetAppVariables to keep the existing variables in the target app unchanged. The converted variables are written to the local variables.json file but are not applied to the cloud app.
This option requires --appId or --reuseAppId because it only applies when targeting an existing app. It can be combined with --preserveTargetAppScript to keep both the load script and variables from the target app intact.