XLSForm の基本—ArcGIS Survey123

XLSForm はフォームの作成を簡素化するオープンスタンダードです。作成作業は、スプレッドシートを使用して、判読可能な形式で行われます。 XLSForm の詳細については、https://xlsform.org/ をご参照ください。 Survey123 は、XLSForm 標準のほとんど (すべてではありません) の機能をサポートしています。

XLSForm 準拠のスプレッドシートを作成するには、多くのオプションがあります。 Microsoft Excel が最もよく使用されますが、Kingsoft Spreadsheets、Google Sheets、OpenOffice Calc といったその他のオプションもあります。さらに、ArcGIS Survey123 で使用できるように XLSForm スプレッドシートをエクスポートするオンラインの XForms ビルダーもあります。

フォームの作成に役立つように、ArcGIS Survey123 には Survey123 Connect デスクトップツールが含まれています。このツールは XLSForm 作成ツールと連動して XLS ファイルを作成します。 Survey123 Connect では、XLSForm ファイルの作成または編集時にプレビューを表示し、フォームを ArcGIS Online および ArcGIS Enterprise に公開して、データ収集のためのフォームの仕様に基づいてフィーチャレイヤーを作成することができます。 ArcGIS Survey123 Connect は Windows で使用できます。

ArcGIS にフォームを公開した後は、Survey123 Web サイトを使用して、ArcGIS 組織サイトのメンバーとフォームを共有できます。また、Survey123 フィールドアプリを介して収集したデータのマップやテーブルを解析し、調査結果をエクスポートすることもできます。

このトピックの目的上、ここでは ArcGIS Survey123 Connect と Microsoft Excel を使用してフォームを作成すると想定します。

通常、各 Excel ワークブックには、survey と choices という 2 つのワークシートがあります。 3 つ目のワークシート (settings) についても以下で説明します。ワークシートには、フォームが機能するために存在しなければならない一連の必須の列があります。さらに、各ワークシートには、フォーム内の各エントリの動作を詳細に制御できるようにする一連のオプションの列もあります。必須の列については、どのエントリもその列に値が存在する必要がありますが、オプションの列は空白のままでもかまいません。必須とオプションのどちらであっても、Excel ワークブックに追加された列は任意の順序で表示できます。オプションの列を省略し、任意数の行を空白にしておくことができます。すべての .xls ファイル形式は無視されるので、分割線、陰影、その他のフォント形式を使用してフォームを読みやすくできます。

survey ワークシート

このワークシートには、フォーム全体の構造が示されます。ここには質問の完全なリストと、フォームでの表示方法に関する情報が格納されています。通常は、1 行ごとに 1 つの質問を表しますが、下記に示すその他機能をフォームに追加して、ユーザーエクスペリエンスを向上させることができます。

survey ワークシートには、type、name と、label または hint の 3 つの必須の列があります。

type 列では、追加する XLSForm 質問のタイプを指定します。この列で可能な質問タイプには、十分に定義されたリストがあります。
name 列は、質問に対する回答が保存されるフィーチャレイヤーのフィールドの名前を決定します。この列では、スペースや特殊文字を使用することはできません。各レイヤーですべての質問の名前が一意でなければなりません。
label および hint 列には質問のテキストが格納されます。このテキストがフォームに表示されます。質問には、少なくとも 1 つのラベルまたはヒントを指定する必要があります。警告メッセージが表示されないようにするには、ラベルを指定することをお勧めします。これらの列では、スペースや特殊文字を使用できます。または、翻訳の列を使用できます。ラベルとヒントは、限られた HTML コードと、調査内で別の質問の回答に置き換えられる変数もサポートしています。詳細については、「メモ」をご参照ください。

survey ワークシートの列の概要については、「survey ワークシートの列」をご参照ください。

choices ワークシート

このワークシートは、複数の選択肢の質問の回答の選択肢を指定するために使用します。各行が回答の選択肢を表しています。リスト名が同じである回答の選択肢は、関連する選択肢のセットの一部だと見なされ、1 つの質問に対してまとめて表示されます。これにより、一連の選択肢を複数の質問に再利用することもできます (yes/no の質問など)。

choices ワークシートには、list name、name、label という 3 つの必須の列があります。

list name 列では、関連する回答の選択肢のセットをグループ化できます。リスト名が同じである選択肢は、質問に対する一連の回答として表示されます。
name 列では、ArcGIS で維持される値を指定します。 name 列の値に特殊文字を含めることはできません。選択リストに重複する選択肢名を含めることはお勧めしません。重複する選択肢名の詳細については、「複数の選択肢の質問」をご参照ください。
label 列には、フォームの表示とまったく同じ状態で回答の選択肢が示されます。または、ラベル翻訳の列を使用できます。

Excel でフォームを作成する場合、使用する構文が正確である必要があります。たとえば、choices ではなく Choices または choice と記述した場合、フォームは機能しません。

settings ワークシート

settings ワークシートはオプションで、フォームをさらにカスタマイズできます。フォームの編集時に表示されるタイトル、完成した各フォームを一意に識別するためのインスタンス名、調査の一意のバージョン識別子などをカスタマイズできます。詳細については、「設定」をご参照ください。

補助ワークシート

Survey123 テンプレートには、フォームで使用できるプロパティ、演算子、および関数を含むワークシートが含まれています。これらのワークシートは、調査および設定ワークシートのドロップダウンリストやその他のデータの整合チェックのルールを設定するためにも使用されます。データの整合チェックを正常に動作させるには、補助ワークシートの内容を変更しないことをお勧めします。

質問タイプ

XLSForm は多数の質問タイプをサポートしています。たとえば、店舗の名前と位置を収集するには、次のように記述します。

次の表は、XLSForm の type 列に入力できる質問、質問で受け入れられる入力、フォームの公開時にその質問に関連する ArcGIS フィーチャレイヤーで作成されるフィールドタイプを示しています。調査の作成者は、これらの質問タイプの多くのフィールドタイプを変更できます。フィールドタイプの詳細については、「Esri カスタム列」をご参照ください。


質問タイプ	回答の入力	デフォルトのフィールドタイプ
integer	整数の入力。	esriFieldTypeInteger
decimal	小数の入力。	esriFieldTypeDouble
range	指定範囲の数の入力。	esriFieldTypeInteger
text	フリーテキストの回答。	esriFieldTypeString
select_one list_name	1 つだけ回答を選択できる複数の選択肢の質問。 list_name を選択リストの名前に置き換えます。フィールドタイプは変更できますが、式で使用する場合、選択名は常にフィールドアプリ内で文字列として処理されます。	esriFieldTypeString
select_multiple list_name	複数の回答を選択できる複数の選択肢の質問。 list_name を選択リストの名前に置き換えます。フィールドタイプは変更できます。式で使用する場合、選択名は常にフィールドアプリ内で文字列として処理されます。	esriFieldTypeString
rank list_name	ランキングの質問。選択肢のリストのランク順を決定します。 list_name を選択リストの名前に置き換えます。フィールドタイプは変更できます。式で使用する場合、選択名は常にフィールドアプリ内で文字列として処理されます。	esriFieldTypeString
note	画面にテキストが表示され、入力は行えません。非表示の計算も表示できます。	esriFieldTypeString
geopoint	単一の GPS 座標を収集します。フィールドタイプは変更できません。	esriFieldTypeGeometry
geotrace	マップ上のラインを収集します。フィールドタイプは変更できません。	esriFieldTypeGeometry
geoshape	マップ上のポリゴンを収集します。フィールドタイプは変更できません。	esriFieldTypeGeometry
date	日付の入力。	esriFieldTypeDate
time	時間の入力。	esriFieldTypeString
dateTime	日時の入力を受け入れます。	esriFieldTypeDate
image	写真を撮影します。	Attachment
begin group	質問のグループを開始します。	該当なし
end group	質問のグループを終了します。	該当なし
begin repeat	一連の繰り返しの質問を開始します。	該当なし
end repeat	一連の繰り返しの質問を終了します。	該当なし
calculate	フォームの値に対して計算を実行します。このタイプの質問は非表示になっているため、フォーム上に表示されません。	esriFieldTypeString
username¹	ArcGIS Online または ArcGIS Enterprise にサインインすると、このフィールドにはアカウントのユーザー名が自動的に設定されます。このタイプの質問は非表示になっているため、フォーム上に表示されません。	esriFieldTypeString
email¹	ArcGIS Online または ArcGIS Enterprise にサインインすると、このフィールドにはアカウントの電子メールアドレスが自動的に設定されます。このタイプの質問は非表示になっているため、フォーム上に表示されません。	esriFieldTypeString
hidden	フォームに表示されないフィールド。 bind::esri:fieldType 列と bind::esri:fieldLength 列を使用して、データスキーマを指定します。	esriFieldTypeString
barcode	バーコードをスキャンします。	esriFieldTypeString
start	調査の開始日時。	esriFieldTypeDate
end	調査の終了日時。	esriFieldTypeDate
deviceid	調査が取得された特定のデバイスを表す Survey123 によって生成された一意の ID。これはモジュールデバイスの IMEI (International Mobile Equipment Identity) と異なります。Survey123 が実行されるデバイスには IMEI がない場合があります。	esriFieldTypeString
audio	オーディオサンプルを記録します。	Attachment
file	デバイスにファイルをアップロードします。	Attachment

¹より柔軟なオプションは、pulldata("@property") 関数を使用して値を取得することです。「デバイスとユーザープロパティ」をご参照ください。

質問タイプのサンプルフォームには、ArcGIS Survey123 によってサポートされるすべての質問タイプが含まれます。これらの質問タイプが Survey123 Web デザイナーおよび Web アプリでどのように表されるかを確認するには、「クイックリファレンス」をご参照ください。

複数の選択肢の質問

XLSForm は select_one (1 つだけの回答を選択)、select_multiple (複数の回答を選択)、および rank (選択肢のリストを順序付け) の質問をサポートしています。複数の選択肢の質問を記述するには、Excel ワークブックに choices ワークシートを追加する必要があります。 select_one の質問の例を次に示します。

survey ワークシートの yes_no は、choices ワークシートの list name 列の yes_no と一致する必要があります。これにより、特定の質問に対して、回答の選択肢の正しいリストがフォームに表示されるようになります。

デフォルトでは、調査の公開時に、調査のフィーチャレイヤーに select_one 質問の選択肢がコード値ドメインとして追加されます。公開プロセス中にドメインの作成を無効化できます。詳細については、「公開オプション」をご参照ください。

select_one 質問の選択肢を変更して調査を再度公開すると、変更の概要が Survey123 Connect に表示され、フィーチャレイヤーのドメインにそれらの変更を適用するかどうかを決定できます。詳細については、「調査の更新」をご参照ください。

注意:

重複する選択肢名がある選択リストを使用する場合、次の制限があります。

重複する選択肢名は、select_multiple の質問ではサポートされていません。
重複する選択肢名は、多言語の調査ではサポートされていません。
jr:choice-name() 関数は、リスト内で最初の重複する選択肢のラベルを返します。
[受信トレイ]、[ドラフト]、[送信トレイ]、[送信済み]、または [概要] フォルダーから開くと、select_one の質問はリスト内で最初の重複する選択肢に戻ります。

次のように、複数回答を選択可能な、複数の選択肢の質問を追加することもできます。

デフォルトでは、これらの選択肢は choices ワークシートで設定された順序で表示されます。さらに、parameters 列に　randomize=true　と入力することで、選択肢の表示順をランダムにするオプションもあります。

注意:

select_multiple または rank の質問で収集されたすべての値は、カンマ区切りのリストとして保存されるため、選択リストの名前の列にカンマを使用しないでください。また、select_multiple および rank の質問は、select_one の質問により送信される名前とラベルではなく、選択の名前だけをフィーチャレイヤーに送信することに注意してください。

rank の質問の値は、ユーザーによって選択肢の順序が変更されるまで空のままです。デフォルト値が設定されている場合は、ユーザーによって選択肢の順序が変更されなければ、そのデフォルトの順序が適用されます。

select_multiple の質問に対する個々の回答は、selected-at 関数を使用して返すことができます。以下は、select_multiple の質問に対する最初の回答の名前値を返します。

selected-at(${species}, 0)

回答のラベルを送信するには、jr:choice-name 関数を使用できます。同じ select_multiple の質問に対する 2 番目の回答のラベル値を取得するには、以下を使用します。

jr:choice-name(selected-at(${species}, 1), '${species}')

その他の指定

複数の選択肢の質問では、希望する選択肢がリストにないときに、その他を選択するオプションを調査に含めることがあります。この場合、回答者にその他オプションを指定するように求めることができます。これを行うには、XLSForm で手動による方法または組み込みによる方法を使用できます。組み込みによる方法の方が手動による方法よりも短時間かつ簡単に構成できますが、いくつかの制約があります。

手動による方法

手動による方法では、other 選択肢の名前とラベル、およびその他の回答を収集するテキストの質問の名前とラベルを指定できるため、この方法が推奨されます。これらの名前とラベルの翻訳を入力できます。テキストの質問に制約と表示設定を適用したり、質問を必須に設定したりすることもできます。

最初に、choices ワークシート上の質問の選択リストに other 選択肢を追加します。リスト内の他の選択肢に指定したときと同様に、この選択肢の名前とラベルを指定します。次の例では、color 選択リストに other という名前の選択肢があります。

survey ワークシートで、その他の回答を収集するテキストの質問を追加します。 other 選択肢を選択したときにだけテキストの質問がたずねられるようにするため、条件式を追加します。次の例では、select_one 質問の回答が other の場合に other_color 質問がたずねられます。

多言語の調査の場合、質問と選択肢を翻訳できます。次の例では、survey ワークシート上で select_one 質問とテキストの質問の両方にフランス語とギリシャ語の翻訳が用意されています。

翻訳は choices ワークシート上の other を含む選択肢にも用意されています。

組み込みによる方法

この方法では、Survey123 Connect はその他の回答を収集するために自動的に other 選択肢を作成します。この方法を使用するには、survey ワークシートの [type] 列内の選択リスト名の後ろに「or_other」と入力します。質問の選択肢のリストに選択肢として [Other] が追加されます。選択肢として [Other] を選択すると質問として [Specify other] が表示され、ユーザーは回答を自由に入力できます。この回答を保存するために、_other の前に複数の選択肢がある質問の名前を付けた追加のフィールド (例: favorite_toppings_other) が Survey123 Connect によってフィーチャレイヤーに自動的に作成されます。次のようになります。

注意:

質問 [Specify other] のラベルは英語以外の言語では表示されません。

既存のフィーチャレイヤーから調査を作成する場合、質問 [Specify other] のフィールドは自動的に作成されないため、調査は公開されません。 _other の前に複数の選択肢がある質問の名前を付けて (例: favorite_toppings_other)、質問 [Specify other] 用のフィールドを手動でフィーチャレイヤーに作成する必要があります。

外部の選択リスト

select_one 質問と select_multiple 質問の選択リストは、外部の .csv ファイルに保存できます。これは、非常に長い選択リストや、Survey123 以外で管理される選択リストに最適です。 .csv ファイルには name 列と label 列が含まれる必要があります。 .csv ファイルは 2 つの方法で追加できます。調査の media フォルダーに手動で配置する方法か、ArcGIS でホストされている .csv ファイルにリンクする方法です。

外部の選択リストに質問を含めるには、質問タイプ (select_one_from_file または select_multiple_from_file) を入力し、その後に .csv ファイルの名前を続けます (例: select_one_from_file CoverType.csv)。ファイル名には大文字と小文字の区別があり、スペースを含めることはできません。

外部の選択リストを外部ファイルからの選択と混同しないようにします。外部ファイルからの選択では、選択肢を追加のワークシートに一覧表示する必要があります。

.csv ファイルをリンク

.csv ファイルを調査にリンクさせるには、次の手順を実行します。

.csv ファイルが ArcGIS Online または ArcGIS Enterprise でホストされており、調査と同じ共有権限を持っていることを確認します。
コンテンツのリンクを行う前に、調査が ArcGIS に公開されていることを確認します。
Survey123 Connect で、調査の [リンクされたコンテンツ] タブを参照し、[コンテンツのリンク] ボタンをクリックします。 [CSV] を選択し、リンクする .csv ファイルを参照して選択します。

Survey123 Connect で .csv ファイルを使用するには、[リンクされたコンテンツ] タブで、ダウンロードボタンを使用してファイルをダウンロードすることができます。これにより、.csv ファイルのコピーが調査の media フォルダーに配置されます。 Survey123 フィールドアプリでは、リンクされたファイルが調査と一緒に自動的にダウンロードされます。

調査の media フォルダーに .csv ファイルを手動で配置し、後から同じ名前の .csv ファイルを ArcGIS にアップロードして、それを調査にリンクさせると、調査内の .csv ファイルはリンクされたコンテンツで更新されます (リンクされたコンテンツの方が新しい場合)。

注意:

.csv ファイルに列ヘッダーがないか、ファイルの行の末尾に後続のカンマがある場合は、調査へのファイルのインポートが失敗します。

最適な結果を得るためには、UTF-8 文字エンコーディングを使用して .csv ファイルをエンコードしてください。 Microsoft Excel を使用して .csv ファイルを作成している場合は、CSV UTF-8 で保存します。

メタデータ

XLSForm には、メタデータの収集のために次のデータタイプオプションが用意されています。


メタデータタイプ	説明
start	調査の開始日時。
end	調査の終了日時。
username	ArcGIS Online または ArcGIS Enterprise にサインインしている現在のユーザーのユーザー名を記録します。このデータタイプは、入力は必要ありません。
email	ArcGIS Online または ArcGIS Enterprise にサインインしている現在のユーザーの電子メールアドレスを記録します。このデータタイプは、入力は必要ありません。
deviceid	調査が取得された特定のデバイスを表す Survey123 によって生成された一意の ID。これはモジュールデバイスの IMEI と異なります。Survey123 が実行されるデバイスには IMEI がない場合があります。

注意:

subscriberid、simserial、phonenumber という XLSForm メタデータエレメントはサポートされていません。

このメタデータをすべて収集するには、調査の最初に次のものを追加します。

上記のメタデータエントリは、ArcGIS Survey123 によって自動的に取得されます。これらはフォームに質問としては表示されませんが、調査の送信後に値が表示されます。

start または end タイプの質問を追加すると、ArcGIS Survey123 によって調査のフィーチャレイヤーが自動的に時間対応になります。この方法で、データの送信日付に基づいて調査のコンテンツをフィルタリングできます。 start および end エントリの追加は、フォームを開いた時点から完了済みのフラグが立った時点までの正確な経過時間を知りたい場合にも有用です。

ヒント

フォーム上の質問にヒントを追加して、質問の回答方法を手引きしたいけれど、ヒントを質問の一部にはしたくない場合があります。 XLSForm では質問にヒントを追加できます。 hint 列を追加してヒントのメッセージを追加します。次の例をご参照ください。

guidance_hint 列を使用して、質問にガイダンスヒントを追加することもできます。ガイダンスヒントは質問の回答方法を詳しく手引きするものですが、ヒントの横に表示されるガイダンスヒントのボタンをユーザーがクリックするまで非表示になっています。ガイダンスヒントは、質問に対するヒントがすでに用意されている場合のみ使用できます。

プレースホルダーテキスト

[body::esri:style] 列で placeholderText パラメーターを設定すると、入力した内容 (テキスト、整数、小数の質問、オートコンプリートの表示設定が指定された select_one の質問など) を受け入れる質問に対し、プレースホルダーテキストを提供することもできます。 placeholderText=@[hint] または placeholderText=@[guidance_hint] を使用すると、ヒントまたはガイダンスヒントは非表示になり、ヒントテキストは質問の入力エリアの中に配置されます。質問が空の場合、プレースホルダーテキストは入力エリアに表示されます。

注意:

ヒントは、begin repeat と begin group の質問ではサポートされません。

プレースホルダーテキストは、Survey123 Web アプリではサポートされていません。

テンプレートの更新

[高度なテンプレート] には Survey123 でサポートされているすべての XLSForm フィーチャが含まれており、Survey123 Connect の [新しい調査] ダイアログボックスで使用できます。このテンプレートは定期的に更新され、新機能が追加されて調査作成エクスペリエンスが強化されます。以前のバージョンのテンプレートも引き続き問題なく使用できますが、最新の変更を活用するために、最新の XLSForm テンプレートに既存の調査を更新することをおすすめします。

[XLSForm テンプレートの更新] ツールでは、調査の既存の XLSForm が最新バージョンの高度なテンプレートに更新されます。 [survey]、[choices]、[settings] の各ワークシートの内容を新しいテンプレートの対応する行と列にコピーすることで更新が行われます。新しいテンプレートだけでなく、外部選択を使用している場合は [external_choices] ワークシートにも追加した列がコピーされます。

ツールを実行するには、Python 環境を Survey123 Connect で構成する必要があります。詳細については、「Python の構成」をご参照ください。

更新する調査を Survey123 Connect で開きます。 [ツール]、[XLSForm テンプレートの更新] の順にクリックします。ツールが実行中であることを示すメッセージがダイアログボックスに表示されます。処理が完了すると、調査フォルダーの .xlsx ファイルが最新のテンプレートに更新され、フォームのプレビューが Survey123 Connect で再ロードされます。ツールの実行中にエラーが発生した場合は、既存の XLSForm が保持されます。

注意:

調査の XLSForm は .xlsx ファイルである必要があります。 [XLSForm テンプレートの更新] ツールは .xls ファイルに対して実行できません。

元の XLSForm の列、データ整合チェック、セルの形式、フォントスタイルが更新された XLSForm にも引き継がれていることを確認することをおすすめします。ツールによって、既存の XLSForm のバックアップとログファイルが C:\Users\<username>\ArcGIS\My Survey Designs\<surveyName>\debug\template_updater に作成されます。バックアップから調査を復元するには、.xlsx ファイルを template_updater フォルダーから調査のルートフォルダーにコピーします。既存の XLSForm を削除し、元の XLSForm と同じになるようにバックアップの名前を変更します。

注意:

各行の先頭列のセルの塗りつぶし色が更新されたテンプレートの行全体に適用されます。

多言語調査の場合、label::language (xx) や hint::language (xx) などのデフォルト言語列が更新されたテンプレートから除外されます。

このトピックへのフィードバック