Qntrlのサンドボックスの利用ガイド

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

早期アクセス

サンドボックスは、すべてのユーザーに対して有効になっているわけではありません。試用をご希望の場合は、早期アクセスについてサポートチームにメールでお問い合わせください。

理解しておくべき主な用語

サンドボックス	本番環境のテスト用クローンです。
環境	1つ以上のインスタンスを格納するコンテナーです。サンドボックスでは、さまざまなレベルのテスト用に複数の環境を作成できます。種類には、開発、ステージング、本番があります。
インスタンス	プロジェクトを構築、テストするための、環境内の特定のワークスペースです。
プロジェクト	プロセスデータと設定の集合です。1つのインスタンスにつき1つのプロジェクトです。1つの実装に複数のプロジェクトが含まれる場合があります。
親プロジェクト	現在のプロジェクトの変更がデプロイされる、次の上位環境にあるプロジェクトです。
リポジトリ	保存されたすべての設定と変更を保管する領域です。
本番環境	ユーザーが現在システムを操作し、利用している稼働中の環境です。
デプロイログ	デプロイされた変更のデータです。元に戻すためのオプションも含まれます。
ライブキュー	デプロイ要求が承認または実行を待つキューです。
同期	デプロイ前に、環境間でデータの整合性を保つために変更を更新することです。

サンドボックスワークフローの概要

環境の作成：テスト用スペースを設定します。
インスタンスの作成：テスト用のサンドボックスインスタンスを設定します。
プロジェクトの作成と関連付け：既存のプロジェクトを関連付けるか、新しいプロジェクトを作成します。
変更の実施：ワークフロー、フォーム、スクリプトなどを変更します。
変更の生成と検証：変更を保存する前に、差分を確認して検証します。
インスタンスとの同期：デプロイ前に、環境間で変更内容を整合させます。
変更のデプロイ：変更をキューに追加し、上位の環境または本番環境にデプロイします。

ステップ 1 - 環境の設定

環境の種類

サンドボックスは複数環境モデルとして構築されており、本番環境に直接デプロイするシンプルな用途から、開発やテスト用に複数の環境を使用する複雑な構成まで対応しています。

本番環境：最終的な稼働環境です。サンドボックスの設定時に、標準インスタンスとともに自動で作成されます。編集や削除はできず、新しいインスタンスも追加できません。
ステージング環境：広範囲かつ継続的なテストに使用します。デプロイ後もプロジェクトの関連付けは維持されます。
開発環境：新機能の開発とテスト専用の環境です。デプロイ後にプロジェクトの関連付けは解除されるため、次のテスト段階で新しいプロジェクトを関連付けることができます。

開発環境またはステージング環境は、任意の順序で作成できます。
サンドボックス組織の初期設定時に、少なくとも1つの環境を作成する必要があります。

新しい環境の作成

［（設定）］→［詳細設定］→［サンドボックス］に移動し、［開発システム］をクリックします。
次に［新しい環境］をクリックし、以下の環境情報を追加します。

［種類の選択］：［ステージング］または［開発］を選択します。詳細は環境の種類のセクションを参照してください。
［システム環境名］：環境の名前を入力します。
［説明（任意）］：簡単な説明を追加します。

［新しいシステム環境を作成］をクリックします。

新しい環境が本番環境の下に表示され、インスタンスの追加やプロジェクトの関連付けができる状態になります。同様に、複数の環境を作成できます。

最大5つの環境を作成できます。
作成後に環境を編集または削除することはできません。

ステップ2：インスタンスの作成と管理

サンドボックスのインスタンスは、プロジェクトを関連付けてテストする場所です。インスタンス内で行った変更は、対応する関連付け済みプロジェクトに保存されます。

インスタンスを作成するには、次の手順を実行します。

環境内で［インスタンスの追加］をクリックし、新しいインスタンスの情報を入力します。

［インスタンス名］：インスタンスの名前を入力します。
［説明（任意）］：説明を追加します。
［プロジェクトの関連付け］

関連付けるプロジェクトの有無を選択して、インスタンスを作成します。
ドロップダウンから既存のプロジェクトを選択するか、［新しいプロジェクト］をクリックして新しく作成します。詳細はこちら。

［インスタンスの作成］をクリックします。

新しいプロジェクトの作成（インスタンス作成時の任意設定）

インスタンスの作成時に新しいプロジェクトを作成する場合は、

以下のプロジェクト情報を入力します。

［プロジェクト名］：プロジェクトの名前を入力します。
［説明（任意）］：説明を入力します。
［リポジトリのブランチ名］：バージョン管理システムのブランチ名を指定します。
［プロジェクトメンバー］：プロジェクトにアクセスできるメンバーを追加します。
［親プロジェクト（任意）］：該当する場合は、親プロジェクトを選択します。複数階層の環境を使用するサンドボックスでのみ適用されます。

［新しいプロジェクト］をクリックします。

プロジェクトが作成され、［プロジェクト］タブのプロジェクト一覧に表示されます。

プロジェクトの関連付けと関連付け解除

1つのインスタンスに同時に関連付けられるプロジェクトは1件のみです。

プロジェクトをインスタンスに関連付けるには、インスタンス内の［関連付け済みプロジェクト］の横にあるドロップダウン矢印をクリックします。一覧から目的のプロジェクトを選択します。

プロジェクトとインスタンスの関連付けを解除するには、関連付け済みプロジェクト名の横にある削除アイコンをクリックします。

プロジェクトを切り替えると、現在のプロジェクトのデータが新しく選択したプロジェクトのデータに置き換えられます。この操作は、インスタンスが「準備完了」または「待機中」の状態の場合にのみ実行でき、「開発中」の状態では実行できません。

インスタンスの編集

インスタンスを編集するには、操作メニューアイコンをクリックして、［インスタンスの編集］を選択します。

必要に応じて名前または説明を更新し、［インスタンスの更新］をクリックして変更を保存します。

制限事項

1つのサンドボックスに最大7件のインスタンスを作成できます。各インスタンスは異なるプロジェクトに関連付けることができます。
1つのサンドボックスインスタンスで同時に有効にできるプロジェクトは1件のみです。
関連付けられたインスタンスにアクセスできるのは、プロジェクトのメンバーと管理者のみです。
プロジェクトを関連付けると、本番ポータルは「読み取り専用」モードに切り替わります。変更するには、設定で「読み取り専用」モードを無効にします。読み取り専用モードの有効化と無効化の詳細。
同じインスタンス内でプロジェクトを切り替えるには、まず現在のプロジェクトの関連付けを解除してから、新しいプロジェクトを関連付けます。

ステップ3：インスタンスへのアクセスと作業

インスタンスの状態

準備完了：インスタンスは作成済みですが、プロジェクトは関連付けられていません。
待機中：インスタンスにプロジェクトが関連付けられ、変更が保存されています。
開発中：プロジェクトは関連付けられていますが、変更はリポジトリーに保存されていません。この状態ではプロジェクトを切り替えられません。
インポート中：データのインポートが進行中です。インスタンスの状態は「インポート中」と表示されます。
インポート失敗：データのインポートに失敗しました。

「失敗」状態のインスタンスでは、再試行オプションを利用できます。

インスタンスでのプロセスのインポート

インスタンスを作成してプロジェクトを関連付けると、データのインポートが開始されます。インポートが完了するまで、インスタンスにはアクセスできず、状態はインポート中と表示されます。
［インスタンスにアクセス］ボタンは、インポートの完了後にのみ有効になります。
［インポート中］をクリックすると、インポートの進行状況を確認し、ログを表示できます。インストールが完了したら、［閉じる］をクリックします。

現在の本番環境の複製が作成されます。複製されたボードは含まれますが、カードデータは含まれません。その後、インスタンスは待機中状態に切り替わります。

インスタンスへのアクセス

インポート処理が完了すると、［インスタンスにアクセス］ボタンが有効になります。
［インスタンスにアクセス］ボタンをクリックします。この操作により、インスタンスポータルが開き、保存済みの変更と未保存の変更の両方のセクションが表示されます。初期状態では、未保存の変更セクションは空です。

複製されたポータルで作業し、必要な変更を加えることができます。

異なる環境間でスクリプトや関数を使用する場合、ドメイン固有の値やIDをハードコードする必要が生じることがよくあります。これを簡単にするには、ConfigStoreを使用してパラメーターを作成し、各環境に動的な値を割り当てます。詳細については、［ConfigStore］タブを参照してください。

サンドボックス固有の動作の理解

サンドボックス環境で作業する場合、特にスクリプト、ID、ユーザーに関する一部の動作は本番環境と異なります。

サンドボックスでのスクリプトとIDの処理

IDのハードコードの回避：レイアウトIDやプロジェクトIDなどのIDを、URLやスクリプトに直接記述しないでください。
代わりに、Config Storeを使用してID値を動的に渡します。
スクリプト内でID（レイアウトIDやZValueなど）を参照して公開した場合：

スクリプトがサンドボックスに移行されると、その本番環境のIDは対応するサンドボックスのIDに自動的に置き換えられます。
このIDマッピングは、次の処理中に自動的に行われます。

サンドボックスの作成
上位環境へのデプロイ
本番環境からの同期（逆同期）

適用対象：

CodeXスクリプト
クライアントスクリプト
カスタム関数

例：
スクリプトにレイアウトIDが含まれていて、そのスクリプトをサンドボックスに移動すると、システムにより元のIDがサンドボックスで作成されたレイアウトIDに置き換えられます。

サンドボックスでのユーザーの利用可否

リンクされたプロジェクトに関連付けられているユーザーのみがサンドボックスに移行されます。
チームと役割は引き継がれますが、それらの役割内でプロジェクトに固有のユーザーのみが利用可能になります。

例：
組織に4人のユーザーがいても、プロジェクトに含まれるのが2人だけの場合、全員が同じチームに所属していても、その2人のみがサンドボックスに表示されます。

サンドボックス環境では、ユーザーを直接追加できません。
ユーザー固有の変更が必要な場合は、本番環境で行う必要があります。

ステップ4：インスタンスでの変更の生成

ポータルで変更を行うと、［変更の生成］オプションが［未保存の変更］セクションで有効になり、これらの変更が最初に表示されます。

変更を行った後にのみ、［変更の生成］ボタンが有効になります。

変更を生成するには：

インスタンスに移動し、［未保存の変更］をクリックします。または、メインポータルから、プロジェクトに関連付けられているインスタンスに移動してアクセスします。
変更が発生すると、インスタンスの状態が「開発中」に変わり、ユーザーはプロジェクトの関連付け解除や切り替えができなくなります。
［変更の生成］をクリックします。変更の生成中は、ポップアップウィンドウにログが表示されます。
この処理中に追加の変更が行われないよう、プロジェクトに関連付けられているインスタンスはロックされます。

すべてのログが完了ステータスになったら、ポップアップを閉じて、［未保存の変更］タブに一覧表示された変更を確認します。各変更には、最後に変更したユーザーの名前が含まれます。

［未保存の変更］タブでは、保存済みのプロジェクトデータと現在のインスタンスデータの差分が強調表示されます。

作業中に右上隅の［変更の生成］ボタンを再度クリックして、継続的に変更を生成できます。

制限事項

差分の生成時、以下の詳細は取得されません。

ビジネスルール条件の変更
条件付き項目の条件の変更
公開フォームでの背景やロゴの変更
Webhookでの、認証情報、メソッド、ブリッジでの実行、JSON形式のパラメーター、その他のパラメーターなどの項目の変更
カスタム関数での、戻り値の種類や引数などの項目の変更

ステップ5：リポジトリーへの保存

変更を生成して確認したら、リポジトリーに保存する必要があります。サンドボックスのリポジトリーオプションでは、プロジェクト設定と変更を保存するための一元的な場所を利用できます。

バージョン管理、環境間の同期、保存済みバージョン間の差分表示などのメリットがあります。保存されるのは設定データのみのため、更新内容の安全性を保ち、システム設定に集中できます。

変更をリポジトリーに保存するには：

まず、［リポジトリーに保存］をクリックし、ポップアップで、参照用にプロジェクトで行った変更内容を説明するメッセージを入力します。
確認のため、もう一度［リポジトリーに保存］をクリックします。

変更ログを含むポップアップが表示されます。正常に完了したら、［閉じる］をクリックします。

保存した変更は、メッセージ、作成者、日付、ステータスなどの詳細とともに、［保存済みの変更］リストに反映されます。

保存後、検証のため、［保存済みの変更］セクションで、［差分を表示］を［差分］列でクリックすると、以前に保存した変更と現在のバージョンの差分を確認できます。

保存後の操作

変更はプロジェクト設定時に作成されたリポジトリーに保存され、サンドボックス環境に反映されます。そこで、ステータスと行われた変更数を確認できます。
以前に保存した変更と現在のバージョンの差分は、［差分を表示］をクリックして確認できます。
変更をリポジトリーに保存すると、関連付けられているインスタンスのロックが解除され、ステータスがアイドルに変わります。これにより、必要に応じて現在のプロジェクトの関連付けを解除し、新しいプロジェクトを関連付けることができます。
本番ポータルで、［（設定）］→［詳細］→［サンドボックス］→［開発システム］に移動します。変更数を確認し、［差分を表示］をクリックして、インスタンスに関連付けられているプロジェクトと本番データを比較します。

ステップ6：変更の同期と上位環境／本番環境への送信

同期の概要

同期とは、上位環境の変更を現在の環境内のインスタンスに取り込むことです。これにより、変更を次の環境に展開する前に、インスタンスの整合性を確保できます。

サンドボックス環境では、設定に応じて、構造化された順序で変更を同期して展開する必要があります。これにより、環境間の一貫性を確保し、競合やデータ損失を防げます。

ベストプラクティス

展開前の同期は任意ですが、データ損失や競合を防ぐため強く推奨されます。これを省略すると、環境間で不整合が生じる可能性があります。

サンドボックス構成に複数の環境（ステージング、UATなど）が含まれる場合は、まず次の上位環境と変更を同期する必要があります。この場合、変更を本番環境に直接送信することはできません。
既定の本番環境以外に環境が1つだけ含まれる構成の場合、変更は本番環境にのみ直接送信できます。
ボタンラベルには、対象環境が動的に反映されます。
本番環境の場合：［本番環境と同期］と［本番環境に送信］。
その他の環境の場合：［インスタンスと同期］と［[環境名]に送信］。