Formeln

Sie können Formeln verwenden, um intelligentere Formulare mit ArcGIS Survey123 zu erstellen.

Auf vorherige Fragen muss in Formeln immer mit dem Format ${field_name} Bezug genommen werden.

Operatoren

Die folgenden Operatoren werden von Survey123 unterstützt:

Operator	Beschreibung	Beispiel
.	Die aktuelle Antwort	.=1
+	Addition	${question_one} + 4
-	Subtraktion	${question_one} - 4
*	Multiplikation	${question_one} * 4
div	Division	${question_one} div 4
=	Gleich	${price}=9.80
!=	Ungleich	${price}!=9.80
<	Kleiner als	${price}<9.80
<=	Kleiner als oder gleich	${price}<=9.80
>	Größer als	${price}>9.80
>=	Größer als oder gleich	${price}>=9.80
and	And	${price}>9.00 and ${price}<9.90
mod	Teilungsrest	${question_one} mod ${question_two}
or	Or	${price}=9.80 or ${price}=9.70

Funktionen

Die folgenden Funktionen werden in Survey123 unterstützt:

Funktion	Beschreibung	Beispiel
boolean(question, expression, or value)	Gibt "true" zurück, wenn der angegebene Wert nicht NULL ist. Es wird empfohlen, stattdessen "boolean-from-string()" zu verwenden. Vorsicht: In der Survey123-Web-App gibt diese Funktion immer "true" zurück. Alternativen finden Sie unter Leere Werte.	boolean(${question_one})
boolean-from-string()	Gibt "true" zurück, wenn die angegebene Zeichenfolge "true" oder "1" ist. Andernfalls wird "false" zurückgegeben.	boolean-from-string(${question_one})
coalesce(value1, value2)	Gibt den ersten nicht leeren Wert zurück. Diese Funktion unterstützt nur zwei Werte.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Gibt die Verbindung der Zeichenfolgenwerte zurück.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Gibt "true" zurück, wenn die angegebene Zeichenfolge eine Teilzeichenfolge enthält.	contains(${question_one}, 'red')
count(repeat)	Gibt die Menge der Antworten auf eine Frage innerhalb der Wiederholungen zurück. Weitere Informationen finden Sie unter Aggregatfunktionen. Hinweis: Bei Verwendung in der mobilen Survey123-App kann diese Funktion innerhalb oder außerhalb der Wiederholung platziert werden. Wenn die Funktion in der Survey123-Web-App verwendet werden soll, muss sie außerhalb der Wiederholung platziert werden. Ein außerhalb der Wiederholung platzierter count-Wert kann in einer Berechnung innerhalb der Wiederholung referenziert werden.	count(${question})
count-selected(question)	Gibt die Anzahl der ausgewählten Antworten für Fragen vom Typ select_one und select_multiple zurück. Diese Funktion gibt auch die Anzahl der Dateianlagen für Bild-, Audio- und Dateifragen mit dem Aussehen "multiline" zurück.	count-selected(${question_one})
date(question, expression, or value)	Wandelt eine Zahl oder Zeichenfolge ohne Beibehaltung der Zeit in ein Datumsobjekt um.	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Wandelt eine Zahl oder Zeichenfolge in ein Datumsobjekt um.	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	Konvertiert ein Datumsobjekt in eine dezimale Datums-/Uhrzeitzahl.	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	Konvertiert ein Zeitobjekt in eine Zahl, die einen Bruchteil des Tages in der Zeitzone des Geräts repräsentiert.	decimal-time(${time_question})
ends-with(string, substring)	Gibt "true" zurück, wenn die angegebene Zeichenfolge mit einer Teilzeichenfolge endet.	ends-with(${question_one}, 'hand.')
false()	False	false()
format-date()	Passt einen vorhandenen Datums- oder Zeitwert an ein definiertes Format an.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Wenn die Auswertung der Bedingung "true" ergibt, wird "a" zurückgegeben, ansonsten "b".	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
indexed-repeat(question, repeat, index number)	Gibt den Wert aus einer bestimmten Frage in einem Wiederholungsdatensatz zurück. Weitere Informationen finden Sie unter Wiederholungen.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Wird in einen ganzzahligen Wert konvertiert. Die Konvertierung ist je nach Datentyp unterschiedlich. Hinweis: Wenn diese Funktion leer ist, wird "NaN" zurückgegeben, und die Frage bleibt leer.	int(${question_one})
join(separator, question)	Verbindet alle Antworten mit einer bestimmten Frage in einer Wiederholung, getrennt durch das angegebene Trennzeichen. Hinweis: Bei Verwendung in der mobilen Survey123-App kann diese Funktion innerhalb oder außerhalb der Wiederholung platziert werden. Wenn die Funktion in der Survey123-Web-App verwendet werden soll, muss sie außerhalb der Wiederholung platziert werden. Ein außerhalb der Wiederholung platzierter join-Wert kann in einer Berechnung innerhalb der Wiederholung referenziert werden.	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	Wird für select_one-Fragen verwendet. Die Funktion gibt die Beschriftung zurück, die mit dem Namen der Auswahlmöglichkeit in der angegebenen Frage verknüpft ist. Beachten Sie, dass die Frage in Anführungszeichen gesetzt werden muss.	jr:choice-name(${select_one}, '${select_one}')
	Wird für select_multiple-Fragen verwendet. Die Funktion gibt die Beschriftung zurück, die mit dem Namen der Auswahlmöglichkeit in der angegebenen Frage verknüpft ist. Um die Beschriftung für einzelne Antworten zu extrahieren, muss die Funktion selected-at() verwendet werden. Beachten Sie, dass die Frage in Anführungszeichen gesetzt werden muss.	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	Gibt den Maximalwert in einem gegebenen Bereich oder für eine Frage innerhalb der Wiederholungen zurück.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Gibt den Minimalwert in einem gegebenen Bereich oder für eine Frage innerhalb der Wiederholungen zurück.	min(${question_one}, ${question_two})
not(expression)	Gibt bei Rückgabe des Ausdrucks von "true" einen falschen Wert zurück und bei Rückgabe des Ausdrucks von "false" einen wahren Wert.	not(selected(., 'yes'))
now()	Gibt einen Zeitstempel für diesen Augenblick zurück. Diese Funktion wird für in Fragen vom Typ "time" und "dateTime" verwendet. Sie verhält sich wie "today()" in Datumsfragen.	now()
number(question, expression, or value)	Wird in eine Zahl konvertiert. Die Konvertierung ist je nach Datentyp unterschiedlich. Hinweis: Wenn diese Funktion leer ist, wird "NaN" zurückgegeben, und die Frage bleibt leer.	number(${question_one})
once()	Wenn eine Frage bereits über einen Wert verfügt, wird der vorhandene Wert zurückgegeben. Diese Funktion ist hilfreich, wenn "random()" oder "uuid()" in einer wiederholten Frage verwendet wird, um sicherzustellen, dass sich der Wert beim Durchsuchen der wiederholten Datensätze im Formular nicht ändert.	once(uuid())
position(..)	Gibt den Index des aktuellen Datensatzes in einer Wiederholung zurück. Weitere Informationen finden Sie unter Wiederholungen.	position(..)
pulldata()	Gibt einen in einer externen CSV-Datei gespeicherten Wert zurück. Weitere Informationen finden Sie unter Abrufen eines Wertes aus CSV-Code.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Gibt einen Wert aus den EXIF-Metadaten in einem Bild zurück. Weitere Informationen finden Sie unter Extrahieren von Bildmetadaten.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Gibt einen Wert aus einer Geopunkt-Frage zurück. Weitere Informationen finden Sie unter Extrahieren von Geopunkt-Werten.	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	Führt eine JavaScript-Funktion im Formular aus und gibt das Ergebnis zurück. Weitere Informationen finden Sie unter JavaScript-Funktionen in Survey-Formularen.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Gibt einen Wert aus einem JSON-Objekt zurück. Weitere Informationen finden Sie unter Abrufen eines Wertes aus JSON-Code.	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	Fragt einen ArcGIS-Feature-Layer, eine Feature-Tabelle oder einen Kartenservice mit aktivierter Abfragefunktion ab und gibt das Ergebnis zurück. Weitere Informationen finden Sie unter Durchführen einer Abfrage für einen Feature-Layer.	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	Gibt Informationen zum Gerät oder zum angemeldeten Benutzer zurück. Weitere Informationen finden Sie unter Geräte- und Benutzereigenschaften.	pulldata("@property", 'username')
random()	Gibt einen Zufallswert zwischen 0 (inklusiv) und 1 (exklusiv) zurück.	random()
regex()	Wendet einen regulären Ausdruck auf die Eingabe der Frage an. Gibt "true" zurück, wenn das Muster übereinstimmt. Weitere Informationen finden Sie unter Reguläre Ausdrücke.	regex(., '^\d{5}$')
selected(question, value)	Überprüft, ob eine Antwort ausgewählt wurde. Diese Funktion wird für Fragen vom Typ select_one und select_multiple verwendet.	selected(${question_one}, 'a')
selected-at(question, number)	Wird für select_multiple-Fragen verwendet. Die Funktion gibt den Namen der für die angegebene Zahl ausgewählten Auswahlmöglichkeit zurück, wobei die Zählung bei Null beginnt; beispielsweise gibt "2" die dritte Auswahlmöglichkeit zurück.	selected-at(${question_one}, 2)
starts-with(string, substring)	Gibt "true" zurück, wenn die angegebene Zeichenfolge mit einer Teilzeichenfolge beginnt.	starts-with(${question_one}, 'The')
string(question, expression, or value)	Wird in eine Zeichenfolge konvertiert. Die Konvertierung ist je nach Datentyp unterschiedlich.	string(${question_one})
string-length(question, expression, or value)	Gibt die Länge einer nicht leeren Zeichenfolge zurück.	string-length(${question_one})
substr(question, start, end)	Gibt die Unterzeichenfolge am angegebenen Start beginnend zurück und erstreckt sich bis zu dem Zeichen am Indexende -1, wobei Start und Ende bei 0 beginnen.	substr(${question_one}, 1, 2)
sum(repeat)	Gibt die Summe aller Antworten für eine Frage innerhalb der Wiederholungen zurück. Weitere Informationen finden Sie unter Aggregatfunktionen. Hinweis: Bei Verwendung in der mobilen Survey123-App kann diese Funktion innerhalb oder außerhalb der Wiederholung platziert werden. Wenn die Funktion in der Survey123-Web-App verwendet werden soll, muss sie außerhalb der Wiederholung platziert werden. Ein außerhalb der Wiederholung platzierter sum-Wert kann in einer Berechnung innerhalb der Wiederholung referenziert werden.	sum(${question})
today()	Gibt das heutige Datum zurück, wobei intern die lokale Mittagszeit gespeichert wird. Diese Funktion wird in Datumsfragen verwendet.	today()
true()	True	true()
uuid()	Gibt eine zufällige UUID-Zeichenfolge zurück.	uuid()
version()	Gibt die Version des im Arbeitsblatt Einstellungen definierten Surveys zurück.	version()

Die folgenden mathematischen Funktionen werden in Survey123 unterstützt:

Funktion	Beschreibung	Beispiel
acos(value)	Gibt den Arkuscosinus des Wertes zurück.	acos(${question_one})
asin(value)	Gibt den Arkussinus des Wertes zurück.	asin(${question_one})
atan(value)	Gibt den Arkustangens des Wertes zurück.	atan(${question_one})
atan2(value1, value2)	Gibt den Arkustangens des Quotienten der Werte zurück.	atan2(${question_one}, ${question_two})
cos(value)	Gibt den Kosinus des Wertes als Winkel in Radiant zurück.	cos(${question_one})
sin(value)	Gibt den Sinus des Wertes als Winkel in Radiant zurück.	sin(${question_one})
tan(value)	Gibt den Tangens des Wertes als Winkel in Radiant zurück.	tan(${question_one})
exp(value)	Gibt den natürlichen Exponent des Wertes zurück.	exp(${question_one})
exp10(value)	Gibt 10 potenziert mit dem Wert zurück.	exp10(${question_one})
log(value)	Gibt den natürlichen Logarithmus des Wertes zurück.	log(${question_one})
log10(value)	Gibt den Logarithmus der Basis 10 des Wertes zurück.	log10(${question_one})
pi()	Ergebnis ist Pi.	pi()
pow(value, power)	Gibt den Wert mit der angegebenen Potenz zurück.	pow(${question_one}, 3)
round(value, places)	Gibt den gerundeten Wert zurück.	round(${question_one}, 5)
sqrt(value)	Gibt die Quadratwurzel des Wertes zurück.	sqrt(${question_one})

Beschränkungen

Durch Hinzufügen einer Einschränkung zu einer Survey-Frage werden die als Antwort zulässigen Eingaben eingeschränkt. Eine Einschränkung kann z. B. ein bestimmter Zahlenbereich, Kombinationen aus Buchstaben und Zahlen oder ein allgemeiner Musterabgleich sein. Im Arbeitsblatt wird der Einschränkungsausdruck in das Feld "constraint" eingegeben, für informativen Text ist die Spalte "constraint_message " des Survey-Arbeitsblatts verfügbar. Im Einschränkungsausdruck wird die Eingabe für die Frage immer durch einen Punkt dargestellt.

So können Sie beispielsweise mit der folgenden Formel die Eingabe für ein ganzzahliges Feld auf positive Zahlen einschränken:

.>= 0

Wenn die folgende Formel auf ein date-Feld angewendet wird, kann der Benutzer keinen früheren Wert als das heutige Datum eingeben:

.>= today()

Sie können auch Berechnungen in Einschränkungen verwenden. Mit dieser Formel wird eine Berechnung durchgeführt, mit der Benutzer nur ein Datum zwischen dem aktuellen Datum und dem Datum 14 Tage ab dem aktuellen Datum auswählen können:

(.>= today()) and (.<=(today() + (1000 * 60 * 60 * 24 * 14)))

Tipp:

Zur Vermeidung unerwarteter Fehler schließen Sie eine führende Null in die Werte ein, wenn eine Formel Dezimalwerte zwischen -1 und 1 enthält. Ohne die führende Null kann das Dezimaltrennzeichen fälschlicherweise als das Operatorzeichen . (oder -.) interpretiert werden. Der folgende Ausdruck schlägt beispielsweise fehl:

.> .25 and .< 24.25

Der folgende Ausdruck wird hingegen wie erwartet ausgeführt:

.> 0.25 and .< 24.25

Reguläre Ausdrücke

Bei einem regulären Ausdruck handelt es sich um eine Folge von Zeichen, die verwendet wird, um in Zeichenfolgen Muster abzugleichen. Wenn das Muster in Survey123 übereinstimmt, gibt der Ausdruck "true" zurück, andernfalls, wenn das Muster nicht übereinstimmt, gibt der Ausdruck "false" zurück.

Reguläre Ausdrücke können Sie auf verschiedene Weise für den Mustervergleich verwenden; mit ihnen können gültige Antworten auf ein bestimmtes Format beschränkt oder es kann sichergestellt werden, dass das Format nur bestimmte Inhalte aufweist. In diesem Beispiel muss die Antwort auf die Frage an beliebiger Stelle das Wort road enthalten:

regex(., 'road')

Der Punkt am Anfang der Beispiele bewirkt, dass der Ausdruck auf das aktuelle Feld angewendet wird. Wenn Sie stattdessen den Namen eines anderes Feldes hinzufügen, wird der reguläre Ausdruck auf dieses Feld angewendet; dies ist ideal für relevante Ausdrücke. Das Komma fungiert als Trennzeichen zwischen dieser Felddefinition und dem Ausdruck.

Dieser reguläre Ausdruck gewährleistet, dass die Antwort exakt mit dem Wort road ohne weitere Zusätze übereinstimmt:

regex(., '^road$')

Reguläre Ausdrücke eignen sich ideal, um die Eingabemöglichkeiten für eine Frage auf ein Standardformat zu beschränken. In diesem Beispiel dürfen nur fünfstellige Postleitzahlen aus den USA eingegeben werden:

regex(., '^\d{5}$')

Hier wird die Antwort mit dem aktuellen Format eines indonesischen Nummernschildes verglichen, siehe folgendes Foto:

regex(., '^[A-Z]{1,2}\d{4}[A-Z]{2,3}$')

Für nicht ganz so streng standardisierte Formate können komplexe reguläre Ausdrücke erforderlich werden. Dieser von der Survey123-Web-App verwendete reguläre Ausdruck schränkt die Eingabe in ein Zeichenfolgenfeld auf das Format einer E-Mail-Adresse ein:

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$')

Anhand der Änderung des obigen Ausdrucks wird die Eingabe auf das Format einer E-Mail-Adresse eingeschränkt, bei der nicht-englische Zeichen zulässig sind:

regex(., '^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\u0400-\uffff\-0-9]+\.)+[a-zA-Z\u0400-\uffff]{2,}))$')

Dieses Beispiel, in dem ebenfalls ein regulärer Ausdruck aus der Survey123-Web-App verwendet wird, schränkt die zulässigen Antworten in einem Feld auf Einträge ein, die dem Format einer Webadresse entsprechen:

regex(., '^((https?|ftps?)\://|)(((?:(?:[\da-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.)+(?:[a-zA-Z](?:[-\da-zA-Z]{0,61}[\da-zA-Z])?)\.?)|localhost)(\:\d+)?(/(?:[^?#\s/]+/)*(?:[^?#\s/]+(?:\?[^?#\s/]*)?(?:#[A-Za-z][\w.:-]*)?)?)?')

Weitere Informationen über reguläre Ausdrücke erhalten Sie in der Dokumentation zum Mozilla Developer Network. Eine Liste der Zeichen und ihrer Funktionen in regulären Ausdrücken finden Sie im Arbeitsblatt Reference in den Survey123-Vorlagen oder in der Kurzübersicht.

Berechnungen

Berechnungen werden in der Spalte "calculation" einer Frage ausgeführt. Berechnungen sind häufig mit Fragen des Typs "calculate" verknüpft, können jedoch auch auf Fragen des Typs "integer", "decimal", "text" sowie "select_one" angewendet werden. Mit dem Ergebnis der Berechnung können relevante oder Einschränkungsausdrücke gefüllt werden, indem der Feldname des Berechnungsausdrucks referenziert wird.

Fragen des Typs "calculate" sind ausgeblendet und werden in Formularen nicht angezeigt. Dieser Fragentyp kann daher auch für Werte verwendet werden, die im Formular nicht angezeigt werden müssen, im Feature-Layer jedoch enthalten sind.

Sie können beispielsweise eine Frage vom Typ "calculate" erstellen, ihr den Namen "calc" zuweisen und den folgenden Ausdruck in die Spalte "column" der Frage einfügen:

${question_1} + ${question_2} + ${question_3}

Verwenden Sie das Ergebnis, um die Relevanz für die nächste Frage festzulegen:

${calc} <= 100

Berechnungen können mit den Antworten in date-Feldern verwendet werden. Mit dieser Berechnung wird die Anzahl der Jahre zwischen einem eingegebenen Datum und dem heutigen Tag geschätzt; dies eignet sich ideal, um das Alter einer Person zu berechnen:

int((today() - ${birth_date}) div (1000 * 24 * 60 * 60 * 365.25))

Manchmal benötigen Sie nur einen Teil eines Wertes oder eine gekürzte Version einer vollständigen Antwort. Der Operator substr gibt nur einen Teil einer Zeichenfolge zurück, der durch die danach folgenden Zahlen definiert wird. Das erste Zeichen bestimmt den Startpunkt der Auswahl, während mit dem zweiten Wert die Länge festgelegt wird (falls kein zweiter Wert vorhanden ist, wird die Berechnung bis zum Ende der Zeichenfolge fortgesetzt). In diesem Beispiel wird mit dem Operator substr alles außer der Zeichenfolge von Zeichen 10 bis Zeichen 15 entfernt:

substr(${previous_question}, 10, 15)

Wenn die erste Zahl negativ ist, beginnt substr die Zählung am Ende der Zeichenfolge statt am Anfang. Mit diesem Beispiel werden nur die letzten fünf Zeichen der Antwort zurückgegeben:

substr(${previous_question}, -5)

Sie können mit dem Parameter calculationMode steuern, wann Berechnungen im Formular ausgeführt werden. Weitere Informationen finden Sie unter Berechnungsmodus.

Sie können auch die Spalte "calculation" für Aggregatfunktionen in Wiederholungen verwenden. Weitere Informationen finden Sie unter Wiederholungen.

Beachten Sie bei der Verwendung von Berechnungen die folgenden Empfehlungen:

• Fügen Sie bei Verwendung von random() ggf. eine Konstante hinzu, um zu vermeiden, dass Sie Null (0) als Ergebnis erhalten, zum Beispiel random()+0.5. Der Wert 0 kann zu einer leeren Antwort führen.
• Vergewissern Sie sich ebenso wie bei Einschränkungen, dass allen Dezimalwerten zwischen -1 und 1 in der Formal eine führende Null hinzufügt wird, da ein Dezimaltrennzeichen als führendes Zeichen Fehler verursacht.
• Der Datentyp eines Berechnungsergebnisses hängt vom Datentyp jedes Elements der Berechnung ab. Wenn eine Berechnung mit zwei ganzzahligen Werten durchgeführt wird, ist auch das Berechnungsergebnis ein ganzzahliger Wert. Wenn die Berechnung einen Zeichenfolgendatentyp enthält, kann es vorkommen, dass der Operator + Werte verkettet, anstatt sie zu addieren. Um unerwartete Ergebnisse zu vermeiden, stellen Sie mithilfe der Funktion number() sicher, dass Zeichenfolgenwerte in einer Berechnung als Zahlen behandelt werden. Die Berechnung zum Addieren von question1 (Datentyp "Integer") zu question2 (Datentyp "Text") lautet beispielsweise ${question1} + number(${question2}).

Tipp:

Der standardmäßige XLSForm-Bindungstyp für Berechnungsfragen ist string. Um diesen Standard zu überschreiben, geben Sie den gewünschten Typ (z. B. int oder decimal) in der Spalte bind::type für Ihre Frage ein. Sie können auch den gewünschten Fragetyp (z. B. integer oder decimal) verwenden und das Aussehen für die Frage auf hidden festlegen.

Vorsicht:

Wenn Sie Funktionen oder Operatoren mit Textfragen verwenden, wird in der NaN-Web-App das Ergebnis Survey123 zurückgegeben. Wenn Sie Textfragen miteinander verbinden möchten, verwenden Sie anstelle des Operators concat() die Funktion +.

Komplexe mathematische Funktionen

In der Spalte "calculation" können auch komplexere mathematische Operationen verarbeitet werden. In diesem Beispiel wird die Fläche einer Parzelle anhand ihres Radius bestimmt; hierzu werden die Pi- und die Potenzfunktion verwendet:

pi() * pow(${plot_radius}, 2)

Die Höhe eines Baumes wird häufig gemessen, indem der Winkel an einem Beobachtungspunkt von der Augenhöhe bis zur Baumspitze und die Entfernung von diesem Beobachtungspunkt bis zur Baumwurzel gemessen wird. Wenn der Winkel bis zur Baumspitze in Grad gemessen wird, wird dieser Wert wie folgt das Bogenmaß umgerechnet:

${angle_to_top_degrees} * (pi() div 180)

Nachdem der Winkel im Bogenmaß vorliegt, kann die Baumhöhe (gerundet auf zwei Dezimalstellen) wie folgt ermittelt werden:

round(((tan(${angle_to_top_radians}) * ${distance_to_tree}) + ${height_to_eyes}),2)

Datumsformate

Sie können die Funktion format-date im Feld calculation verwenden, um Datums- und Zeitwerte zu formatieren. Dies kann hilfreich sein, wenn Sie Datumsteile für Benutzer anzeigen oder als Zeichenfolgen beibehalten möchten.

In diesem Beispiel wird der Wert in einer vorherigen time- oder dateTime-Frage im 24-Stunden-Format zurückgegeben:

format-date(${previous_time},'%H:%M')

In der Funktion format-date können Sie die folgenden Qualifizierer verwenden:

Qualifizierer	Beschreibung
%3	Mit 0 aufgefüllte Millisekundenticks (000-999)
%a	Tageskurztext mit drei Buchstaben
%b	Abgekürzter Monatsname
%d	Mit 0 aufgefüllter Tag des Monats
%e	Tag des Monats
%h	Stunde (24-Stunden-Format)
%H	Mit 0 aufgefüllte Stundenangabe (24-Stunden-Format)
%m	Mit 0 aufgefüllte Monatsangabe
%M	Mit 0 aufgefüllte Minutenangabe
%n	Monat in Zahlen
%S	Mit 0 aufgefüllte Sekundenangabe
%W	Wochennummer Hinweis: Der Qualifizierer %W kann in einer "format-date"-Funktion, in der die Datumsfrage eine Berechnung verwendet, nicht verwendet werden. Bei einer Datumsfrage, die einen Standardwert enthält, funktioniert dieser Qualifizierer.
%y	Zweistelliges Jahr
%Y	Vierstelliges Jahr

Hinweis:

Bei Fragen vom Typ "dateTime" werden Zeitauflösungen unter einer Minute nicht unterstützt. Wenn Sie eine Zeitauflösung mit Datumsangaben unter einer Minute erfassen möchten, sollten Sie Fragen vom Typ start und end verwenden.

Leere Werte

Bedenken Sie bei Verwendung von Einschränkungen und Berechnungen, die andere Fragen referenzieren, was passiert, wenn diese Frage leer ist (d. h. wenn sie keine Antwort hat). Leere Werte werden wie folgt dargestellt:

• NaN (Not a Number, keine Zahl) für Integer- und Dezimalfragen. Dies ist ein spezieller Wert, der das Fehlen eines gültigen Wertes darstellt.
• '' (eine leere Zeichenfolge) für Textfragen. Der Standarddatentyp für Fragen vom Typ "select_one", "select_multiple", "rank" und "hidden" ist ebenfalls "Text". Wenn Fragen vom Typ "select_one", "select_multiple" und "hidden" leer sind oder wenn eine Rangfolgefrage (Typ "rank") nicht durch den Benutzer abgeändert worden ist, enthalten sie eine leere Zeichenfolge.

Das Verhalten in Berechnungen unterscheidet sich in Abhängigkeit davon, ob der Wert eine Zahl oder Text ist.

Bei Integer- und Dezimalfragen verhalten sich Berechnungen wie folgt:

• Mathematische Ausdrücke mit dem Wert "NaN" werden grundsätzlich nicht ausgeführt, und die Frage bleibt leer.
• Die Funktionen "min()" und "max()" werden ausgeführt, wobei eventuelle NaN-Werte ignoriert werden.
• Der Vergleich des NaN-Wertes mit einem anderen Wert gibt nur in solchen Berechnungen "true" zurück, in denen ein Wertevergleich vom Typ is not equal stattfindet. Bei allen anderen Ausdrücken wird "false" zurückgegeben.

Auf Textfragen trifft folgendes Verhalten zu:

• Die Verkettung von Textfragen wird durchgeführt, wenn leere Werte vorhanden sind. Das Ergebnis von concat("Hello" + ${firstName}, ", how are you?") ist beispielsweise "Hello , how are you?", wenn der Wert "firstName" der Frage leer ist.
• Die Funktionen "min()" und "max()" werden ausgeführt, wobei eventuelle leere Zeichenfolgen ignoriert werden.
• Eine leere Textantwort ist gleich einer anderen leeren Textantwort und immer kleiner als nicht leerer Text.

Mithilfe der Funktion string-length können Sie ermitteln, ob eine Frage leer ist. Die Funktion string-length kann für alle Fragetypen verwendet werden. Beispiel: string-length(${Question1}) gibt 0 zurück, wenn Question1 leer ist.

Mit der Funktion count-selected können Sie auch ermitteln, ob eine Frage des Typs "select_one" oder "select_multiple" leer ist. Beispiel: count-selected(${question2}) gibt 0 zurück, wenn für question2 keine Auswahl erfolgt ist.

Fragen des Typs "select_multiple" und "rank"

Die Antworten auf Fragen des Typs "select_multiple" und "rank" werden anders als die auf Fragen aller anderen Typen gespeichert. Jede ausgewählte Antwort in einer Frage des Typs "select_multiple" wird in der Reihenfolge der Auswahl (getrennt durch Kommas) aufgeführt. Wenn beispielsweise die Antworten "A" und "B" in dieser Reihenfolge ausgewählt werden, wird die Antwort als "A,B" dargestellt. Die Antworten auf eine Frage des Typs "rank" werden ebenfalls als kommagetrennte Liste gespeichert, allerdings in der Reihenfolge vom höchsten zum niedrigsten Rang zum Zeitpunkt der Übermittlung.

Einige XLSForm-Features können für Fragen vom Typ "select_multiple" und "rank" nicht verwendet werden. Wenn Sie beispielsweise die Antwort "A" in die Spalte "relevant" einer Frage eingeben, die Ihre Frage vom Typ "select_multiple" referenziert, und die Survey-Antwort "A,B" lautet, wird die Antwort nicht als relevant betrachtet. In diesem Fall können Sie mithilfe der Funktion selected() bestimmen, ob einer der Werte in der Liste enthalten ist.

Wenn der folgende Ausdruck in der Spalte "relevant" einer Frage verwendet wird, wird die Frage angezeigt, sofern der Benutzer "A" als eine der Antworten in der referenzierten Frage vom Typ "select_multiple" ausgewählt hat. Zusätzliche Antworten in der Frage vom Typ "select_multiple" haben keinen Einfluss auf dieses Verhalten.

selected(${previous_question}, 'A')

Abrufen eines Wertes aus einer CSV-Datei

Durch Verwendung der Funktion pulldata() in der Spalte "calculation" einer Frage können Sie Daten vorab aus einer .csv-Datei laden. Eine .csv-Datei kann auf zwei Arten eingebunden werden: Sie können die Datei manuell im Ordner media des Survey platzieren oder eine in ArcGIS gehostete .csv-Datei verknüpfen.

Für die Funktion pulldata() müssen die folgenden vier Parameter in der genannten Reihenfolge angegeben werden:

1. Der Name der .csv-Datei, die die Liste der Werte enthält. Das Dateinamenssuffix .csv ist nicht im Namen enthalten.
2. Der Name der Spalte in der .csv-Datei, die den zurückzugebenden Wert enthält.
3. Der Name des Schlüsselfeldes in der .csv-Datei, anhand dessen nach dem Wert gesucht wird.
4. Der Schlüsselwert, der im Schlüsselfeld nachgeschlagen werden soll.

Diese Werte können direkt oder durch Variablen definiert werden, die an anderer Stelle im Survey festgelegt werden. Im folgenden Beispiel gibt die Berechnung die E-Mail-Adresse einer Person, die in einer vorherigen Frage benannt wurde, aus einer .csv-Datei namens "info" zurück:

pulldata('info', 'email', 'name', ${respondent_name})

Die gleiche pulldata()-Funktion kann auch in der Spalte "constraints" verwendet werden, um zu verhindern, dass der Benutzer Antworten sendet, die nicht in der .csv-Datei enthalten sind. In der Spalte "constraints" verhindert die gleiche Formel, dass das Formular Werte akzeptiert, die nicht in der Spalte "name" der .csv-Datei vorhanden sind.

Für die Funktion pulldata() gelten einige Einschränkungen. Der Name des Schlüsselfeldes unterliegt der gleichen Einschränkung wie die Spalte "name" im Arbeitsblatt choices; diese Werte dürfen also keine Leerzeichen oder Nicht-ASCII-Zeichen enthalten. Da es sich um eine .csv-Datei handelt, führt die Verwendung eines Kommas in einem dieser Felder außerdem dazu, dass die Funktion pulldata() falsche Ergebnisse generiert.

Wenn Werte in Ihrer .csv-Datei 255 Zeichen überschreiten, müssen Sie in der Spalte "bind::esri:fieldLength" sowohl für die Frage, die Sie mit dem .csv-Inhalt füllen, als auch für alle Fragen, die als Eingabe für die Funktion pulldata() verwendet werden, einen höheren Wert eingeben. Wenn Ihre .csv-Datei Werte enthält, die größer sind als die maximale Länge eines dieser Felder, kann keine Survey-Antwort übermittelt werden. Stattdessen wird ein Fehler mit dem Code 1000 angezeigt.

Hinweis:

Die Funktion pulldata() kann nicht zum Füllen der Werte von Fragen des Typs "select_multiple" verwendet werden.

Bei Verwendung der Funktion pulldata() dürfen die .csv-Spaltennamen nicht leer sein und keine Leerzeichen, Bindestriche oder andere Sonderzeichen enthalten.

Es wird empfohlen, dass Sie die .csv-Datei mit UTF-8-Zeichencodierung codieren. Wenn Sie zur Erstellung der Microsoft Excel-Datei .csv verwenden, müssen Sie sie als CSV UTF-8 abspeichern.

Abrufen eines Wertes aus JSON-Code

Mit der Funktion pulldata("@json") können Sie einzelne Eigenschaften aus einem JSON-Objekt extrahieren. Häufig werden mit dieser Funktion andere Funktionen wie pulldata("@javascript") oder pulldata("@layer") ergänzt. Die Syntax der Funktion lautet wie folgt:

pulldata("@json", <question name>, "<JSON property>")

Die Parameter für pulldata("@json") lauten wie folgt:

• question name: Der Name der Frage, die das JSON-Objekt enthält, zum Beispiel: ${json_response}.
• JSON property: Die Eigenschaft, die aus dem JSON-Code abgerufen werden soll. Verwenden Sie Punkte, um anzugeben, wo sich die Eigenschaft innerhalb der JSON-Struktur befindet. Wenn Sie beispielsweise die Eigenschaft City aus dem Objekt address abrufen möchten, geben Sie "address.City" an.

Im folgenden Beispiel wird das Ergebnis eines Rückwärts-Geokodierungsvorgangs als JSON-Objekt in einer Textfrage namens json_response zurückgegeben:

Es wird eine Locator-Antwort zurückgegeben, die der folgenden Antwort ähnelt:

{
    "address": {
        "Match_addr": "Eiffel Tower",
        "LongLabel": "Eiffel Tower, Paris, Île-de-France, FRA",
        "ShortLabel": "Eiffel Tower",
        "Addr_type": "POI",
        "Type": "Historical Monument",
        "PlaceName": "Eiffel Tower",
        "AddNum": "",
        "Address": "",
        "Block": "",
        "Sector": "",
        "Neighborhood": "Paris 07",
        "District": "Paris",
        "City": "Paris",
        "MetroArea": "",
        "Subregion": "Paris",
        "Region": "Île-de-France",
        "RegionAbbr": "",
        "Territory": "",
        "Postal": "",
        "PostalExt": "",
        "CntryName": "France",
        "CountryCode": "FRA"
    },
    "location": {
        "x": 2.294520000000034,
        "y": 48.85832000000005,
        "spatialReference": {
            "wkid": 4326,
            "latestWkid": 4326
        }
    }
}

Mit der Funktion pulldata("@json") wird die Eigenschaft City aus dem Objekt address abgerufen:

pulldata("@json", ${json_response}, "address.City")

Breiten- und Längengrad werden aus dem Objekt location abgerufen:

pulldata("@json", ${json_response}, "location.x")

pulldata("@json", ${json_response}, "location.y")

Hinweis:

Für den Zugriff auf einzelne Eigenschaften eines Parent-Objekts wird ein Punkt verwendet. Wenn ein Punkt auch einen Teil einer Eigenschaft bildet, muss er in eckige Klammern [ ] eingeschlossen werden. Wenn zum Beispiel die Eigenschaft mit dem Namen City.Population aus dem Objekt address abgerufen werden soll, muss der Ausdruck pulldata("@json", ${json_response}, "address.[City.Population]") verwendet werden.

Sie können auf ein Objekt in einem Objekt-Array zugreifen, indem Sie seine Position im Array in eckigen Klammern angeben. Der Index eines JSON-Array beginnt bei Null. Es folgt ein Beispiel für ein von intelligenten Attributen zurückgegebenes JSON-Objekt. Es enthält ein classes-Array:

{
    "classNames": "person,bottle,keyboard",
    "classes": [
        {
            "name": "person",
            "score": 0.67421875,
            "xmin": 47,
            "ymin": 20,
            "xmax": 1086,
            "ymax": 262
        },
        {
            "name": "bottle",
            "score": 0.7625,
            "xmin": 237,
            "ymin": 469,
            "xmax": 552,
            "ymax": 639
        },
        {
            "name": "keyboard",
            "score": 0.55078125,
            "xmin": 28,
            "ymin": 49,
            "xmax": 1078,
            "ymax": 385
        }
    ]
}

Der folgende Ausdruck gibt für das obige Beispiel den score-Wert 0.67421875 aus dem ersten Objekt im classes-Array zurück:

pulldata("@json", ${results}, "classes[0].score")

Mit der Eigenschaft length können Sie die Anzahl der Objekte in einem Array zurückgeben. Der folgende Ausdruck gibt für das obige Beispiel den Längenwert 3 zurück:

pulldata("@json", ${results}, "classes.length")

Durchführen einer Abfrage für einen Feature-Layer

Mit der Funktion pulldata("@layer") können Sie eine Abfrage für einen Feature-Layer, eine Feature-Tabelle oder einen Kartenservice mit aktivierter Abfragefunktion durchführen. Sie können eine Attributabfrage oder eine räumliche Abfrage durchführen. Bei einer Attributabfrage wird die Operation getRecord oder getValue verwendet:

pulldata("@layer", "getRecord", "<URL>", "<WHERE clause>")
pulldata("@layer", "getValue", "<JSON property>", "<URL>", "<WHERE clause>")

Bei einer räumlichen Abfrage wird die Operation getRecordAt oder getValueAt verwendet:

pulldata("@layer", "getRecordAt", "<URL>", <location>, "<WHERE clause>")
pulldata("@layer", "getValueAt", "<JSON property>", "<URL>", <location>, "<WHERE clause>")

Hinweis:

Bei der in einer räumlichen Abfrage angegebenen Position muss es sich um eine Geopunkt-Frage handeln.

Die Operationen getRecord und getRecordAt geben ein JSON-Feature-Objekt zurück, das ein einzelnes Feature und alle zugehörigen Attribute enthält. Die Operationen getValue und getValueAt geben anstelle der gesamten Abfrageantwort einen einzelnen Wert aus dem Feature-Objekt zurück.

Die Parameter für pulldata("@layer") lauten wie folgt:

Parameter	Beschreibung
JSON property	Erforderlich für die Operationen getValue und getValueAt. Der Wert, den Sie aus der Abfrageantwort abrufen möchten. Beispiele: "attributes.COUNTRY" "geometry"
location	Erforderlich für die Operationen getRecordAt und getValueAt. Die Punktposition, die Sie mit dem Feature-Layer abfragen möchten. Hierbei muss es sich um eine Geopunkt-Frage handeln. Beispiel: ${location}
URL	Erforderlich. Die URL des Feature-Layers oder der Tabelle, für den oder die die Abfrage durchgeführt werden soll. Dieser Parameter akzeptiert zusätzliche Anforderungsparameter. Beispiel: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Optional. Ein WHERE-Ausdruck, der den Feature-Layer oder die Tabelle filtert. Wenn die WHERE-Klausel nicht angegeben wurde, wird standardmäßig "1=1" verwendet. Beispiel: "COUNTRY='Canada'"

Tipp:

Die Funktion pulldata("@layer") gibt den ersten Datensatz in der Abfrageantwort zurück. Entwerfen und testen Sie die Abfrage, um sicherzustellen, dass Sie die gewünschten Ergebnisse erhalten. Sie können die Abfrage mit der WHERE-Klausel und den nachfolgend beschriebenen zusätzlichen Anforderungsparametern verfeinern.

Die Funktion pulldata("@layer") cacht die Abfrageantworten, um eine höhere Effizienz zu erreichen. Um bei jeder Ausführung dieser Funktion den Cache zu berücksichtigen und sicherzustellen, dass eine neue Anforderung übermittelt wird, sollten Sie der URL einen Zeitparameter mit dem Wert "now" hinzufügen, zum Beispiel concat(${layer_url}, "?t=", now()).

Im folgenden Beispiel wird eine Abfrage für einen Polygon-Feature-Layer der globalen Zeitzonen durchgeführt. Es wird die Zeitzone zurückgegeben, in der sich der Geopunkt befindet:

Mit der Operation getRecordAt wird die Zeitzone abgerufen, die der Geopunkt schneidet. Hierzu wird folgende Syntax verwendet:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

Das Attribut ZONE wird anschließend mithilfe der Funktion pulldata("@json") aus der Abfrageantwort extrahiert. Alternativ können Sie die Operation getValueAt in der Berechnung pulldata("@layer") verwenden, um das Attribut ZONE direkt abzurufen, ohne dass eine separate Frage zum Speichern der Abfrageantwort erforderlich ist. Beispiel:

pulldata("@layer", "getValueAt", "attributes.ZONE", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})

pulldata("@layer") kann in Einschränkungen verwendet werden. Beispielsweise können Sie eine Einschränkung auf eine Geopunkt-Frage anwenden, um zu verhindern, dass Benutzer Positionen außerhalb eines Interessenbereichs übermitteln.

Die Operation getRecordAt gibt das JSON-Feature-Objekt für das Land, in dem sich der Geopunkt befindet, mit der folgenden Syntax zurück:

pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0", ${location}, "COUNTRY='Canada'")

Der Name des Landes wird in einer Textfrage unter Verwendung von pulldata("@json") extrahiert. Die Einschränkung ${country}='Canada' wird dann auf die Geopunkt-Frage angewendet, um sicherzustellen, dass sich die Position in der Region Kanada befindet.

Anforderungsparameter

Sie können eine pulldata("@layer")-Abfrage mit zusätzlichen Anforderungsparametern wie distance, orderByFields und resultOffset verfeinern. Weitere Informationen zu Anforderungsparametern finden Sie unter Abfragen (Feature-Service/-Layer). Die Funktion pulldata("@layer") unterstützt nur die Anforderungen, die ein Feature-Objekt zurückgeben.

Wenn Sie diese Parameter in eine Abfrage einbinden möchten, hängen Sie sie nach einem Fragezeichen an die URL an. Zusätzliche Parameter werden durch kaufmännische Und-Zeichen (&) getrennt. Im folgenden Beispiel werden die Parameter orderByFields und resultOffset an die Feature-Layer-URL angehängt, um den Namen des zehntgrößten Landkreises in Kalifornien zurückzugeben:

pulldata("@layer", "getValue", "attributes.NAME", "https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1?orderByFields=POPULATION DESC&resultOffset=9", "STATE_NAME = 'California'")

Eine aggregierte Abfrage kann verwendet werden, um Statistiken für einen Feature-Layer mit dem Parameter outStatistics zurückzugeben. Statistiken, die mit diesem Parameter berechnet werden können, sind Anzahl, Summe, Minimum, Maximum, Durchschnitt, Standardabweichung und Varianz.

Im folgenden Beispiel wird die Anzahl der Landkreise im ausgewählten Bundesstaat zurückgegeben:

pulldata("@layer", "getValue", "attributes.TotalCount", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "count","onStatisticField": "objectId","outStatisticFieldName": "TotalCount"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

Im folgenden Beispiel wird die Summe des Feldes POPULATION für alle Landkreise im ausgewählten Bundesstaat zurückgegeben:

pulldata("@layer", "getValue", "attributes.TotalPopulation", concat("https://services5.arcgis.com/jMCHJcLe13FaKCFB/arcgis/rest/services/US_Counties/FeatureServer/1", '?outStatistics=[{"statisticType": "sum","onStatisticField": "POPULATION","outStatisticFieldName": "TotalPopulation"}]'), concat("STATE_NAME = '", ${state_name}, "'"))

Hinweis:

Die Funktion pulldata("@layer") unterstützt alle Anforderungsparameter, die in Abfragen (Feature-Service/-Layer) aufgelistet sind, mit Ausnahme der folgenden Parameter:

• f
• outFields
• outSR
• resultRecordCount
• returnCountOnly
• returnGeometry
• returnIDsOnly
• token

Abrufen einer Position aus einer Liste

Sie können Benutzern die Möglichkeit geben, eine Position aus einem Feature-Layer abzurufen. Dabei dient ihre Auswahl aus einer Liste von Auswahlmöglichkeiten in einer Frage des Typs "select_one" als Grundlage. Die Auswahl wird als Text übermittelt, und die entsprechende Geometrie wird als Position für die Survey-Antwort angegeben. Dieser Ansatz entspricht der Frage Ortsliste im Survey123 Web Designer.

Um eine Liste mit Positionen zu erstellen, fügen Sie eine Frage des Typs "select_one" mit den Aussehen "search" und "autocomplete" hinzu. Durch das Aussehen "search" wird die Liste mit Werten aus einem Feature-Layer gefüllt. Beim Aussehen autocomplete werden die Werte in einer Dropdown-Liste angezeigt, was nützlich ist, wenn vom Feature-Layer eine sehr lange Liste zurückgegeben wird.

Konfigurieren Sie den Ausdruck search() so, dass eine Liste von Werten aus einem Feature-Layer abgerufen wird. Fügen Sie in der Frage vom Typ "geopoint", "geoshape" oder "geotrace" den Ausdruck pulldata("@layer") hinzu, um die Geometrie für das in der Liste ausgewählte Feature abzurufen.

Im folgenden Beispiel wählen Befragte einen Wasserzähler aus einer "select_one"-Frage namens meter_id aus. Die Geometrie des Wasserzählers wird aus dem Layer "Water Meters Feature" abgerufen und in der "geopoint"-Frage gespeichert:

Weitere Informationen zum Aussehen "search" finden Sie unter Search.