Formule

È possibile utilizzare le formule per creare modelli più intelligenti con ArcGIS Survey123.

Le domande precedenti devono sempre essere indicate nelle formule con il formato ${field_name}.

Operatori

Survey123 supporta i seguenti operatori:

Operatore	Descrizione	Esempio
.	Risposta corrente	.=1
+	Addizione	${question_one} + 4
-	Sottrazione	${question_one} - 4
*	Moltiplicazione	${question_one} * 4
div	Divisione	${question_one} div 4
=	Uguale a	${price}=9.80
!=	Non uguale	${price}!=9.80
<	Minore di	${price}<9.80
<=	Minore o uguale a	${price}<=9.80
>	Maggiore di	${price}>9.80
>=	Maggiore o uguale a	${price}>=9.80
and	And	${price}>9.00 and ${price}<9.90
mod	Modulo (resto della divisione)	${question_one} mod ${question_two}
or	Oppure	${price}=9.80 or ${price}=9.70

Funzioni

Survey123 supporta le seguenti funzioni:

Funzione	Descrizione
area(question)	Restituisce l'area in metri quadrati di un poligono per le domande geoshape. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: area(${geoshape})
boolean(question, expression, or value)	Restituisce true se il valore fornito non è null. Si consiglia invece di utilizzare boolean-from-string(). Attenzione: Questa funzione restituisce sempre true nell'app Web Survey123. Per le alternative, consultare Valori vuoti. Esempio: boolean(${question_one})
boolean-from-string()	Restituisce true se la stringa fornita è "true" o "1". In caso contrario, restituisce false. Esempio: boolean-from-string(${question_one})
coalesce(value1, value2)	Restituisce il primo valore non vuoto Questa funzione supporta solo due valori. Esempio: coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Restituisce la concatenazione dei valori di stringa. Esempio: concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Restituisce true se la stringa fornita contiene la sottostringa. Esempio: contains(${question_one}, 'red')
count(repeat)	Restituisce la quantità di risposte a una determinata domanda nelle ripetizioni. Per ulteriori informazioni, consultare Funzioni di aggregazione. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Quando utilizzata nell'app da campo Survey123, questa funzione può essere posizionata dentro o fuori della ripetizione. Se la funzione deve essere utilizzata nell'app Web Survey123, deve essere posizionata fuori dalla ripetizione. È possibile fare riferimento a un valore conteggio esterno alla ripetizione in un calcolo all'interno della ripetizione. Esempio: count(${question})
count-selected(question)	Restituisce il numero di risposte selezionate per le domande select_one e select_multiple. Questa funzione restituisce anche il numero di file allegati per le domande di tipo image, audio e file utilizzando l'aspetto multiline. Esempio: count-selected(${question_one})
date(question, expression, or value)	Converte un numero o stringa in un oggetto data, senza mantenere il tempo. Esempio: date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Converte un numero o stringa in un oggetto data. Esempio: date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	Converte un oggetto data in un numero decimale date-time. Esempio: decimal-date-time(${date_question})
decimal-time(question, expression, or string)	Converte un oggetto orario in un numero che rappresenta un giorno frazionario nel fuso orario del dispositivo. Esempio: decimal-time(${time_question})
distance(question)	Restituisce la lunghezza in metri di una polilinea per le domande geotrace. Restituisce la lunghezza in metri del perimetro di un poligono per le domande geoshape. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: distance(${geotrace})
ends-with(string, substring)	Restituisce true se la stringa fornita finisce con la sottostringa. Esempio: ends-with(${question_one}, 'hand.')
false()	False false()
formato-data()	Adatta una data o un'ora esistente a un formato specifico. Esempio: format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Se la condizione è vera, restituisce a; altrimenti, restituisce b. Per ulteriori informazioni, consultare Espressioni condizionali. Esempio: if(selected(${question_one}, 'yes'), 'yes', 'no')
ripetizione indicizzata(domanda, ripetizione, numero indice)	Restituisce il valore da una domanda specifica in un record di ripetizione. Per ulteriori informazioni, fare riferimento alla sezione sulle ripetizioni. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Tronca la parte frazionaria di un numero decimale per restituire un numero intero. Nota: Se questa funzione è vuota restituirà NaN e la domanda rimarrà vuota. Esempio: int(${question_one})
join(separator, question)	Concatena tutte le risposte ad una determinata domanda in una ripetizione, separate dal separatore specificato. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Quando utilizzata nell'app da campo Survey123, questa funzione può essere posizionata dentro o fuori della ripetizione. Se la funzione deve essere utilizzata nell'app Web Survey123, deve essere posizionata fuori dalla ripetizione. È possibile fare riferimento a un valore di unione dall'esterno della ripetizione in un calcolo interno alla ripetizione. Esempio: join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	Utilizzato per le domande select_one. Restituisce l'etichetta associata al nome della scelta nella domanda specificata. Tenere presente che la domanda deve essere definita all'interno di virgolette. Esempio: jr:choice-name(${select_one}, '${select_one}')
	Utilizzato per le domande select_multiple. Restituisce l'etichetta associata al nome della scelta nella domanda specificata. La funzione selected-at() deve essere usata per estrarre l'etichetta delle singole risposte. Tenere presente che la domanda deve essere definita all'interno di virgolette. Esempio: jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	Restituisce il valore massimo in un determinato intervallo o a una singola domanda nelle ripetizioni. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: max(${question_one}, ${question_two})
min(value1, value2, ...)	Restituisce il valore minimo in un determinato intervallo o a una singola domanda nelle ripetizioni. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: min(${question_one}, ${question_two})
not(expression)	Restituisce un valore 'false' se l'espressione restituisce vero e un valore 'true' se l'espressione restituisce falso. Esempio: not(selected(., 'yes'))
now()	Restituisce un indicatore data e ora per questo momento. Questa funzione è utilizzata nelle domande time e dateTime. Si comporta come today() nelle domande date. Esempio: now()
number(question, expression, or value)	Converte una stringa di cifre in un valore numerico. Nota: Se questa funzione è vuota restituirà NaN e la domanda rimarrà vuota. Esempio: number(${question_one})
once()	Se una domanda ha già un valore, restituisce il valore esistente. Questa funzione è utile quando si utilizza random() o uuid() in una domanda ripetuta per garantire che il valore non cambi quando si scorrono i record ripetuti nel modulo. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: once(uuid())
posizione(...)	Restituisce l'indice del record corrente in una ripetizione. Per ulteriori informazioni, fare riferimento alla sezione sulle ripetizioni. Esempio: position(..)
pulldata()	Restituisce un valore da un file CSV esterno. Per ulteriori informazioni, consultare Recuperare un valore da CSV. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Esempio: pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Restituisce un valore dai metadati EXIF in un'immagine. Per ulteriori informazioni, consultare Estrarre metadati immagine. Esempio: pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Restituisce un valore da una domanda geopoint. Per ulteriori informazioni, consultare Estrarre valori geopoint. Esempio: pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	Esegue una funzione JavaScript nel modulo e restituisce il risultato. Per ulteriori informazioni, consultare Funzioni JavaScript nei moduli del rilevamento. Esempio: pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Restituisce un valore da un oggetto JSON. Per ulteriori informazioni, consultare Recuperare un valore da JSON. Esempio: pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	Interroga un feature layer o una tabella feature ArcGIS oppure un servizio mappa abilitato alle interrogazioni e restituisce il risultato. Per ulteriori informazioni, vedi Interrogazione di un feature layer. Esempio: pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	Restituisce informazioni sull'utente o dispositivo connesso. Per ulteriori informazioni, consultare Proprietà dei dispositivi e degli utenti. Esempio: pulldata("@property", 'username')
random()	Restituisce un valore casuale compreso tra 0 (incluso) e 1 (escluso). Esempio: random()
regex()	Applica un'espressione regolare all'input della domanda. Restituisce true se il modello è corrispondente. Per ulteriori informazioni, consultare Espressioni regolari. Esempio: regex(., '^\d{5}$')
selected(question, value)	Verifica se la risposta è selezionata. Questa funzione è utilizzata per le domande select_one e select_multiple. Esempio: selected(${question_one}, 'a')
selected-at(question, number)	Utilizzato per le domande select_multiple. Restituisce il nome della scelta selezionata per il numero specificato, conteggiato a partire da zero; ad esempio, '2' restituisce la terza scelta selezionata. Esempio: selected-at(${question_one}, 2)
starts-with(string, substring)	Restituisce true se la stringa fornita inizia con la sottostringa. Esempio: starts-with(${question_one}, 'The')
string(question, expression, or value)	Converte in stringa. La conversione varia in base al tipo di dati. Esempio: string(${question_one})
string-length(question, expression, or value)	Restituisce la lunghezza di una stringa non vuota. Esempio: string-length(${question_one})
substr(question, start, end)	Restituisce una sottostringa che parte dall'inizio specificato e si estende fino al carattere in corrispondenza dell'indice end -1, dove i valori di inizio e fine partono da 0. Quando l'inizio è negativo, la funzione comincia a contare dalla fine della stringa. Esempi: substr(${question_one}, 1, 2) substr(${question_one}, -5)
sum(repeat)	Restituisce la somma di tutte le risposte a una determinata domanda nelle ripetizioni. Per ulteriori informazioni, consultare Funzioni di aggregazione. Nota: Questa funzione non è supportata in Survey123 Studio o Survey123 Mobile. Quando utilizzata nell'app da campo Survey123, questa funzione può essere posizionata dentro o fuori della ripetizione. Se la funzione deve essere utilizzata nell'app Web Survey123, deve essere posizionata fuori dalla ripetizione. È possibile fare riferimento a un valore somma esterno alla ripetizione in un calcolo all'interno della ripetizione. Esempio: sum(${question})
today()	Restituisce la data odierna, memorizzata internamente come mezzogiorno locale. Questa funzione è utilizzata nelle domande date. Esempio: today()
true()	True Esempio: true()
uuid()	Restituisce una stringa UUID casuale. Esempio: uuid()
version()	Restituisce la versione del rilevamento definito nel foglio di lavoro delle impostazioni. Esempio: version()

Le seguenti funzioni matematiche sono supportate in Survey123:

Funzione	Descrizione	Esempio
acos(value)	Restituisce l'arco coseno del valore.	acos(${question_one})
asin(value)	Restituisce il seno dell'arco del valore.	asin(${question_one})
atan(value)	Restituisce l'arco tangente del valore.	atan(${question_one})
atan2(value1, value2)	Restituisce l'arco tangente del quoziente dei valori.	atan2(${question_one}, ${question_two})
cos(value)	Restituisce il coseno del valore come angolo in radianti.	cos(${question_one})
sin(value)	Restituisce il seno del valore come angolo in radianti.	sin(${question_one})
tan(value)	Restituisce la tangente del valore come angolo in radianti.	tan(${question_one})
exp(value)	Restituisce l'esponente naturale del valore.	exp(${question_one})
exp10(value)	Restituisce 10 alla potenza del valore.	exp10(${question_one})
log(value)	Restituisce il logaritmo naturale del valore.	log(${question_one})
log10(value)	Restituisce il logaritmo in base 10 del valore.	log10(${question_one})
pi()	Restituisce pi greco.	pi()
pow(value, power)	Restituisce il valore alla potenza specificata.	pow(${question_one}, 3)
round(value, places)	Restituisce il valore arrotondato.	round(${question_one}, 5)
sqrt(value)	Restituisce la radice quadrata del valore.	sqrt(${question_one})

Vincoli

Aggiungere un vincolo a una domanda del rilevamento limita gli input accettati per una risposta. Ciò può includere un intervallo specifico di numeri, combinazioni di lettere e numeri o corrispondenze generiche. Nel foglio di calcolo, l'espressione del vincolo viene immessa nel campo constraint, mentre il testo informativo viene immesso nella colonna constraint_message del foglio di lavoro del rilevamento. Nell'espressione constraint, l'input per la domanda è sempre rappresentato da un punto.

Ad esempio, è possibile utilizzare la formula seguente per limitare l'input di un campo con numero intero ai soli numeri positivi:

.>= 0

Questa formula, quando applicata a un campo date, impedisce all'utente di immettere un valore precedente alla data odierna:

.>= today()

È anche possibile utilizzare i calcoli nelle limitazioni. Questa formula effettua un calcolo per consentire solo all'utente di selezionare date comprese tra oggi e 14 giorni a partire da oggi:

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

Suggerimento:

Per evitare errori imprevisti, se la formula include valori decimali compresi tra -1 e 1, includi uno zero iniziale nei valori. Senza lo zero iniziale, il valore decimale può essere interpretato erroneamente come il carattere dell'operatore (. oppure -.). Ad esempio, la seguente espressione non sarà corretta:

.> .25 and .< 24.25

Invece la seguente espressione sarà corretta:

.> 0.25 and .< 24.25

Espressioni regolari

Un'espressione regolare è una sequenza di caratteri utilizzata per abbinare i modelli nelle stringhe. In Survey123, se il modello viene abbinato, l'espressione restituirà true, altrimenti se il modello non viene abbinato l'espressione restituirà false.

Puoi utilizzare le espressioni regolari in vari modi per confrontare modelli, limitare le risposte valide a un determinato formato o assicurarti che contengano contenuto specifico. Questo esempio richiede che la risposta alla domanda includa la parola road al suo interno:

regex(., 'road')

Il punto usato all’inizio di questi esempi applica l’espressione al campo attuale. Se si aggiunge il nome di un altro campo al suo posto si applica invece tale espressione regolare a quel campo, il che risulta ideale per le espressioni di rilevanza. La virgola funge da separatore tra la definizione di questo campo e l'espressione.

Questa espressione regolare garantisce che la risposta corrisponda esattamente alla parola road, senza alcun carattere prima o dopo di essa.

regex(., '^road$')

Le espressioni regolari sono ideali per limitare l’input di una domanda ad un formato standard. Questo esempio accetta solo l’input di un codice postale a cinque cifre degli Stati Uniti:

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

Questo esempio abbina la risposta al formato attuale delle targhe indonesiane come nella seguente foto:

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

I formati meno standardizzati possono richiedere espressioni regolari complesse. Questa espressione regolare utilizzata dall'app Web Survey123 limita l'input di un campo stringa a un formato di indirizzo e-mail:

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

Questa modifica dell'espressione precedente limita l'input al formato di un indirizzo e-mail, accettando al tempo stesso caratteri non inglesi.

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

Questo esempio, in cui si utilizza anche un’espressione regolare dall’app Web Survey123, limita un campo ad accettare solo risposte che corrispondono al formato di un indirizzo 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.:-]*)?)?)?')

Per maggiori informazioni sulle espressioni regolari, fare riferimento alla documentazione di Mozilla Developer Network. Per un elenco dei caratteri e delle relative funzioni nelle espressioni regolari, vedi il foglio di lavoro Riferimento nei modelli di Survey123 oppure Espressioni.

Calcoli

Il valore di una domanda può essere calcolato immettendo un'espressione nella relativa colonna calculation. Puoi applicare calcoli ai tipi di domanda che memorizzano testo, numeri, date, ore o posizioni.

Il tipo di domanda calculate è nascosto e non viene visualizzato nel modulo. Ciò significa che può essere utilizzato per contenere valori che non devono essere visualizzati nel modulo ma che sono inclusi nel feature layer. Il risultato del calcolo può essere utilizzato per popolare le espressioni relevant o constraint facendo riferimento al nome del campo della domanda calculate.

Ad esempio, puoi creare una domanda calculate, assegnarle il nome calc e inserire la seguente espressione nella relativa colonna calculation:

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

Utilizzare il risultato per impostare la rilevanza per la domanda successiva:

${calc} <= 100

Le risposte alle domande di tipo date possono essere utilizzate nei calcoli. Il seguente calcolo stima il numero di anni trascorsi tra una data immessa e la data odierna, ideale per calcolare l'età di una persona:

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

A volte occorre solo parte di un valore o una versione troncata di una risposta completa. La funzione substr() restituisce una parte di una stringa a partire dalla posizione iniziale specificata fino alla posizione finale (esclusa). Se non viene specificata una posizione finale, la sottostringa continua fino alla fine della stringa. In questo esempio, la funzione substr() restituisce i caratteri dalla posizione 10 alla posizione 14 (incluse):

substr(${previous_question}, 10, 15)

Quando la posizione iniziale è negativa, la funzione substr() inizia a contare dalla fine della stringa anziché dall'inizio. Questo esempio restituisce gli ultimi cinque caratteri della stringa:

substr(${previous_question}, -5)

È possibile utilizzare il parametro calculationMode per controllare quando vengono eseguiti i calcoli nel modulo. Per ulteriori informazioni, consultare Modalità di calcolo.

È anche possibile usare la colonna Calcolo per le funzioni aggregate nelle ripetizioni. Per ulteriori informazioni, fare riferimento alla sezione sulle ripetizioni.

Rispettare le buone prassi seguenti quando si utilizzano calcoli:

• Quando utilizzi la funzione random(), valuta l'aggiunta di una costante per evitare di ottenere zero (0) come risultato, ad esempio random()+0.5. Un valore di 0 può portare a una risposta vuota.
• Come avviene per i vincoli, assicurarsi che tutti i valori decimali tra -1 e 1 nella formula siano preceduti da uno 0, perché una virgola decimale iniziale causa degli errori.
• Il tipo di dati del risultato di un calcolo dipende dal tipo di dati di ciascun elemento del calcolo. Se un calcolo viene eseguito su due numeri interi, il risultato sarà un numero intero. Se un calcolo include un tipo di dati stringa, l'operatore + concatenerà i valori invece che sommarli. Per evitare risultati imprevisti, utilizza la funzione number() per assicurarti che i valori stringa in un calcolo vengano trattati come numeri. Ad esempio, il calcolo per aggiungere question1 (di tipo intero) a question2 (di tipo testo) è ${question1} + number(${question2}).

Suggerimento:

Il tipo di binding predefinito di XLSForm per una domanda di calcolo è string. Per sovrascrivere questa impostazione predefinita, inserire il tipo richiesto (per esempio, int o decimal) nella colonna bind::type della domanda. In alternativa, è possibile usare il tipo di domanda desiderato (per esempio, integer o decimal) e impostare l'aspetto di questa domanda come hidden.

Attenzione:

L'uso di funzioni matematiche o operatori con domande di tipo testo restituisce un risultato NaN nell'app Web Survey123. Per concatenare domande di tipo testo, utilizzare la funzione concat() invece dell'operatore +.

Funzioni matematiche complesse

La colonna Calcolo è anche in grado di gestire operazioni matematiche più complesse. Questo esempio determina l'area di un appezzamento in base al suo raggio utilizzando le funzioni pi e power:

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

Un metodo comune per misurare l'altezza di un albero consiste nel misurare l'angolo dal livello degli occhi in un punto di osservazione alla cima dell'albero e la distanza dallo stesso punto di osservazione alla base dell'albero. Se l'angolo verso la cima dell'albero viene misurato in gradi, verrà utilizzato il seguente calcolo per convertirlo in radianti:

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

Con l'angolo di misurazione ora in radianti, l'altezza dell'albero (arrotondata a due cifre decimali) può essere determinata con il seguente calcolo:

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

Formattazione data

Puoi utilizzare la funzione format-date() nella colonna calculation per formattare i valori di data e ora delle domande date, time e dateTime. Ciò può essere utile per mostrare agli utenti parti di date o mantenerle come stringhe.

In questo esempio, il valore contenuto in una domanda time o dateTime precedente viene restituito in formato di 24 ore:

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

I qualificatori che possono essere utilizzati nella funzione format-date() sono i seguenti:

Qualificatore	Descrizione
%3	Millisecondo con 0 iniziale (000-999)
%a	Nome breve del giorno di tre lettere
%b	Nome mese abbreviato
%d	Giorno del mese con 0 iniziale
%e	Giorno del mese
%h	Ora (formato di 24 ore)
%H	Ora completata con 0 (formato di 24 ore)
%m	Mese con 0 iniziale
%M	Minuto con 0 iniziale
%n	Mese numerico
%S	Secondo con 0 iniziale
%W	Numero della settimana (definito dalla norma ISO 8601) Nota: Il qualificatore %W non può essere utilizzato nella funzione format-date() quando la domanda di tipo date utilizza un calcolo. Questo qualificatore funziona con una domanda data che presenta un valore predefinito. Il qualificatore %W non è supportato nell'app web.
%y	Anno a 2 cifre
%Y	Anno a 4 cifre

Nota:

Le domande dateTime non supportano le risoluzioni di tempo inferiori a un minuto. Per catturare una risoluzione di tempo con le date inferiore a un minuto, considerare l'utilizzo delle domande start e end.

La funzione format-date() non è supportata per le domande di tipo time nell'app Web Survey123.

Valori vuoti

Quando si utilizzano vincoli e calcoli che fanno riferimento ad altre domande, considerare cosa accade quando la domanda è vuota, ovvero non contiene una risposta. I valori vuoti sono rappresentati nel seguente modo:

• NaN (non un numero) per domande integer e decimal. Questo è un valore speciale che rappresenta l'assenza di un valore valido.
• '' (una stringa vuota) per domande text. Il tipo di dati predefinito per le domande select_one, select_multiple, rank e hidden è anch'esso text. Quando i tipi di domanda select_one, select_multiple e hidden sono vuoti o quando una domanda rank non è stata modificata dall'utente, contengono una stringa vuota.

A seconda che il valore sia un numero o del testo, il comportamento nei calcoli cambia.

Nelle domande integer o decimal, si verificano i seguenti comportamenti:

• Un'espressione matematica con un valore NaN non viene completata e la domanda rimane vuota.
• Le funzioni min() e max() vengono completate ignorando eventuali valori NaN.
• Rispetto ad altri valori, il valore NaN è true solo in un calcolo di confronto tra valori is not equal. Tutte le altre espressioni risultano false.

Nelle domande text, si verificano i seguenti comportamenti:

• La concatenazione di domande text viene completata se sono presenti dei valori vuoti. Ad esempio, concat("Hello" + ${firstName}, ", how are you?") dà come risultato "Hello , how are you?" quando la domanda firstName è vuota.
• Le funzioni min() e max() vengono completate ignorando eventuali stringhe vuote.
• Una risposta a una domanda text vuota è uguale a un’altra risposta a una domanda text vuota ed è sempre inferiore rispetto a un testo non vuoto.

È possibile determinare se una domanda è vuota con la funzione string-length. La funzione string-length può essere utilizzata con tutti i tipi di domande. Ad esempio, string-length(${Question1}) restituisce 0 se Question1 è vuota.

È anche possibile determinare se una domanda select_one o select_multiple è vuota con la funzione count-selected. Ad esempio, count-selected(${question2}) restituisce 0 se non si è effettuata alcuna selezione per question2.

Domande select_multiple e rank

Nota:

Le domande di tipo rank sono attualmente supportate solo nell'app di campo Survey123 e nell'app WebSurvey123.

Le risposte ai tipi di domanda select_multiple e rank vengono memorizzate in modo diverso rispetto a tutti gli altri tipi di domanda. Ciascuna risposta selezionata in una domanda select_multiple immessa nell'ordine in cui è stata selezionata, separate da virgole. Ad esempio, selezionando le risposte 'A' e 'B' in questo ordine mostra le risposte come 'A,B'. Anche una domanda rank memorizza le risposte in un elenco separato da virgole, in un ordine che va dalla classificazione più alta a quella più bassa al momento dell'invio.

Alcune funzioni di XLSForm non si applicano alle domande select_multiple e rank. Ad esempio, se si immette la risposta "A" nella colonna Rilevante di una domanda che fa riferimento alla propria domanda select_multiple e la risposta del rilevamento è "A,B", la risposta non viene considerata rilevante. In questo caso, la soluzione consiste nell'utilizzare la funzione selected(), che determina se uno dei valori compare nell'elenco.

La seguente espressione, se utilizzata nella colonna Rilevante di una domanda, mostra la domanda se l'utente ha selezionato "A" come una delle risposte nella domanda select_multiple di riferimento. Risposte aggiuntive a una domanda select_multiple non cambiano questo comportamento.

selected(${previous_question}, 'A')

Recuperare un valore da un file .csv

Nota:

Questa sezione descrive le funzionalità disponibili solo in Survey123 Connect e nell'app da campo Survey123. Queste funzionalità non sono disponibili in Survey123 Studio o Survey123 Mobile.

È possibile utilizzare la funzione pulldata() nella colonna di calcolo di una domanda per precaricare i dati di un file .csv. Esistono due modi per includere un file .csv: inserire manualmente il file nella cartella media del rilevamento oppure collegare un file .csv .

La funzione pulldata() richiede che i seguenti quattro parametri vengano specificati nell'ordine indicato:

• Il nome del file .csv che contiene l'elenco di valori. Il nome non include il suffisso .csv nel nome del file.
• Il nome della colonna nel file .csv che contiene il valore che si desidera restituire.
• Il nome del campo chiave nel file .csv che verrà utilizzato per ricercare il valore.
• Il valore chiave da ricercare nel campo chiave.

Questi valori possono essere definiti direttamente o tramite variabili definite altrove nel rilevamento. Nell'esempio seguente, il calcolo restituisce l'indirizzo e-mail di una persona indicata in una domanda precedente da un file .csv denominato info:

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

La stessa funzione pulldata() si applica anche alla colonna Vincoli e impedisce all'utente di inviare risposte che non siano nel file .csv. Nella colonna Vincoli, questa stessa formula impedisce al modulo di accettare valori che non si trovano nella colonna Nome del file .csv.

Vi sono alcune limitazioni alla funzione pulldata(). Il nome del campo chiave presenta la stessa limitazione della colonna Nome nel foglio di calcolo Scelte, ovvero questi valori non possono contenere spazi o caratteri non ASCII. Inoltre, poiché si tratta di file .csv, l'uso della virgola in questi campi fa sì che la funzione pulldata() produca risultati non corretti.

Se i valori nel file .csv superano i 255 caratteri, devi immettere un valore maggiore nella colonna bind::esri:fieldLength sia per la domanda che viene popolata con il contenuto del file .csv sia per tutte le domande utilizzate come input della funzione pulldata(). Se il file .csv include valori che superano la lunghezza massima di uno di questi campi, l'invio di una risposta al rilevamento non riesce e viene visualizzato un errore Codice 1000.

Nota:

La funzione pulldata() non può essere utilizzata per compilare i valori di domande select_multiple.

Quando si utilizza la funzione pulldata(), i nomi delle colonne .csv non possono essere vuoti o contenere spazi, trattini o altri caratteri speciali.

Si consiglia di codificare il file .csv utilizzando la codifica dei caratteri UTF-8. Se utilizzi Microsoft Excel per creare il file .csv, salvalo in formato CSV UTF-8.

Recuperare un valore da JSON

È possibile utilizzare la funzione pulldata("@json") per estrarre proprietà individuali da un oggetto JSON. Questa funzione è spesso utilizzata in modo complementare ad altre funzioni, ad esempio pulldata("@javascript") e pulldata("@layer"). La funzione ha la seguente sintassi:

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

I parametri per pulldata("@json") sono i seguenti:

• question name: il nome della domanda contenente l'oggetto JSON, ad esempio: ${json_response}.
• JSON property: la proprietà che si desidera recuperare dal JSON. Utilizzare i punti per specificare la posizione della proprietà nella struttura JSON. Ad esempio, per recuperare la proprietà City dall'oggetto address, utilizzare "address.City".

Nel seguente esempio, il risultato di un'operazione di geocodifica inversa viene restituito come JSON in una domanda di testo denominata json_response:

Viene restituita una risposta del localizzatore simile alla seguente:

{
    "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 funzione pulldata("@json") viene utilizzata per recuperare la proprietà City dall'oggetto address nell'esempio seguente:

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

La latitudine e la longitudine vengono recuperate dall'oggetto location come segue:

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

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

Nota:

Viene utilizzato il punto per accedere alle singole proprietà di un oggetto padre. Quando anche un punto fa parte di una proprietà, deve essere racchiuso tra parentesi quadre [ ]. Ad esempio, per recuperare una proprietà denominata City.Population dall'oggetto address, l'espressione sarà pulldata("@json", ${json_response}, "address.[City.Population]").

È possibile accedere a un oggetto in un array di oggetti specificando la sua posizione nell'array racchiusa da parentesi quadre. L'indice di un array JSON inizia da zero. L'esempio seguente mostra un oggetto JSON restituito dagli attributi intelligenti. Contiene un array 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
        }
    ]
}

Per l'esempio precedente, la seguente espressione restituisce il punteggio di 0.67421875 dal primo oggetto nell'array classes:

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

È possibile utilizzare la proprietà length per restituire il numero di oggetti in un array. Per l'esempio precedente, la seguente espressione restituisce una lunghezza di 3:

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

Interrogazione di un feature layer

Puoi utilizzare la funzione pulldata("@layer") per interrogare un feature layer, una tabella feature o un map service abilitato alle interrogazioni. È possibile eseguire un'interrogazione attributo o un'interrogazione spaziale. Un'interrogazione attributo utilizza un'operazione getRecord oppure getValue, come mostrato nell'esempio seguente:

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

Un'interrogazione spaziale utilizza un'operazione getRecordAt oppure getValueAt, come mostrato nell'esempio seguente:

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

Nota:

La posizione specificata in una interrogazione spaziale deve essere una domanda geopoint.

Le operazioni getRecord e getRecordAt restituiscono un oggetto feature JSON contenente una singola feature e tutti i relativi attributi. Le operazioni getValue e getValueAt restituiscono un singolo valore dall'oggetto feature invece dell'intera risposta all'interrogazione.

Nota:

L'operazione getRecord non può essere utilizzata per recuperare feature polilinea o poligono in Survey123 Studio oppure Survey123 Mobile.

I parametri per pulldata("@layer") sono i seguenti:

Parametro	Descrizione
JSON property	Il valore da richiamare dalla risposta all'interrogazione. Questo parametro è obbligatorio per le operazioni getValue e getValueAt. Esempi: "attributes.COUNTRY" "geometry"
location	La posizione del punto da interrogare con il feature layer. Deve essere una domanda geopoint. Questo parametro è obbligatorio per le operazioni getRecordAt e getValueAt. Esempio: ${location}
URL	L'URL del feature layer o della tabella feature da interrogare. Questo parametro accetta parametri di richiesta aggiuntivi. Questo parametro è obbligatorio. Esempio: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Un'espressione WHERE che filtra il feature layer o la tabella. Quando non viene fornita la clausola WHERE, viene utilizzato un valore predefinito di "1=1". Questo parametro è opzionale. Esempio: "COUNTRY='Canada'"

Suggerimento:

La funzione pulldata("@layer") restituisce il primo record nella risposta all'interrogazione. Progetta e verifica l'interrogazione per assicurarti di ottenere i risultati desiderati. È possibile restringere l'interrogazione utilizzando una clausola WHERE e gli altri parametri di richiesta descritti di seguito.

La funzione pulldata("@layer") memorizza in cache le risposte alle interrogazioni per una maggiore efficienza. Per bypassare la cache e assicurarti che venga effettuata una nuova richiesta ogni volta che la funzione viene eseguita, aggiungi un parametro time=now all'URL, ad esempio concat(${layer_url}, "?t=", now()).

L'esempio seguente interroga un feature layer poligono dei fusi orari mondiali e restituisce il fuso orario in cui si trova il geopoint:

L'operazione getRecordAt consente di richiamare il fuso orario intersecato dal geopoint utilizzando la seguente sintassi:

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

L'attributo ZONE, quindi, viene estratto dalla risposta all'interrogazione utilizzando la funzione pulldata("@json"). In alternativa, puoi utilizzare un'operazione getValueAt nel calcolo pulldata("@layer") per recuperare direttamente l'attributo ZONE senza dover utilizzare una domanda separata per memorizzare la risposta dell'interrogazione. Vedere l'esempio seguente:

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

È possibile utilizzare pulldata("@layer") nei vincoli. Ad esempio, puoi applicare un vincolo a una domanda geopoint per impedire agli utenti di inviare posizioni al di fuori di un'area di interesse, come mostrato nell'immagine seguente.

L'operazione getRecordAt restituisce l'oggetto feature JSON per il paese in cui si trova il geopoint utilizzando la seguente sintassi:

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

Il nome del paese viene estratto in una domanda testo utilizzando pulldata("@json"). Alla domanda geopoint viene quindi applicato un vincolo ${country}='Canada' per garantire che la posizione rientri nella regione del Canada.

Parametri della richiesta

È possibile restringere un'interrogazione pulldata("@layer") con ulteriori parametri di richiesta, ad esempio distance, orderByFields e resultOffset. Per ulteriori informazioni sui parametri della richiesta, vedi Interrogazione (Feature Service/Layer). La funzione pulldata("@layer") supporta solo le richieste che restituiscono un oggetto feature.

Per includere questi parametri in un'interrogazione, accodali all'URL dopo un punto interrogativo. Ulteriori parametri sono separati dal carattere "&". Nell'esempio seguente, i parametri orderByFields e resultOffset sono accodati all'URL del feature layer per restituire il nome delle dieci contee più popolose in California:

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

Può essere utilizzata un'interrogazione aggregata per restituire statistiche in un feature layer utilizzando il parametro outStatistics. Le statistiche che possono essere calcolate con questo parametro includono conteggio, somma, minimo, massimo, media, deviazione standard e varianza.

Nel seguente esempio, viene restituito il conteggio di contee nello stato selezionato:

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

Nel seguente esempio, viene restituita la somma del campo POPULATION per tutte le contee dello stato selezionato:

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

Nota:

La funzione pulldata("@layer") supporta tutti i parametri di richiesta elencati in Interrogazione (Feature Service/Layer), eccetto i seguenti:

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

Recuperare una posizione da un elenco

Nota:

Questa sezione descrive le funzionalità disponibili solo in Survey123 Connect e nell'app da campo Survey123. Queste funzionalità non sono disponibili in Survey123 Studio o Survey123 Mobile.

Puoi consentire agli utenti di recuperare una posizione da un feature layer in base alla selezione effettuata da un elenco di scelte in una domanda select_one. La scelta viene inviata come testo e la geometria corrispondente viene inviata come posizione per la risposta al rilevamento. Questo approccio è equivalente a una domanda di elenco di posizioni nel web designer Survey123.

Per creare un elenco di posizioni, aggiungi una domanda select_one con gli aspetti search e autocomplete come segue:

• L'aspetto di ricerca compila l'elenco con i valori di un feature layer. Per ulteriori informazioni su come configurare l'espressione search(), vedi Crea un elenco di scelte dinamico utilizzando l'aspetto search.
• L'aspetto autocomplete presenta i valori in un elenco a discesa, utile quando dal feature layer viene restituito un elenco molto lungo.

In una domanda geopoint, geoshape o geotrace, aggiungi un'espressione pulldata("@layer") per recuperare la geometria della feature selezionata dall'elenco.

Nel seguente esempio, gli intervistati selezionano un contatore dell'acqua da una domanda select_one denominata meter_id. La geometria del contatore dell'acqua viene recuperata dal feature layer Contatori dell'acqua e viene salvata nella domanda geopoint: