Formules

Les formules permettent de créer des formulaires plus intelligents avec ArcGIS Survey123.

Les questions précédentes doivent toujours être indiquées au format ${field_name} dans les formules.

Opérateurs

Les opérateurs suivants sont pris en charge dans Survey123 :

Opérateur	Description	Exemple
.	La réponse actuelle	.=1
+	Addition	${question_one} + 4
-	Soustraction	${question_one} - 4
*	Multiplication	${question_one} * 4
div	Division	${question_one} div 4
=	Égal	${price}=9.80
!=	Différent	${price}!=9.80
<	Inférieur à	${price}<9.80
<=	Inférieur ou égal à	${price}<=9.80
>	Supérieur à	${price}>9.80
>=	Supérieur ou égal à	${price}>=9.80
and	Et	${price}>9.00 and ${price}<9.90
mod	Modulo (reste de la division)	${question_one} mod ${question_two}
or	Ou	${price}=9.80 or ${price}=9.70

Fonctions

Les fonction suivantes sont prises en charge dans Survey123 :

Fonction	Description	Exemple
boolean(question, expression, or value)	Renvoie true (vrai) si la valeur indiquée n’est pas nulle. Il est recommandé d’utiliser à la place la fonction boolean-from-string(). Attention : Cette fonction renvoie toujours la valeur true (vrai) dans l’application Web Survey123. Pour connaître les alternatives, reportez-vous à la rubrique Valeurs vides.	boolean(${question_one})
boolean-from-string()	Renvoie true (vrai) si la chaîne indiquée est « true » (vrai) ou « 1 ». Sinon, renvoie false (faux).	boolean-from-string(${question_one})
coalesce(value1, value2)	Renvoie la première valeur non vide. Cette fonction prend en charge deux valeurs uniquement.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Renvoie la concaténation des valeurs de chaîne.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Renvoie true (vrai) si la chaîne donnée contient la sous-chaîne.	contains(${question_one}, 'red')
count(repeat)	Renvoie la quantité de réponses à une question donnée dans des répétitions. Pour plus d’informations, reportez-vous à la rubrique Fonctions d’agrégation. Remarque : Lorsqu’elle est utilisée dans l’application de terrain Survey123, cette fonction peut être placée dans la répétition ou en dehors de celle-ci. Si cette fonction doit être utilisée dans l’application Web Survey123, elle doit être placée en dehors de la répétition. Une valeur count externe à la répétition peut être référencée dans un calcul interne à la répétition.	count(${question})
count-selected(question)	Renvoie le nombre de réponses sélectionnées aux questions select_one et select_multiple. Cette fonction renvoie également le nombre de fichiers joints aux questions de type image, audio et file (fichier) à l’aide de l’apparence multiligne.	count-selected(${question_one})
date(question, expression, or value)	Convertit un nombre ou une chaîne en objet de date, sans conserver l'heure.	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Convertit un nombre ou une chaîne en objet de date.	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	Convertit un objet de date en nombre date-heure décimal.	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	Convertit un objet de type heure en un nombre représentant une fraction décimale de jour dans le fuseau horaire de l’appareil.	decimal-time(${time_question})
ends-with(string, substring)	Renvoie true (vrai) si la chaîne donnée se termine par la sous-chaîne.	ends-with(${question_one}, 'hand.')
false()	False	false()
format-date()	Ajuste une valeur de date ou d’heure existante à un format défini.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Si la condition évaluée est vraie (true), renvoie a ; sinon, renvoie b.	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
indexed-repeat(question, repeat, index number)	Renvoie la valeur d’une question spécifique dans un enregistrement de répétition. Pour plus d'informations, reportez-vous à la rubrique Répétitions.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Convertit en nombre entier. La conversion varie selon le type de données. Remarque : Si cette fonction est vide, elle renvoie NaN et la question reste vide.	int(${question_one})
join(separator, question)	Concatène toutes les réponses à une question donnée en une répétition, chacune séparée par le séparateur donné.	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	Utilisée pour les questions select_one. Renvoie l’étiquette associée au nom du choix dans la question donnée. N’oubliez pas que la question doit être définie entre guillemets.	jr:choice-name(${select_one}, '${select_one}')
	Utilisée pour les questions select_multiple. Renvoie l’étiquette associée au nom du choix dans la question donnée. La fonction selected-at() doit être utilisée pour extraire l’étiquette des réponses individuelles. N’oubliez pas que la question doit être définie entre guillemets.	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	Renvoie la valeur maximale dans une plage donnée, ou vers une seule question dans des répétitions.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Renvoie la valeur minimale dans une plage donnée, ou vers une seule question dans des répétitions.	min(${question_one}, ${question_two})
not(expression)	Renvoie une valeur false (Faux) si l’expression renvoyait true (Vrai) et renvoie une valeur true (Vrai) si l’expression renvoyait false (Faux).	not(selected(., 'yes'))
now()	Renvoie un horodatage pour cet instant. Cette fonction est utilisée dans les questions time et dateTime. Elle se comporte comme today() dans les questions date.	now()
number(question, expression, or value)	Convertit en nombre. La conversion varie selon le type de données. Remarque : Si cette fonction est vide, elle renvoie NaN et la question reste vide.	number(${question_one})
once()	Si une question possède déjà une valeur, renvoie la valeur existante. Cette fonction est utile si vous utilisez random() ou uuid() dans une question répétée pour s’assurer que la valeur ne change pas lorsque vous parcourez les enregistrements répétés du formulaire.	once(uuid())
position(..)	Renvoie l’index de la enregistrement actuel dans une répétition. Pour plus d'informations, reportez-vous à la rubrique Répétitions.	position(..)
pulldata()	Renvoie une valeur provenant d’un fichier CSV externe. Pour plus d’informations, voir Extraire une valeur d’un fichier CSV.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Renvoie une valeur provenant des métadonnées EXIF d’une image. Pour plus d’informations, voir Extraire des métadonnées d’une image.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Renvoie une valeur d’une question géopoint. Pour plus d’informations, voir Extraire des valeurs de géopoints.	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	Exécute une fonction JavaScript dans le formulaire et renvoie le résultat. Pour plus d’informations, voir Fonctions JavaScript dans les formulaires d’enquête.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Renvoie une valeur d’un objet JSON. Pour plus d’informations, voir Extraire une valeur d’un objet JSON.	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	Interroge une couche d’entités ou une table d’entités ArcGIS, ou le service de carte avec la fonction d’interrogation activée et renvoie le résultat. Pour plus d’informations, reportez-vous à la rubrique Interroger une couche d’entités.	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	Renvoie des informations sur l’appareil ou l’utilisateur connecté. Pour plus d’informations, voir Propriétés concernant l’appareil et l’utilisateur.	pulldata("@property", 'username')
random()	Renvoie une valeur aléatoire comprise entre 0 (inclusive) et 1 (exclusive).	random()
regex()	Applique une expression régulière à la saisie de la question. Renvoie true (vrai) si le modèle est respecté. Pour plus d’informations, reportez-vous à la rubrique Expressions régulières.	regex(., '^\d{5}$')
selected(question, value)	Vérifie si la réponse est sélectionnée. Cette fonction est utilisée pour les questions select_one et select_multiple.	selected(${question_one}, 'a')
selected-at(question, number)	Utilisée pour les questions select_multiple. Renvoie le nom du choix sélectionné pour le nombre donné, en commençant à compter à partir de zéro ; par exemple, « 2 » renvoie le troisième choix sélectionné.	selected-at(${question_one}, 2)
starts-with(string, substring)	Renvoie true (vrai) si la chaîne donnée commence par la sous-chaîne.	starts-with(${question_one}, 'The')
string(question, expression, or value)	Convertit en chaîne. La conversion varie selon le type de données.	string(${question_one})
string-length(question, expression, or value)	Renvoie la longueur d'une chaîne non vide.	string-length(${question_one})
substr(question, start, end)	Renvoie la sous-chaîne commençant par le début spécifié (start) et s’étend jusqu’au caractère à l’index de fin end -1, où start et end commencent à 0.	substr(${question_one}, 1, 2)
sum(repeat)	Renvoie la somme de toutes les réponses à une question donnée dans des répétitions. Pour plus d’informations, reportez-vous à la rubrique Fonctions d’agrégation. Remarque : Lorsqu’elle est utilisée dans l’application de terrain Survey123, cette fonction peut être placée dans la répétition ou en dehors de celle-ci. Si cette fonction doit être utilisée dans l’application Web Survey123, elle doit être placée en dehors de la répétition. Une valeur sum externe à la répétition peut être référencée dans un calcul interne à la répétition.	sum(${question})
today()	Renvoie la date du jour, stockée en interne à midi heure locale. Cette fonction est utilisée dans les questions date.	today()
true()	True	true()
uuid()	Renvoie une chaîne UUID aléatoire.	uuid()
version()	Retourne la version de l'enquête définie dans la feuille de calcul des paramètres.	version()

Les fonctions mathématiques suivantes sont prises en charge dans Survey123 :

Fonction	Description	Exemple
acos(value)	Renvoie l’arc cosinus de la valeur.	acos(${question_one})
asin(value)	Renvoie l’arc sinus de la valeur.	asin(${question_one})
atan(value)	Renvoie l’arc tangent de la valeur.	atan(${question_one})
atan2(value1, value2)	Renvoie l’arc tangent du quotient des valeurs.	atan2(${question_one}, ${question_two})
cos(value)	Renvoie le cosinus de la valeur en tant qu’angle en radians.	cos(${question_one})
sin(value)	Renvoie le sinus de la valeur en tant qu’angle en radians.	sin(${question_one})
tan(value)	Renvoie la tangente de la valeur en tant qu’angle en radians.	tan(${question_one})
exp(value)	Renvoie l'exposant naturel de la valeur.	exp(${question_one})
exp10(value)	Renvoie 10 à la puissance de la valeur.	exp10(${question_one})
log(value)	Renvoie le logarithme naturel de la valeur.	log(${question_one})
log10(value)	Renvoie le logarithme en base 10 de la valeur.	log10(${question_one})
pi()	Renvoie pi.	pi()
pow(value, power)	Renvoie la valeur à la puissance spécifiée.	pow(${question_one}, 3)
round(value, places)	Renvoie la valeur arrondie.	round(${question_one}, 5)
sqrt(value)	Renvoie la racine carrée de la valeur.	sqrt(${question_one})

Contraintes

L’ajout d’une contrainte à une question d’enquête restreint les saisies acceptées pour une réponse. Il peut s’agir d’une plage spécifique de nombres, d’associations de lettres et chiffres ou d’un appariement de motifs général. Dans votre feuille de calcul, l’expression de contrainte est saisie dans le champ de contrainte et du texte informatif est entré dans la colonne constraint_message de la feuille de calcul d’enquête. Dans l’expression de contrainte, la saisie pour la question est toujours représentée par un point final.

Par exemple, la formule suivante permet de restreindre la saisie d’un champ d’entier aux nombres positifs :

.>= 0

Cette formule, lorsqu’elle est appliquée à un champ date, empêche l’utilisateur de saisir une valeur antérieure à la date du jour :

.>= today()

Vous pouvez également utiliser des calculs dans les contraintes. Cette formule effectue un calcul pour que l’utilisateur ne puisse sélectionner que des dates comprises entre la date du jour et 14 jours à partir de la date du jour :

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

Conseil :

Afin d’éviter des erreurs inattendues, si votre formule comprend des valeurs décimales comprises entre -1 et 1, veillez à inclure un zéro de début dans vos valeurs. Sans zéro de début, la valeur décimale peut être prise pour le caractère arithmétique . (ou -.). Par exemple, l’expression suivante échoue :

.> .25 and .< 24.25

L’expression suivante s’exécute comme prévu :

.> 0.25 and .< 24.25

Expressions régulières

Une expression régulière est une séquence de caractères utilisée pour correspondre aux modèles des chaînes. Dans Survey123 si le modèle est respecté, l’expression renvoie true (vrai). Sinon, l’expression renvoie false (faux).

Vous pouvez utiliser des expressions régulières de différentes manières pour l’appariement de modèles afin de restreindre les réponses valides selon un format donné ou de s’assurer qu’elles comportent un contenu spécifique. Cet exemple exige que le mot road apparaisse quelque part dans la réponse à la question :

regex(., 'road')

Le point utilisé au début de ces exemples applique l’expression au champ actuel. L’ajout du nom d’un autre champ à la place applique l’expression régulière à ce champ, ce qui est idéal pour les expressions pertinentes. La virgule fait office de séparateur entre la définition de ce champ et l’expression.

Cette expression régulière garantit que la réponse correspond exactement au mot route, sans rien avant ou après.

regex(., '^road$')

Les expressions régulières sont idéales pour restreindre la saisie d’une question à un format standard. Cet exemple accepte uniquement la saisie d’un code postal à cinq chiffres des États-Unis :

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

Cet exemple correspond à la réponse au format actuel des plaques d’immatriculation indonésiennes, comme sur la photo suivante :

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

Les formats standardisés de façon plus approximative peuvent exiger des expressions régulières complexes. Cette expression régulière utilisée par l’application Web Survey123 nécessite que la saisie d’un champ de chaîne respecte le format d’une adresse électronique :

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,}))$')

Cette modification de l’expression ci-dessus contraint l’entrée à correspondre au format d’une adresse électronique, tout en acceptant les caractères non anglais :

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,}))$')

Cet exemple, qui utilise également une expression régulière provenant de l’application Web Survey123, force un champ à n’accepter que les réponses correspondant au format d’une adresse Web :

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.:-]*)?)?)?')

Pour plus d’informations sur les expressions régulières, reportez-vous à la documentation Mozilla Developer Network. Pour consulter la liste de caractères et leurs fonctions dans les expressions régulières, consultez la feuille de calcul Reference (Référence) dans les modèles Survey123 ou reportez-vous à la rubrique Référence rapide.

Calculs

Les calculs sont effectués dans la colonne calculation (calcul) pour une question. Les calculs sont souvent associés aux questions de type calcul, mais ils peuvent aussi être appliqués à des questions de type entier, décimale, texte et à choix unique. Le résultat du calcul peut être utilisé pour renseigner des expressions pertinentes ou de contrainte en référence à un nom de champ de la question de calcul.

Le type de question à calcul est caché et ne s’affiche plus sur un formulaire. Ceci signifie qu’il peut aussi contenir des valeurs qui n’ont pas besoin d’être affichées sur le formulaire mais qui sont incluses dans la couche d’entités.

Par exemple, vous pouvez créer une question de type calcul et la nommer calc, puis insérer l’expression suivante dans sa colonne calculation (calcul) :

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

Utilisez le résultat pour définir la pertinence pour la question suivante :

${calc} <= 100

Vous pouvez utiliser des calculs avec les réponses dans les champs date. Ce calcul estime le nombre d’années entre une date saisie et la date du jour, ce qui est idéal pour calculer l’âge d’une personne :

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

Parfois, il suffit d’une valeur ou d’une version tronquée d’une réponse complète. L’opérateur substr renvoie seulement une partie d’une chaîne, définie par les nombres qui le suivent. Le premier caractère détermine le point de départ de la sélection, et la deuxième valeur définit la longueur (si aucune deuxième valeur n’est présente, elle continue jusqu’à la fin de la chaîne). Dans cet exemple, l’opérateur substr supprime tout sauf la chaîne à partir des caractères 10 à 15 :

substr(${previous_question}, 10, 15)

Lorsque le premier nombre est négatif, substr commence à compter à partir de la fin de la chaîne plutôt qu’à partir du début. L’exemple suivant renvoie uniquement les cinq derniers caractères de la réponse :

substr(${previous_question}, -5)

Vous pouvez utiliser le paramètre calculationMode pour contrôler le moment où les calculs sont effectués dans le formulaire. Pour plus d’informations, consultez la rubrique Mode de calcul.

Vous pouvez aussi utiliser la colonne calculation (calcul) pour les fonctions d’agrégation des répétitions. Pour plus d'informations, reportez-vous à la rubrique Répétitions.

Adoptez les pratiques conseillées suivantes lorsque vous faites appel à des calculs :

• Lorsque vous utilisez random(), pensez à ajouter une constante pour éviter d’obtenir un résultat égal à zéro (0), par exemple, random()+0.5. La valeur 0 peut entraîner une réponse vide.
• Comme avec les contraintes, assurez-vous que toutes les valeurs de décimales entre -1 et 1 de votre formule aient un zéro de début, car le fait d’avoir une valeur décimale de début entraîne des erreurs.
• Le type de données du résultat d'un calcul dépend du type de données de chaque élément du calcul. Si un calcul est réalisé sur deux entiers, le résultat du calcul est un entier. Si un calcul comprend des données de type chaîne, un opérateur + concaténera les valeurs plutôt que de les additionner. Pour éviter des résultats inattendus, utilisez la fonction number() afin de garantir que les valeurs de chaîne dans un calcul sont traitées comme des nombres. Par exemple, le calcul permettant d’additionner question1 (de type entier) et de question2 (de type texte) est ${question1} + number(${question2}).

Conseil :

Le type de liaison XLSForm par défaut pour une question de type calcul est string. Pour remplacer cette valeur par défaut, saisissez le type requis (par exemple, int ou decimal) dans la colonne bind::type pour votre question. Par ailleurs, vous pouvez utiliser le type de question de votre choix (par exemple, integer ou decimal) et définir l’apparence de cette question sur hidden.

Attention :

L’utilisation de fonctions ou d’opérateurs mathématiques pour les questions de type texte renvoie le résultat NaN dans l’application Web Survey123. Pour concaténer les questions de type texte, utilisez la fonction concat() au lieu de l’opérateur +.

Fonctions mathématiques complexes

La colonne calculation (calcul) peut également traiter des opérations mathématiques plus complexes. Cet exemple calcule la surface d’un tracé à partir de son rayon, avec les fonctions pi et de puissance :

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

Pour mesurer la hauteur d’un arbre, on mesure généralement l’angle à hauteur des yeux entre un point d’observation et le sommet de l’arbre, et la distance entre le même point d’observation et la base de l’arbre. Si l’angle au sommet de l’arbre est mesuré en degrés, le calcul suivant permet de le convertir en radians :

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

Maintenant que la mesure de l’angle est exprimée en radians, la hauteur de l’arbre (arrondie à deux décimales) peut être calculée comme suit :

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

Format de date

Vous pouvez utiliser la fonction format-date dans le champ calculation pour définir le format des valeurs de date et d’heure. Cela peut être utile si vous souhaitez afficher des parties de dates pour les utilisateurs ou les conserver en tant que chaînes.

Dans cet exemple, la valeur contenue dans une question d'heure ou dateTime précédente est renvoyée au format 24 heures :

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

Les qualificateurs pouvant être utilisés dans la fonction format-date sont les suivants :

Qualificateur	Description
%3	Milliseconde avec ajout de 0 (000-999)
%a	Jour en texte court à trois lettres
%b	Nom du mois abrégé
%d	Jour du mois avec ajout de 0
%e	Jour du mois
%h	Heure (format 24 heures)
%H	Heure avec ajout de 0 (format 24 heures)
%m	Mois avec ajout de 0
%M	Minute avec ajout de 0
%n	Mois numérique
%S	Seconde avec ajout de 0
%W	Numéro de semaine Remarque : Le qualificateur %W ne peut pas être utilisé dans une fonction format-date dans laquelle la question de type date fait appel à un calcul. Ce qualificateur fonctionne avec une question de type date dotée d’une valeur par défaut.
%y	Année à 2 chiffres
%Y	Année à 4 chiffres

Remarque :

Les questions dateTime ne prennent pas en charge les résolutions temporelles inférieures à une minute. Pour capturer une résolution temporelle avec des dates inférieures à une minute, utilisez les questions start et end.

Valeurs vides

Lors de l’utilisation de contraintes et de calculs qui font référence à d’autres questions, envisagez ce qui se passe lorsque cette question est vide (c’est-à-dire qu’il n’y a aucune réponse). Les valeurs vides sont représentées de la manière suivante :

• NaN (not a number, pas un nombre) pour les questions d’entiers et de décimales. Il s’agit d'une valeur spéciale qui représente l’absence d’une valeur valide.
• '' (chaîne vide) pour les questions de texte. Le type de données par défaut pour les questions de type select_one (choix unique), select_multiple (choix multiples), rank (classement) et masquées est également texte. Si les types de questions select_one (choix unique), select_multiple (choix multiples) et masquées sont vides ou que le type de question rank (classement) n’a pas été modifié par l’utilisateur, ils contiennent une chaîne vide.

Selon si la valeur est un nombre ou du texte, les comportements lors des calculs diffèrent.

Dans les questions d’entier ou de décimale, le comportement suivant se manifeste :

• Toute expression mathématique contenant une valeur NaN échoue et la question reste vide.
• Les fonctions min() et max() aboutissent et ignorent les valeurs NaN.
• Comparée à d’autres valeurs, la valeur NaN est true (vraie) uniquement dans le calcul d’une valeur de comparaison is not equal. Toutes les autres expressions entraînent la valeur false (faux).

Dans les questions de texte, le comportement suivant se manifeste :

• La concaténation des questions de type texte aboutit si des valeurs vides sont présentes. Par exemple, concat("Hello" + ${firstName}, ", how are you?") donne comme résultat "Hello , how are you?" si la question firstName (Prénom) est vide.
• Les fonctions min() et max() aboutissent et ignorent les chaînes vides.
• Toute réponse de texte vide est égale à une autre réponse de texte vide ; elle est toujours inférieure à du texte non vide.

Vous pouvez déterminer si une question est vide grâce à la fonction string-length. Vous pouvez utiliser la fonction string-length avec tous les types de questions. Par exemple, string-length(${Question1}) renvoie 0 si Question1 est vide.

Vous pouvez également déterminer si une question à choix unique ou à choix multiples est vide grâce à la fonction count-selected. Par exemple, count-selected(${question2}) renvoie 0 si aucune sélection n’a été effectuée pour question2.

Questions de type select_multiple (choix multiples) et rank (classement)

Les réponses aux types de questions select_multiple (choix multiples) et rank (classement) sont enregistrées différemment de tous les autres types de questions. Chaque réponse vérifiée dans une question select_multiple saisie dans l’ordre dans lequel elle a été sélectionnée, séparée par une virgule. Par exemple, le fait de sélectionner les réponses « A » et « B » dans cet ordre présente la réponse sous la forme « A,B ». Une question de type rank (classement) enregistre également ses réponses dans une liste séparée par des virgules dans l’ordre allant du classement le plus élevé au classement le plus bas au moment de l’envoi.

Certaines fonctionnalités XLSForm ne fonctionnent pas avec les questions de type select_multiple (choix multiples) et rank (classement). Par exemple, si vous saisissez la réponse « A » dans la colonne relevant (pertinent) d’une question faisant référence à votre question à choix multiples et que la réponse à l’enquête est « A,B », la réponse n’est pas considérée comme pertinente. Dans ce cas, la solution consiste à utiliser la fonction selected(), qui détermine si l’une des valeurs apparaît dans la liste.

L’expression suivante, lorsqu’elle est utilisée dans la colonne relevant (pertinent) d’une question, affiche la question si l’utilisateur a sélectionné « A » comme l’une des réponses dans la question à choix multiples référencée. La présence d’autres réponses dans la question à choix multiples ne change pas ce comportement.

selected(${previous_question}, 'A')

Extraire une valeur d’un fichier .csv

Vous pouvez utiliser la fonction pulldata() dans la colonne calculation (calcul) d’une question pour précharger des données à partir d’un fichier .csv. Vous pouvez inclure un fichier .csv de deux manières : en plaçant manuellement le fichier dans le dossier media de l’enquête ou en créant un lien vers un fichier .csv hébergé dans ArcGIS.

La fonction pulldata() nécessite que les quatre paramètres suivants soient précisés, dans l’ordre suivant :

1. Nom du fichier .csv qui contient la liste de valeurs. Le nom ne contient pas le suffixe de nom de fichier .csv.
2. Nom de la colonne dans le fichier .csv qui contient la valeur à retourner.
3. Nom du champ de clé dans le fichier .csv que vous allez utiliser pour rechercher la valeur.
4. Valeur de clé à rechercher dans le champ de clé.

Ces valeurs peuvent être définies directement ou via des variables définies ailleurs dans l’enquête. Dans l’exemple suivant, le calcul retourne l’adresse électronique d’une personne nommée dans une question précédente à partir d’un fichier .csv dont le nom est info :

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

Cette même fonction pulldata() peut également être utilisée dans la colonne constraints (contraintes), qui empêche l’utilisateur de fournir des réponses qui ne se trouvent pas dans le fichier .csv. Dans la colonne constraints (contraintes), cette même formule empêche le formulaire d’accepter des valeurs qui ne se trouvent pas dans la colonne name (nom) du fichier .csv.

Certaines restrictions s’appliquent à la fonction pulldata(). Le nom du champ de clé présente la même limitation que la colonne name (nom) dans la feuille de calcul choices (choix), ce qui signifie que ces valeurs ne peuvent pas contenir d’espaces ou de caractères autres qu’ASCII. De plus, ces fichiers étant de type .csv, si l’un des champs contient une virgule, la fonction pulldata() génère des résultats incorrects.

Si votre fichier .csv contient des valeurs comportant plus de 255 caractères, vous devez saisir une valeur plus élevée dans la colonne bind::esri:fieldLength, à la fois pour la question que vous renseignez avec le contenu du fichier .csv et pour toute question utilisée en entrée de la fonction pulldata(). Si certaines valeurs de votre fichier .csv dépassent la longueur maximale de l’un de ces champs, l’envoi d’une réponse à l’enquête échoue et l’erreur Code 1000 s’affiche.

Remarque :

La fonction pulldata() ne permet pas de renseigner les valeurs des questions à choix multiples.

Lorsque vous utilisez la fonction pulldata(), les noms de colonne .csv ne peuvent pas être vides ni contenir d’espaces, de traits d’union, ni d’autres caractères spéciaux.

Il est recommandé d’encoder le fichier .csv à l’aide de l’encodage des caractères UTF-8. Si vous utilisez Microsoft Excel pour créer le fichier .csv, enregistrez-le au format CSV UTF-8.

Extraire une valeur d’un objet JSON

Vous pouvez utiliser la fonction pulldata("@json") pour extraire des propriétés individuelles d’un objet JSON. Cette fonction est généralement utilisée conjointement à d’autres fonctions, telles que pulldata("@javascript") et pulldata("@layer"). La syntaxe de cette fonction est la suivante :

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

Les paramètres pour pulldata("@json") sont les suivants :

• question name : nom de la question qui contient l’objet JSON, par exemple ${json_response}.
• JSON property : propriété à extraire de l’objet JSON. Utilisez des points pour indiquer l’emplacement de la propriété dans la structure JSON. Par exemple, pour extraire la propriété City de l’objet address, utilisez "address.City".

Dans l’exemple suivant, le résultat d’une opération de géocodage inverse est renvoyé sous forme de données JSON dans une question de type texte nommée json_response:

Une réponse du localisateur similaire à l’exemple suivant est renvoyée :

{
    "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
        }
    }
}

La fonction pulldata("@json") est utilisée pour extraire la propriété City de l’objet address :

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

La latitude et la longitude sont extraites de l’objet location :

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

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

Remarque :

Un point permet d’accéder à des propriétés d’un objet parent. Lorsqu’un point fait également partie d’une propriété, il doit être placé entre crochets [ ]. Par exemple, pour extraire une propriété nommée City.Population de l’objet address, l’expression à utiliser est pulldata("@json", ${json_response}, "address.[City.Population]").

Vous pouvez accéder à un objet dans un tableau d’objets en spécifiant sa position entre crochets. L’index d’un tableau JSON commence à zéro. Voici l’exemple d’un objet JSON renvoyé par des attributs intelligents. Il contient un tableau classes :

{
    "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
        }
    ]
}

Pour l’exemple ci-dessus, l’expression suivante renvoie le score 0,67421875 du premier objet dans le tableau classes :

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

Vous pouvez utiliser la propriété length pour renvoyer le nombre d’objets dans un tableau. Pour l’exemple ci-dessus, l’expression suivante renvoie la longueur 3 :

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

Interroger une couche d’entités

Vous pouvez utiliser la fonction pulldata("@layer") pour interroger une couche d’entités, une table d’entités ou un service de carte avec la fonction d’interrogation activée. Vous pouvez effectuer une requête attributaire ou spatiale. Une requête attributaire utilise une opération getRecord ou getValue :

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

Une requête spatiale utilise une opération getRecordAt ou getValueAt :

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

Les opérations getRecord et getRecordAt renvoient un objet d’entité JSON contenant une entité unique et tous ses attributs. Les opérations getValue et getValueAt renvoient une valeur unique provenant de l’objet d’entité au lieu de la réponse à la requête entière.

Les paramètres pour pulldata("@layer") sont les suivants :

Paramètre	Description
JSON property	Obligatoire pour les opérations getValue et getValueAt. Valeur à extraire de la réponse à la requête. Exemples : "attributes.COUNTRY" "geometry"
location	Obligatoire pour les opérations getRecordAt et getValueAt. Localisation du point à interroger avec la couche d’entités. Il doit s’agir d’une question de type géopoint. Exemple : ${location}
URL	(obligatoire). URL de la table ou de la couche d’entités à interroger. Ce paramètre accepte des paramètres de requête supplémentaires. Exemple : "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Facultatif. Expression WHERE qui filtre la table ou la couche d’entités. Si la clause WHERE n’est pas fournie, la valeur par défaut "1=1" est utilisée. Exemple : "COUNTRY='Canada'"

Conseil :

La fonction pulldata("@layer") renvoie le premier enregistrement dans la réponse à la requête. Concevez votre requête et testez-la pour vous assurer que vous obtiendrez les résultats souhaités. Vous pouvez affiner votre requête à l’aide d’une clause WHERE et des paramètres de requête supplémentaires décrit ci-dessous.

La fonction pulldata("@layer") met en cache les réponses aux requêtes à des fins d’efficacité. Pour contrecarrer le cache et vous assurer qu’une demande est créée à chaque exécution de la fonction, ajoutez un paramètre time=now à l’URL (par exemple, concat(${layer_url}, "?t=", now())).

L’exemple suivant interroge une couche d’entités surfaciques de fuseaux horaires et renvoie le fuseau horaire dans lequel se trouve le géopoint :

L’opération getRecordAt est utilisée pour extraire le fuseau horaire dans lequel se trouve le géopoint à l’aide de la syntaxe suivante :

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

L’attribut ZONE est ensuite extrait de la réponse à la requête à l’aide de la fonction pulldata("@json"). Vous pouvez aussi utiliser une opération getValueAt dans le calcul pulldata("@layer") pour extraire l’attribut ZONE directement, sans utiliser de question distincte pour stocker la réponse à la requête. Consultez l’exemple ci-dessous :

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

Vous pouvez utiliser pulldata("@layer") dans des contraintes. Par exemple, vous pouvez appliquer une contrainte à une question de type géopoint pour empêcher les utilisateurs de soumettre des localisations hors d’une zone d’intérêt.

L’opération getRecordAt renvoie un objet d’entité JSON pour le pays dans lequel se trouve le géopoint à l’aide de la syntaxe suivante :

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

Le nom du pays est extrait dans une question de type texte à l’aide de pulldata("@json"). La contrainte ${country}='Canada' est ensuite appliquée à la question de type géopoint pour garantir que la localisation se trouve dans la région du Canada.

Paramètres de requête

Vous pouvez affiner une requête pulldata("@layer") avec des paramètres de requête supplémentaires, tels que distance, orderByFields et resultOffset. Pour plus d’informations sur les paramètres de requête, reportez-vous à la rubrique Requête (Service/Couche d’entités). La fonction pulldata("@layer") prend en charge uniquement les requêtes qui renvoient un objet entité.

Pour inclure ces paramètres dans une requête, ajoutez-les à l’URL après un point d’interrogation. Les paramètres supplémentaires sont séparés par une esperluette. Dans l’exemple suivant, les paramètres orderByFields et resultOffset sont ajoutés à l’URL de la couche d’entités pour renvoyer le nom du dixième comté le plus peuplé en Californie :

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'")

Il est possible d’utiliser une requête agrégée pour renvoyer les statistiques sur une couche d’entités à l’aide du paramètre outStatistics. Les statistiques pouvant être calculées avec ce paramètre incluent le nombre, la somme, le minimum, le maximum, la moyenne, l’écart type et la variance.

Dans l’exemple suivant, le nombre de comtés dans l’état sélectionné est renvoyé :

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}, "'"))

Dans l’exemple suivant, la somme du champ POPULATION pour tous les comtés de l’État sélectionné est renvoyée :

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}, "'"))

Remarque :

La fonction pulldata("@layer") prend en charge tous les paramètres de requête recensés sur la page Query (Feature Service/Layer), à l’exception des suivants :

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

Extraire une localisation d’une liste

Vous pouvez permettre aux utilisateurs d’extraire une localisation d’une couche d’entités, en fonction de leur sélection dans la liste de choix d’une question select_one (sélection unique). Le choix est envoyé sous forme de texte et sa géométrie correspondante est envoyée en tant que localisation pour la réponse à l’enquête. Cette approche est équivalente à celle d’une question de type Liste de localisations dans le concepteur Web Survey123.

Pour créer une liste de localisations, ajoutez une question select_one avec les apparences de recherche et de renseignement automatique. L’apparence de recherche renseigne la liste avec les valeurs d’une couche d’entités. L’apparence de renseignement automatique présente les valeurs dans une liste déroulante, ce qui est utile lorsque la liste renvoyée à partir de la couche d’entités est très longue.

Configurez l’expression search() pour extraire une liste de valeurs d’une couche d’entités. Dans la question de type géopoint, géoforme ou géotrace, ajoutez une expression pulldata("@layer") pour extraire la géométrie pour l’entité sélectionnée dans la liste.

Dans l’exemple suivant, les sondés sélectionnent un compteur d’eau dans une question de type select_one nommée meter_id. La géométrie du compteur d’eau est extraite de la couche d’entités Water Meters (Compteurs d’eau) et enregistrée dans la question de type géopoint :

Pour plus d’informations sur l’apparence de recherche, reportez-vous à la rubrique Recherche.