# 変換の仕組み

変換パイプラインには以下のフェーズがあります。

* 抽出 — `--generatePrj`が有効になっている場合、QV2QSはQlikView Desktopを起動し、QVWファイルをPRJフォルダーに抽出します。QV2QSは、QlikView Desktopのシステムインストールが検出されない限り、バンドルされているポータブルエンジンを使用します。詳細については、[QlikView Desktop エンジン](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/getting-started/qlikview-desktop-engine.htm)を参照してください。
* 解析 — QV2QS は PRJ フォルダーを読み込み、すべてのオブジェクト定義、シート レイアウト、ロード スクリプト、変数、およびドキュメント プロパティを解析します。QV2QSは、QVW/QVFバイナリを直接読み取り、メタデータ、変数、およびファイルに埋め込まれた隠されたロード スクリプトを抽出します。
* 変換 — 各 QlikView オブジェクトは Qlik Sense ビジュアライゼーション タイプにマッピングされます。ディメンション、メジャー、式、スタイル設定、およびレイアウト位置は、Qlik Sense JSON形式に変換されます。
* 書き込み — QV2QS は、変換されたアプリの構造を JSON ファイルのセットとして出力フォルダーに書き込みます。
* デプロイ (クラウドモードのみ) — QV2QS はテナント上にアプリを作成し、メディアをアップロードし、アプリを構築し、必要に応じてデータを伴ってアプリをリロードします。
* レポート — QV2QS は、結果、オートメーションのスコアリング、および手動でのフォローアップが必要な項目をまとめた変換レポートを生成します。

デプロイフェーズは、Qlik Cloud へのビルドモードと QVF エクスポートモードで実行されます。ローカル専用モードでは、QV2QS は変換された出力を Qlik Cloud に接続せずにディスクに書き込みます。レポートフェーズはすべてのモードで実行されます。

## 変換モード

QV2QSは3つの変換モードをサポートしています。ウィザードのセットアップステップで、または対応するCLIフラグを使用して、モードを選択します。

| モード | CLIフラグ | Qlik Cloud が必要です | 出力 | デプロイフェーズ |
| --- | --- | --- | --- | --- |
| Qlik Cloud へ構築 | *(既定)* | 可 | アプリがテナントにデプロイされました | はい — アプリを作成し、メディアをアップロードし、ビルドし、シートを公開します |
| QVFをエクスポート | `--exportQvf` | 可 | ディスク上のQVFファイル | はい — Qlik Cloudでアプリを構築し、QVFとしてエクスポートし、その後、クラウドアプリを削除します |
| ローカルのみ | `--unbuildOnly` | 不可 | ディスク上のビルドフォルダーと変換レポート | 不可 |

Qlik Cloud へのビルドは、移行に推奨されるモードです。QVFのエクスポートは、共有したり別のテナントにインポートしたりするためのポータブルファイルを作成するのに役立ちます。ローカルのみモードは、評価およびレビューを目的としています。ローカルのみの制限の詳細については、以下のセクションを参照してください。

情報メモ

ユーザーインターフェースはデフォルトで固定キャンバスモード、リロード有効、および自動バイナリ有効になっています。CLIはデフォルトで動的グリッドモード、リロード無効、および自動バイナリ無効に設定されています。ウィザードからCLIに移行する際は、ウィザードの動作に合わせるために、これらのフラグを明示的に指定してください。引数とデフォルト値の完全なリストについては、[引数リファレンス](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/command-line-interface/argument-reference.htm)を参照してください。

## ローカルのみモード

ローカル専用モード (`--unbuildOnly`) は、Qlik Cloud に接続せずに Parse、Convert、Write、Report の各フェーズを実行します。テナントまたはAPIキーは不要です。QV2QS は、完全な変換レポート、エグゼクティブサマリー、およびビルド出力フォルダーをディスク上に生成します。

### ユース ケース

* 移行アセスメント — ローカル専用モードを実行して、変換レポート、エグゼクティブサマリー、オートメーションスコア、および式に関する検出結果を、Qlik Cloudへのアクセスを必要とせずに生成します。テナントの認証情報を設定する前に、QVW資産全体にわたる変換品質を評価してください。
* 展開前レビュー — クラウド展開にコミットする前に、生成された出力 (ロード スクリプト、オブジェクト定義、変数、ディメンション) を確認します。変更管理プロセスを持つ組織は、出力を中間成果物としてレビューできます。
* オフラインまたは制限された環境 — QVWファイルをホストしているマシンが外部インターネットアクセスを持たない場合、ローカルのみモードを実行して、変換レポートをローカルで生成します。変換されたアプリを展開するには、QVWファイルをQlik Cloudにアクセスできるマシンにコピーし、接続されたマシンからBuild to Qlik CloudモードでQV2QSを実行します。

### 制限事項

デプロイフェーズは、`qlik app build`単独では実行しないいくつかの操作を処理します。ローカルのみモードを実行し、その後`build/`フォルダーをスタンドアロンの[qlik-cli](https://qlik.dev/toolkits/qlik-cli/)インストールで手動でデプロイすると、以下のギャップが生じます。

* メディアファイルがアップロードされていません。背景画像とボタン画像は`images/`フォルダーに抽出されますが、`build/`フォルダーには含まれません。`qlik app build` コマンドはメディアファイルを処理しません。デプロイされたアプリでは、すべての背景画像とボタン画像が表示されなくなります。
* シートとオブジェクトの背景参照は解決されません。QV2QS は、クラウドアプリIDを使用して、デプロイフェーズ中にシートとオブジェクトのJSONファイルに背景画像のURLを挿入します。ローカルビルドの出力には、背景画像の参照が含まれていません。デプロイされたアプリでは、シートとオブジェクトの背景は表示されません。
* ボタン画像のURLにはプレースホルダー文字列が含まれています。ローカルビルド出力のボタン画像は、解決済みのメディアURLの代わりに内部プレースホルダー値を使用します。Qlik Sense エンジンはプレースホルダー文字列を解釈できません。ボタン画像は壊れて表示されます。
* 代替状態は作成されません。別の状態名が、`build/`フォルダーの外にある`cloud/alternate_states.json`に書き込まれます。`qlik app build` コマンドは代替ステートを処理しません。デフォルト以外の状態を参照するオブジェクトは、正しく表示されない可能性があります。
* シートは公開されていません。`qlik app build`コマンドは、アプリの所有者のみに表示される個人オブジェクトとしてシートを作成します。QV2QS はデプロイフェーズ中にシートをベースシートとして公開します。共有スペースでは、シートが手動で公開されるまで、他のユーザーはシートを見ることができません。

情報メモ

メディアのアップロード、バックグラウンドの解決、代替状態の作成、およびシートの公開を含む完全な展開には、ローカルのみモードの代わりに、Qlik CloudへのビルドモードまたはQVFのエクスポートモードを使用してください。

## ソースファイルの安全性

QV2QSは、ソースのQVWまたはQVFファイルの内容を変更しません。抽出フェーズ中に、QV2QS は QlikView Desktop を介してソース ドキュメントを開き、システムの一時フォルダーに一時コピーを保存します。QV2QSはその後、オリジナルを閉じ、一時コピーからPRJフォルダーを生成します。PRJ生成が完了した後、QV2QSは結果の`-prj` フォルダーをソースファイルと同じディレクトリにコピーし、一時コピーを削除します。ソースファイルの隣に`-prj`フォルダーが既に存在する場合、QV2QSはそのフォルダーを新しく生成されたバージョンに置き換えます。他のすべての変換出力は、`--outputDir`によって指定された個別の出力ディレクトリに書き込まれます。

QlikView Desktop は、一時コピーの作成中に、ソースドキュメントにファイルロックをかけます。QlikView Desktop でアクティブに開かれている、または QlikView Server によって提供されているファイルに対して QV2QS を実行すると、ファイルロックの競合や PRJ 生成の失敗を引き起こす可能性があります。共有ネットワークドライブ上のファイルも、同じ競合を引き起こす可能性があります。「`-prj`」フォルダーをネットワーク共有または読み取り専用ディレクトリに書き戻すことも失敗する可能性があります。

本番環境へのいかなるリスクも回避するため、必ずソースドキュメントのコピーで作業してください。次の手順に従ってください:

1. QV2QSが実行されているマシン上のローカルの作業フォルダーに、QVWまたはQVFファイルをコピーします。
2. QV2QS を、オリジナルではなく、コピーしたファイルに向けてください。
3. 変換を開始する前に、実行中のQlikView Desktopインスタンスをすべて閉じてください。QV2QS は QlikView Desktop への占有アクセスを必要とします。

警告メモ

QV2QS を QlikView Server ドキュメントフォルダー、本番ネットワーク共有、または QlikView Desktop で開いているファイルに対して直接実行しないでください。ソースドキュメントは常にローカルコピーを使用してください。

## 標準的なタイミング

QV2QSは高速性を追求して設計されています。完全なパイプラインは、数時間ではなく数分で完了します。以下の表は、単一のアプリ変換にかかる一般的な期間を示しています。

| フェーズ | 標準的な期間 | メモ |
| --- | --- | --- |
| 抽出 (PRJ生成) | 5～15秒 | QVWの複雑さによります。PRJフォルダーが既に存在する場合、スキップされます。 |
| 解析 + 変換 + 書き込み | 30秒以内 | 中核となるXMLからJSONへの変換。数百のオブジェクトを持つ複雑なアプリケーションを処理します。 |
| デプロイ (クラウド ビルド) | 1～3分 | テナントでのアプリ作成、メディアアップロード、アプリビルドが含まれます。 |
| リロード | 様々 | データ量、データ ソースの待機時間、およびテナントのリソースによって異なります。一般的な QVW のバイナリ ロードは 1 分未満で完了します。 |

クラウド展開とデータのリロードを伴う単一アプリの変換は、エンドツーエンドで通常2～5分で完了します。ローカルのみの変換 (`--unbuildOnly`) は30秒未満で完了します。

バッチモードでは、QV2QSは複数のプロジェクトを並行して変換します。合計バッチ時間は、プロジェクト数をワーカー数で割った値に比例します。4つのワーカーを使用する20個のアプリのバッチの場合、ローカル変換フェーズにかかる単一アプリの所要時間の約5倍に加えて、クラウド展開時間も想定してください。

## 出力フォルダー構造

`--outputDir` 引数は出力ルートを指定します。QV2QS は、出力ルート内に、QVWファイル (またはPRJフォルダー) にちなんで名付けられたサブフォルダーを作成します。プロジェクトのすべての変換出力は、そのサブフォルダーに書き込まれます。2つのQVWファイルが同じ名前を共有している場合、QV2QSは競合を避けるために`_2`、`_3`、およびそれ以降の番号を追加します。この動作はバッチモードと一致し、各プロジェクトも専用のサブフォルダーを受け取ります。

```
<outputDir>/
  <ProjectName>/
    build/
    images/
    reports/
    logs/
    cloud/
    qvf/
```

QV2QS は、出力フォルダーがまだ存在しない場合に、そのフォルダーを作成します。もし、同じQVWの以前の実行からそのフォルダーが存在する場合、QV2QSはそのフォルダーを再利用します。フォルダー内の既存のログファイルは、ログのクリーンアップが有効になっていない限り保持されます。出力ディレクトリは、いずれかのソースディレクトリと同じ、またはその親であってはなりません。QV2QS は、変換を開始する前に出力パスを検証し、パスが重複している場合はエラーを報告します。プロジェクトのサブフォルダーには以下が含まれています。

| フォルダー / ファイル | コンテンツ |
| --- | --- |
| `build/` | Qlik Sense アプリの `qlik app build` 向け構造。`config.yml` (ビルド マニフェスト)、`script.qvs` (ロード スクリプト)、`app-properties.json`、`connections.yml` (データ接続)、`dimensions.json` (マスターディメンション)、`measures.json` (マスターメジャー)、`variables.json`、および各シートと視覚化につき1つのJSONファイルを含む`objects/`サブフォルダーが含まれています。 |
| `images/` | コンテンツハッシュによって重複排除された抽出済みメディアファイルおよび`backgrounds.json` (バックグラウンドマニフェスト)。 |
| `reports/` | `executive_summary.json`、`executive_summary.html`、およびExcel変換レポート (`*_conversion_report_*.xlsx`) (有効な場合)。 |
| `logs/` | 実行ごとの構造化ログファイル。 |
| `cloud/` | `cloud_state.json` (アプリID、メディアハッシュ、シートIDマッピング、タイムスタンプ) および `alternate_states.json`。クラウド展開中に作成されました。 |
| `qvf/` | エクスポートされたQVFファイル (`--exportQvf` が使用されたときに作成されます)。 |
| `.qv2qs_source` | どのQVWがサブフォルダーを生成したかを記録するマーカーファイル。QV2QS は、名前の衝突を検出し、以降の実行で正しいフォルダーを再利用するために、マーカーを使用します。 |

ヒント メモ

変換が完了した後、ウィザードから直接出力フォルダーを開きます。

## 変換後

変換が完了したら、優先度別にグループ化された以下の項目について作業を進めてください。

公開前に修正

1. `reports/`サブフォルダーにあるExcel変換レポートを開き、Follow-up\_Objectsワークシートを確認します。最初にエラーとマークされたすべての項目（変換に失敗したオブジェクト）を修正し、次にプレースホルダー（再構築が必要なオブジェクト）、そして調整が必要（部分的に変換されたオブジェクト）を修正してください。
2. 分析ワークシートで、マクロ参照、セクション アクセス の使用状況、および手動での対応が必要となる可能性のある ロード スクリプト パターンを含む分析結果を確認します。
3. 式が正しく評価されることを確認します。QV2QS は変換中にセット分析の引用符の問題を自動的に修正します。QlikView専用関数(`GetCurrentField()`, `MsgBox()`)を使用しており、手動での書き換えが必要な計算ディメンション、条件付き色付け、および式を確認してください。
4. 余分なディメンションまたはメジャーが代替コレクションに移動されたオブジェクトについては、Overflow\_Actionsワークシートで確認してください。

公開前に確認する

1. 変換されたアプリをQlik Senseで開き、シートのレイアウト、オブジェクトの位置、および背景画像が期待どおりに表示されることを確認します。
2. タブコンテナナビゲーション (ボタンストリップまたはタブ付きコンテナ) がコンテンツ領域間を正しく切り替えることを確認します。
3. 軸グループを使用するチャートで、ドリルダウンとサイクリック グループのサイクリング動作をテストします。
4. 表示条件によってオブジェクトが期待どおりに非表示になったり表示されたりすることを確認します。
5. リストボックスとテーブルのソート順、特に日付形式のフィールドについて確認してください。

ポーランド語

1. フォント、色、またはオブジェクトの配置を、Qlik Sense アプリエディタで必要に応じて調整します。レイアウトの配置に関するガイダンスについては、[変換レイアウト設定](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)を参照してください。

レポートの内容の詳細については、[コンバージョンレポート](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/conversion-results/conversion-report.htm)を参照してください。

## 詳細はこちら

* [クイックスタート](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/getting-started/quick-start.htm)
* [ユーザーインターフェース](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/user-interface/index.htm)
* [コマンドラインインターフェース](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/command-line-interface/index.htm)
* [変換レイアウト設定](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/conversion-layout-settings/index.htm)
* [コンバージョンの成果](https://help.qlik.com/ja-JP/migration/Content/Qv2qsMigration/conversion-results/conversion-outcomes.htm)