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	Esempio
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.	boolean(${question_one})
boolean-from-string()	Restituisce true se la stringa fornita è "true" o "1". In caso contrario, restituisce false.	boolean-from-string(${question_one})
coalesce(value1, value2)	Restituisce il primo valore non vuoto Questa funzione supporta solo due valori.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Restituisce la concatenazione dei valori di stringa.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Restituisce true se la stringa fornita contiene la sottostringa.	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: 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.	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.	count-selected(${question_one})
date(question, expression, or value)	Converte un numero o stringa in un oggetto data, senza mantenere il tempo.	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Converte un numero o stringa in un oggetto data.	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.	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.	decimal-time(${time_question})
ends-with(string, substring)	Restituisce true se la stringa fornita finisce con la sottostringa.	ends-with(${question_one}, 'hand.')
false()	False	false()
formato-data()	Adatta una data o un'ora esistente a un formato specifico.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Se la condizione è vera, restituisce a; altrimenti, restituisce b.	if(selected(${question_one}, 'yes') and selected(${question_two}, '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.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Converte in intero. La conversione varia in base al tipo di dati. Nota: Se questa funzione è vuota restituirà NaN e la domanda rimarrà vuota.	int(${question_one})
join(separator, question)	Concatena tutte le risposte ad una determinata domanda in una ripetizione, separate dal separatore specificato. Nota: 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.	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.	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.	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.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Restituisce il valore minimo in un determinato intervallo o a una singola domanda nelle ripetizioni.	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.	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.	now()
number(question, expression, or value)	Converte in numero. La conversione varia in base al tipo di dati. Nota: Se questa funzione è vuota restituirà NaN e la domanda rimarrà vuota.	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.	once(uuid())
posizione(...)	Restituisce l'indice del record corrente in una ripetizione. Per ulteriori informazioni, fare riferimento alla sezione sulle ripetizioni.	position(..)
pulldata()	Restituisce un valore da un file CSV esterno. Per ulteriori informazioni, consultare Recuperare un valore da CSV.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Restituisce un valore dai metadati EXIF in un'immagine. Per ulteriori informazioni, consultare Estrarre metadati immagine.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Restituisce un valore da una domanda geopoint. Per ulteriori informazioni, consultare Estrarre valori geopoint.	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.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Restituisce un valore da un oggetto JSON. Per ulteriori informazioni, consultare Recuperare un valore da JSON.	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.	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.	pulldata("@property", 'username')
random()	Restituisce un valore casuale compreso tra 0 (incluso) e 1 (escluso).	random()
regex()	Applica un'espressione regolare all'input della domanda. Restituisce true se il modello è corrispondente. Per ulteriori informazioni, consultare Espressioni regolari.	regex(., '^\d{5}$')
selected(question, value)	Verifica se la risposta è selezionata. Questa funzione è utilizzata per le domande select_one e select_multiple.	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.	selected-at(${question_one}, 2)
starts-with(string, substring)	Restituisce true se la stringa fornita inizia con la sottostringa.	starts-with(${question_one}, 'The')
string(question, expression, or value)	Converte in stringa. La conversione varia in base al tipo di dati.	string(${question_one})
string-length(question, expression, or value)	Restituisce la lunghezza di una stringa non vuota.	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.	substr(${question_one}, 1, 2)
sum(repeat)	Restituisce la somma di tutte le risposte a una determinata domanda nelle ripetizioni. Per ulteriori informazioni, consultare Funzioni di aggregazione. Nota: 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.	sum(${question})
today()	Restituisce la data odierna, memorizzata internamente come mezzogiorno locale. Questa funzione è utilizzata nelle domande date.	today()
true()	True	true()
uuid()	Restituisce una stringa UUID casuale.	uuid()
version()	Restituisce la versione del rilevamento definito nel foglio di lavoro delle impostazioni.	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 lavoro, l'espressione constraint viene inserita nel campo constraint e il testo informativo nella colonna constraint_message del foglio di lavoro 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 inattesi, se la propria formula include valori decimali tra -1 e 1, far precedere i valori da uno zero iniziale. In assenza dello zero iniziale, il decimale può essere erroneamente interpretato come il carattere di operazione . (o -.). 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.

Le espressioni regolari possono essere usate in modi diversi per le corrispondenze dei modelli, limitando le risposte valide a un determinato formato o verificando che contenga del 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 assicura che la risposta includa esattamente la parola road, senza nient'altro 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 in modo che corrisponda al formato di un indirizzo e-mail, pur accettando 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 loro funzioni in espressioni regolari, vedere il foglio di lavoro Riferimenti nei modelli Survey123 o consultare Riferimenti rapidi.

Calcoli

I calcoli vengono eseguiti nella colonna Calcolo per una domanda. I calcoli sono spesso associati al tipo di domanda calculate ed essere applicati a domande di tipo integer, decimal, text, e select_one. Il risultato del calcolo può essere utilizzato per complicare espressioni relevant o constraint facendo riferimento al nome del campo della domanda calculate.

Il tipo di domanda calculate viene nascosto non viene visualizzato in un modulo. Ciò significa che può essere utilizzato anche per avere valori che non necessitano di essere visualizzati nel modulo, ma che sono inclusi nel feature layer.

Ad esempio, è possibile creare una domanda di tipo calculate e denominarla calc, quindi inserire la seguente espressione nella relativa colonna Calcolo:

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

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

${calc} <= 100

I calcoli possono essere utilizzati con le risposte nei campi date. Questo calcolo consente di stimare il numero di anni tra una data immessa e la data odierna ed è utile, ad esempio, per calcolare l'età:

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. L'operatore substr restituisce solo parte di una stringa, definita dai numeri dopo di essa. Il primo carattere determina il punto iniziale della selezione, mentre il secondo valore ne determina la lunghezza (in assenza di un secondo valore, continua fino alla fine della stringa). In questo esempio, l'operatore substr rimuove tutto tranne la stringa dei caratteri da 10 a 15:

substr(${previous_question}, 10, 15)

Se il primo numero è negativo, substr inizia a contare dalla fine della stringa invece che dall'inizio. Questo esempio restituisce solo gli ultimi cinque caratteri della risposta:

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 si utilizza random(), valutare se aggiungere una costante per evitare di ottenere un risultato uguale a zero (0), 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 inattesi, utilizzare la funzione number(), che assicura che i valori della 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 consente di determinare un'area a partire dal suo raggio, utilizzando le funzioni di pigreco e di potenza:

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

Un metodo comune per la misurazione dell'altezza di un albero è misurare l'angolo ad altezza d'uomo verso un punto d'osservazione in cima all'albero e la distanza da tale punto d'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

La funzione format-date può essere utilizzata nel campo calculation per formattare i valori di data e ora. 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 Nota: Non è possibile usare il qualificatore %W in una funzione formato-data in cui la domanda data utilizza un calcolo. Questo qualificatore funziona con una domanda data che presenta un valore predefinito.
%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.

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 i 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 le 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

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

È possibile utilizzare la funzione pulldata() nella colonna di calcolo di una domanda per precaricare i dati di un file .csv. Ci sono due modi per includere un file .csv: posizionare manualmente il file nella cartella media del rilevamento o collegarsi a un file .csv ospitato in ArcGIS.

La funzione pulldata() richiede di specificare i seguenti quattro parametri in questo ordine:

1. Il nome del file .csv che contiene l'elenco di valori. Il nome non include il suffisso .csv nel nome del file.
2. Il nome della colonna nel file .csv che contiene il valore che si desidera restituire.
3. Il nome del campo chiave nel file .csv che verrà utilizzato per ricercare il valore.
4. 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 qualcuno denominato in una precedente domanda dalle informazioni di un file .csv:

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, è necessario inserire un valore più alto nella colonna bind::esri:fieldLength per entrambe le domande in cui si desidera inserire il contenuto del file .csv e per qualsiasi domanda usata come input per la funzione pulldata(). Se il file .csv include valori maggiori rispetto alla lunghezza massima consentita per uno di questi campi, non è possibile inviare risposte del rilevamento 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 si sta utilizzando Microsoft Excel per creare il file .csv, salvarlo come 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:

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

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

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. Il seguente è un esempio di oggetto JSON restituito dagli attributi smart. 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

È possibile 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 o getValue:

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

Un'interrogazione spaziale utilizza un'operazione getRecordAt o getValueAt:

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.

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

Parametro	Descrizione
JSON property	Obbligatorio per le operazioni getValue e getValueAt. Il valore da richiamare dalla risposta all'interrogazione. Esempi: "attributes.COUNTRY" "geometry"
location	Obbligatorio per le operazioni getRecordAt e getValueAt. La posizione del punto da interrogare con il feature layer. Deve essere una domanda geopoint. Esempio: ${location}
URL	Obbligatorio. L'URL del feature layer o della tabella feature da interrogare. Questo parametro accetta parametri di richiesta aggiuntivi. Esempio: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Facoltativo. 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". Esempio: "COUNTRY='Canada'"

Suggerimento:

La funzione pulldata("@layer") restituisce il primo record nella risposta all'interrogazione. Progetta e prova l'interrogazione per accertarti 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 disattivare la cache e garantire che venga effettuata una nuova richiesta ogni volta che viene eseguita la funzione, aggiungere un parametro time=now all'URL, ad esempio: concat(${layer_url}, "?t=", now()).

L'esempio seguente riguarda l'interrogazione di un feature layer poligono dei fusi orari mondiali e restituisce il fuso orario in cui è collocato 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, è possibile utilizzare un'operazione getValueAt nel calcolo pulldata("@layer") per richiamare direttamente l'attributo ZONE senza bisogno di una domanda separata per memorizzare la risposta all'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. È possibile, ad esempio, applicare un vincolo a una domanda geopoint per evitare che gli utenti inviino posizioni esterne a un'area di interesse.

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"). Un vincolo di ${country}='Canada', quindi, viene applicato alla domanda geopoint per accertarsi 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 di 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 o 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

È possibile consentire agli utenti di recuperare una posizione da un feature layer in base alla loro selezione 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 del rilevamento. Questo approccio è equivalente a una domanda di elenco di posizioni nel web designer Survey123.

Per creare un elenco di posizioni, aggiungere una domanda select_one con aspetti di ricerca e autocompletamento. L'aspetto di ricerca compila l'elenco con i valori di un feature layer. L'aspetto di autocompletamento presenta i valori in un elenco a discesa, utile quando viene restituito un elenco molto lungo dal feature layer.

Configurare l'espressione search() per recuperare un elenco di valori da un feature layer. Nella domanda geopoint, geoshape o geotrace, aggiungere un'espressione pulldata("@layer") per recuperare la geometria per la 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:

Per maggiori informazioni sull'aspetto di ricerca, consultare Ricerca.