Fórmulas

Puede usar fórmulas para crear formularios más inteligentes con ArcGIS Survey123.

Siempre se debe hacer referencia a las preguntas anteriores en las fórmulas con el formato ${field_name}.

Operadores

Survey123 admite los siguientes operadores:

Operador	Descripción	Ejemplo
.	La respuesta actual	.=1
+	Adición	${question_one} + 4
-	Resta	${question_one} - 4
*	Multiplicación	${question_one} * 4
div	División	${question_one} div 4
=	Igual	${price}=9.80
!=	No es igual	${price}!=9.80
<	Menor que	${price}<9.80
<=	Menor o igual que	${price}<=9.80
>	Mayor que	${price}>9.80
>=	Mayor o igual que	${price}>=9.80
and	Y	${price}>9.00 and ${price}<9.90
mod	Módulo (resto de la división)	${question_one} mod ${question_two}
or	O	${price}=9.80 or ${price}=9.70

Funciones

Survey123 admite las siguientes funciones:

Función	Descripción	Ejemplo
boolean(question, expression, or value)	Devuelve el valor True si el valor proporcionado no es nulo. Se recomienda utilizar en su lugar boolean-from-string(). Precaución: Esta función siempre devuelve un valor true en la aplicación web Survey123. Para conocer las alternativas, consulte Valores vacíos.	boolean(${question_one})
boolean-from-string()	Devuelve el valor True si la cadena de caracteres proporcionada es "true" o "1". De lo contrario, devuelve False.	boolean-from-string(${question_one})
coalesce(value1, value2)	Devuelve el primer valor no vacío. Esta función solo admite dos valores.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Devuelve la concatenación de los valores de la cadena de caracteres.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Devuelve el valor True si la cadena de caracteres indicada contiene la subcadena.	contains(${question_one}, 'red')
count(repeat)	Devuelve la cantidad de respuestas a una pregunta dada en repeticiones. Para obtener más información, consulte Funciones de consolidación. Nota: Cuando se utiliza en la aplicación de campo Survey123, esta función se puede colocar dentro o fuera de la repetición. Si la función se va a utilizar en la aplicación web Survey123, debe colocarse fuera de la repetición. En un cálculo dentro de la repetición se puede hacer referencia a un valor de recuento de fuera de la repetición.	count(${question})
count-selected(question)	Devuelve el número de respuestas seleccionadas para las preguntas select_one y select_multiple. Esta función también devuelve el número de archivos adjuntos para las preguntas de imagen, audio y archivo utilizando la apariencia multiline.	count-selected(${question_one})
date(question, expression, or value)	Convierte un número o cadena de caracteres en un objeto de fecha, sin mantener la hora.	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Convierte un número o cadena de caracteres en un objeto de fecha.	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	Convierte un objeto de fecha en un número de fecha-hora decimal.	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	Convierte un objeto de hora en un número que representa una fracción de un día en la zona horaria del dispositivo.	decimal-time(${time_question})
ends-with(string, substring)	Devuelve el valor True si la cadena de caracteres indicada termina por la subcadena.	ends-with(${question_one}, 'hand.')
false()	False	false()
format-date()	Ajusta un valor de fecha u hora existente a un formato definido.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Si la condición se evalúa como true, devuelve a; de lo contrario, devuelve b.	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
indexed-repeat(question, repeat, index number)	Devuelve el valor de una pregunta concreta de un registro de repetición. Para obtener más información, consulte Repeticiones.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Convierte a entero. La conversión varía según el tipo de datos. Nota: Si esta función está vacía, devolverá NaN y la pregunta permanecerá vacía.	int(${question_one})
join(separator, question)	Concatena todas las respuestas de una pregunta determinada en una repetición, separadas por el separador indicado. Nota: Cuando se utiliza en la aplicación de campo Survey123, esta función se puede colocar dentro o fuera de la repetición. Si la función se va a utilizar en la aplicación web Survey123, debe colocarse fuera de la repetición. En un cálculo dentro de la repetición se puede hacer referencia a un valor de unión de fuera de la repetición.	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	Se utiliza en las preguntas select_one. Devuelve la etiqueta asociada al nombre de la opción de la pregunta indicada. Recuerde que la pregunta debe estar definida dentro de comillas.	jr:choice-name(${select_one}, '${select_one}')
	Se utiliza en las preguntas select_multiple. Devuelve la etiqueta asociada al nombre de la opción de la pregunta indicada. La función selected-at() se debe utilizar para extraer la etiqueta de las respuestas individuales. Recuerde que la pregunta debe estar definida dentro de comillas.	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	Devuelve el valor máximo de un rango dado o para una pregunta simple en repeticiones.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Devuelve el valor mínimo de un rango dado o para una pregunta simple en repeticiones.	min(${question_one}, ${question_two})
not(expression)	Devuelve un valor false si la expresión devuelve true, y un valor true si la expresión devuelve false.	not(selected(., 'yes'))
now()	Devuelve una marca de hora para este instante. Esta función se utiliza en preguntas de hora y dateTime. Funciona igual que today() en las preguntas de fecha.	now()
number(question, expression, or value)	Convierte a número. La conversión varía según el tipo de datos. Nota: Si esta función está vacía, devolverá NaN y la pregunta permanecerá vacía.	number(${question_one})
once()	Si una pregunta ya tiene un valor, devuelve el valor existente. Esta función resulta útil cuando se utiliza random() o uuid() en una pregunta repetida para asegurarse de que el valor no va a cambiar cuando navegue por los registros repetidos del formulario.	once(uuid())
position(..)	Devuelve el índice del registro actual en una repetición. Para obtener más información, consulte Repeticiones.	position(..)
pulldata()	Devuelve un valor de un archivo CSV externo. Para obtener más información, consulte Recuperar un valor a partir de un CSV.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Devuelve un valor de los metadatos EXIF de una imagen. Para obtener más información, consulte Extraer metadatos de la imagen.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Devuelve un valor de una pregunta de geopunto. Para obtener más información, consulte Extraer valores de geopuntos.	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	Ejecuta una función de JavaScript en el formulario y devuelve el resultado. Para obtener más información, consulte Funciones JavaScript en formularios de encuesta.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Devuelve un valor de un objeto JSON. Para obtener más información, consulte Recuperar un valor a partir de un JSON.	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	Consulta una capa de entidades, tabla de entidades o un servicio de mapas habilitado para consulta de ArcGIS y devuelve el resultado. Para obtener más información, consulte Consultar una capa de entidades.	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	Devuelve información sobre el dispositivo o el usuario que ha iniciado sesión. Para obtener más información, consulte Propiedades del dispositivo y del usuario.	pulldata("@property", 'username')
random()	Devuelve un valor aleatorio entre 0 (incluido) y 1 (excluido).	random()
regex()	Aplica una expresión regular a la entrada de la pregunta. Devuelve el valor True si el patrón coincide. Para obtener más información, consulte Expresiones regulares.	regex(., '^\d{5}$')
selected(question, value)	Comprueba si se ha seleccionado una respuesta. Esta función se utiliza en las preguntas select_one y select_multiple.	selected(${question_one}, 'a')
selected-at(question, number)	Se utiliza en las preguntas select_multiple. Devuelve el nombre de la opción seleccionada para el número indicado, empezando a contar desde cero; por ejemplo, "2" devolverá la tercera opción seleccionada.	selected-at(${question_one}, 2)
starts-with(string, substring)	Devuelve el valor True si la cadena de caracteres indicada comienza por la subcadena.	starts-with(${question_one}, 'The')
string(question, expression, or value)	Convierte a cadena de caracteres. La conversión varía según el tipo de datos.	string(${question_one})
string-length(question, expression, or value)	Devuelve la longitud de una cadena no vacía.	string-length(${question_one})
substr(question, start, end)	Devuelve la subcadena empezando en el inicio especificado y se extiende al carácter que se encuentra en índice final -1, donde el inicio y el final empiezan en 0.	substr(${question_one}, 1, 2)
sum(repeat)	Devuelve la suma de todas las respuestas a una pregunta dada en repeticiones. Para obtener más información, consulte Funciones de consolidación. Nota: Cuando se utiliza en la aplicación de campo Survey123, esta función se puede colocar dentro o fuera de la repetición. Si la función se va a utilizar en la aplicación web Survey123, debe colocarse fuera de la repetición. En un cálculo dentro de la repetición se puede hacer referencia a un valor de suma de fuera de la repetición.	sum(${question})
today()	Devuelve la fecha de hoy, almacenada internamente como la hora del medio día local. Esta función se utiliza en preguntas de fecha.	today()
true()	Verdadero	true()
uuid()	Devuelve una cadena de caracteres de UUID aleatoria.	uuid()
version()	Devuelve la versión de la encuesta definida en la hoja de cálculo de configuración.	version()

Survey123 admite las siguientes funciones matemáticas:

Función	Descripción	Ejemplo
acos(value)	Devuelve el arcocoseno del valor.	acos(${question_one})
asin(value)	Devuelve el arcoseno del valor.	asin(${question_one})
atan(value)	Devuelve el arcotangente del valor.	atan(${question_one})
atan2(value1, value2)	Devuelve el arcotangente del cociente de los valores.	atan2(${question_one}, ${question_two})
cos(value)	Devuelve el coseno del valor como un ángulo en radianes.	cos(${question_one})
sin(value)	Devuelve el seno del valor como un ángulo en radianes.	sin(${question_one})
tan(value)	Devuelve la tangente del valor como un ángulo en radianes.	tan(${question_one})
exp(value)	Devuelve el exponente natural del valor.	exp(${question_one})
exp10(value)	Devuelve 10 a la potencia del valor.	exp10(${question_one})
log(value)	Devuelve el logaritmo natural del valor.	log(${question_one})
log10(value)	Devuelve el logaritmo en base 10 del valor.	log10(${question_one})
pi()	Devuelve pi.	pi()
pow(value, power)	Devuelve el valor a la potencia especificada.	pow(${question_one}, 3)
round(value, places)	Devuelve el valor redondeado.	round(${question_one}, 5)
sqrt(value)	Devuelve la raíz cuadrada del valor.	sqrt(${question_one})

Restricciones

Al agregar una restricción a una pregunta de una encuesta, se restringen las entradas aceptadas para una respuesta. Esto puede incluir un rango de números, combinaciones de letras y números o la coincidencia general de patrones. En su hoja de cálculo, la expresión de restricción se introduce en el campo de restricción y el texto informativo se introduce en la columna constraint_message de la hoja de cálculo survey. En la expresión de la restricción, la entrada de la pregunta siempre se representa mediante un punto.

Por ejemplo, se puede usar la siguiente fórmula para restringir la entrada de un campo de tipo entero únicamente a los números positivos:

.>= 0

Esta fórmula, cuando se aplica a un campo date, impide que el usuario introduzca un valor anterior a la fecha actual:

.>= today()

También puede utilizar cálculos en las restricciones. Esta fórmula realiza un cálculo para permitir únicamente al usuario seleccionar fechas entre la fecha actual y la de dentro de 14 días:

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

Sugerencia:

Para evitar errores inesperados, si la fórmula incluye valores decimales entre -1 y 1, recuerde incluir un cero inicial en los valores. Sin el cero inicial, el decimal podría confundirse con el carácter de operación . (o -.). Por ejemplo, la siguiente expresión generará un error:

.> .25 and .< 24.25

La siguiente expresión se ejecutará del modo esperado:

.> 0.25 and .< 24.25

Expresiones regulares

Una expresión regular es una secuencia de caracteres que se utiliza para hacer coincidir patrones en cadenas de caracteres. En Survey123, si el patrón coincide, la expresión devolverá el valor True; de lo contrario, si el patrón no coincide, la expresión devolverá el valor False.

Las expresiones regulares se pueden usar de una gran variedad de formas para aplicar la coincidencia de patrones con el fin de restringir las respuestas válidas a un formato indicado o para asegurarse de que contenga un contenido específico. Este ejemplo exige que la respuesta a la pregunta contenga la palabra road:

regex(., 'road')

El punto utilizado al principio de estos ejemplos aplica la expresión al campo actual. Al agregar el nombre de otro campo en su lugar, la expresión regular se aplica a ese campo, lo que resulta ideal para las expresiones relevantes. La coma actúa como separador entre esta definición de campo y la expresión.

Esta expresión regular garantiza que la respuesta coincida exactamente con la palabra road, sin nada más antes ni después:

regex(., '^road$')

Las expresiones regulares son ideales para confinar la entrada de una pregunta a un formato estándar. Este ejemplo acepta únicamente la introducción de un código postal de cinco dígitos de los Estados Unidos:

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

Este ejemplo contrasta la respuesta con el formato actual de las matrículas de Indonesia, como se muestra en la siguiente foto:

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

Los formatos estandarizados de manera más variable pueden requerir expresiones regulares complejas. Esta expresión regular utilizada en la aplicación web Survey123 limita la entrada de un campo de cadena de caracteres para que coincida con el formato de una dirección de correo electrónico:

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

Esta modificación de la expresión anterior restringe la entrada para que coincida con el formato de una dirección de correo electrónico, y acepta caracteres no ingleses:

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

Este ejemplo, aunque también utiliza una expresión regular de la aplicación web Survey123, limita un campo para solo aceptar respuestas que coincidan con el formato de una dirección 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.:-]*)?)?)?')

Para obtener más información sobre las expresiones regulares, consulte la documentación de Mozilla Developer Network. Para obtener una lista de caracteres y sus funciones en expresiones regulares, consulte la hoja de cálculo Referencia en las plantillas de Survey123 o consulte la Referencia rápida.

Cálculos

Para una pregunta, los cálculos se efectúan en la columna calculation. A menudo, los cálculos se asocian con el tipo de pregunta de cálculo, pero también pueden aplicarse a los tipos de preguntas integer, decimal, text y select_one. El resultado del cálculo se puede usar para rellenar las expresiones relevantes o de restricciones haciendo referencia al nombre de campo de la pregunta calculate.

El tipo de pregunta calculate está oculto y no aparece en el formulario. Significa que también se puede usar para albergar valores que no es necesario mostrar en el formulario, pero que se incluyen en la capa de entidades.

Por ejemplo, puede crear una pregunta de tipo calculate, llamarla "calc" e insertar la siguiente expresión en su columna calculation:

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

Use el resultado para definir la relevancia de la siguiente pregunta:

${calc} <= 100

Se pueden usar cálculos con las respuestas en los campos date. Este cálculo estima el número de años entre la fecha introducida y la actual, lo que permite, por ejemplo, calcular la edad de alguien:

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

En ocasiones solo se necesita parte de un valor o una versión truncada de una respuesta completa. El operador substr solo devuelve parte de una cadena de caracteres, definida por los números que aparecen tras él. El primer carácter determina el punto inicial de la selección, mientras que el segundo valor determina la longitud (si no hay un segundo valor, sigue hasta el final de la cadena de caracteres). En este ejemplo, el operador substr lo elimina todo menos la cadena de caracteres comprendida entre los caracteres 10 y 15:

substr(${previous_question}, 10, 15)

Si el primer número es negativo, substr empieza a contar desde el final de la cadena de caracteres en lugar de hacerlo desde el principio. Este ejemplo solo devuelve los cinco últimos caracteres de la respuesta:

substr(${previous_question}, -5)

Puede utilizar el parámetro calculationMode para controlar cuándo se calculan los cálculos en el formulario. Para obtener más información, consulte Modo de cálculo.

También puede utilizar la columna calculation para funciones de agregación en las repeticiones. Para obtener más información, consulte Repeticiones.

Respete las siguientes prácticas recomendadas al usar cálculos:

• Cuando use random(), considere la posibilidad de agregar una constante para evitar un resultado cero (0), por ejemplo, random()+0.5. Un valor 0 puede generar una respuesta en blanco.
• Como en el caso de las restricciones, debe asegurarse de que todos los valores decimales entre -1 y 1 de la fórmula tienen un 0, ya que comenzar con un punto decimal genera errores.
• El tipo de datos de un resultado de cálculo depende del tipo de datos de cada elemento del cálculo. Si se realiza un cálculo con dos enteros, el resultado será un entero. Si un cálculo contiene un tipo de datos de cadena de caracteres, puede ocurrir que un operador + concatene valores en lugar de sumarlos. Para evitar resultados inesperados, use la función number() para garantizar que los valores de cadenas de caracteres de un cálculo se tratan como números. Por ejemplo, el cálculo para agregar question1 (de tipo integer) a question2 (de tipo text) sería ${question1} + number(${question2}).

Sugerencia:

El tipo de vinculación predeterminado de XLSForm para una pregunta calculation es string. Para sobreescribir este valor predeterminado, introduzca el tipo requerido (por ejemplo, int o decimal) en la columna bind::type de su pregunta. Como alternativa, puede utilizar el tipo de pregunta que desee (por ejemplo, integer o decimal) y establecer la apariencia de esta pregunta como hidden.

Precaución:

El uso de funciones u operadores matemáticos con preguntas de tipo text devuelve NaN como resultado en la aplicación web Survey123. Para concatenar preguntas de tipo text, utilice la función concat() en lugar del operador +.

Funciones matemáticas complejas

La columna calculation también puede gestionar operaciones matemáticas más complejas. Este ejemplo determina el área de un trazado a partir de su radio usando las funciones de potencia y pi:

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

Un método común para medir la altura de un árbol es medir el ángulo desde el nivel del ojo en un punto de observación hasta la parte superior del árbol, y la distancia desde el mismo punto de observación hasta la base del árbol. Si el ángulo en la parte superior del árbol se mide en grados, se utilizará el siguiente cálculo para convertirlo a radianes:

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

Con la medición del ángulo ahora en radianes, la altura del árbol (con redondeo a dos posiciones decimales) se puede determinar mediante el siguiente cálculo:

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

Aplicación de formato de fecha

Puede usar la función format-date en el campo calculation para aplicar formato a los valores de fecha y hora. Esto puede resultar útil si desea mostrar partes de fechas a los usuarios o mantenerlas como cadenas de caracteres.

En este ejemplo, el valor incluido en una pregunta de hora o dateTime anterior se devuelve con formato de 24 horas:

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

Los calificadores que puede utilizar en la función format-date son los siguientes:

Calificador	Descripción
%3	Marcas de milisegundo relleno con 0 (000-999)
%a	Texto abreviado de día, con tres letras
%b	Nombre de mes abreviado
%d	Día del mes relleno con 0
%e	Día del mes
%h	Hora (formato de 24 horas)
%H	Hora rellena con 0 (formato de 24 horas)
%m	Mes relleno con 0
%M	Minuto relleno con 0
%n	Mes numérico
%S	Segundo relleno con 0
%W	Número de semana Nota: El calificador %W no se puede usar en una función format-date en la cual la pregunta de fecha utilice un cálculo. Este calificador funciona con las preguntas de fecha que tengan un valor predeterminado.
%y	Año con 2 dígitos
%Y	Año con 4 dígitos

Nota:

Las preguntas dateTime no admiten resoluciones de tiempo inferiores a un minuto. Para capturar una resolución de tiempo con fechas inferiores a un minuto, plantéese utilizar las preguntas start y end.

Valores vacíos

Cuando use restricciones y cálculos que hacen referencia a otras preguntas, piense en lo que sucederá cuando esa pregunta esté vacía (es decir, cuando no tenga respuesta). Los valores vacíos se representan de la forma siguiente:

• NaN (no es un número) para las preguntas de tipo integer y decimal. Es un valor especial que representa la ausencia de un valor válido.
• '' (una cadena de caracteres vacía) para las preguntas de tipo text. El tipo de datos predeterminado para las preguntas select_one, select_multiple, clasificación y oculto también es texto. Cuando los tipos de preguntas select_one, select_multiple y oculto están vacíos o cuando el usuario no ha modificado una pregunta de clasificación, contienen una cadena de caracteres vacía.

Dependiendo de si el valor es un número o texto, los comportamientos de los cálculos difieren.

En las preguntas de tipo integer o decimal, el comportamiento será el siguiente:

• Cualquier expresión matemática con un valor NaN genera un error y la pregunta queda vacía.
• Las funciones min() y max() completan y hacen caso omiso de cualquier valor NaN (es decir, que no sea un número).
• La comparación del valor NaN con cualquier otro valor solo arroja un valor verdadero en un cálculo de una comparación de valores is not equal. Las demás expresiones arrojan un resultado falso.

En las preguntas de texto, el comportamiento será el siguiente:

• La concatenación de preguntas de tipo text se completa si hay valores vacíos. Por ejemplo, concat("Hello" + ${firstName}, ", how are you?") genera "Hello , how are you?" cuando firstName esté vacío en la pregunta.
• Las funciones min() y max() completan y hacen caso omiso de cualquier cadena de caracteres vacía.
• Una respuesta de texto vacía es igual a otra respuesta de texto vacía y es siempre inferior a un texto no vacío.

Puede determinar si una pregunta está vacía usando la función string-length. La función string-length se puede usar con todos los tipos de preguntas. Por ejemplo, string-length(${Question1}) devuelve 0 si Question1 está vacío.

También puede determinar si una pregunta select_one o select_multiple está vacía usando la función count-selected. Por ejemplo, count-selected(${question2}) devuelve 0 si no se hizo ninguna selección para question2.

Preguntas select_multiple y de clasificación

Las respuestas a los tipos de preguntas select_multiple y de clasificación se almacenan de forma diferente a todos los demás tipos de preguntas. Cada respuesta marcada de una pregunta select_multiple se introduce en el orden en que se seleccionó, separada por comas. Por ejemplo, al seleccionar las respuestas "A" y "B" en ese orden, las respuestas aparecen como "A,B". Una pregunta de clasificación también almacena sus respuestas en una lista separada por comas por orden de clasificación, de la más alta a la más baja, en el momento del envío.

Algunas características de XLSForm no funcionan con las preguntas select_multiple y de clasificación. Por ejemplo, si introduce la respuesta 'A' en la columna relevant de una pregunta que hace referencia a la pregunta select_multiple y la respuesta de la encuesta es 'A,B', la respuesta no se considera relevante. En este caso, la solución es usar la función selected(), que determina si alguno de los valores aparece en la lista.

La siguiente expresión, cuando se usa en la columna relevant de una pregunta, muestra la pregunta si el usuario ha seleccionado 'A' como una de las respuestas en la pregunta select_multiple a la que se hace referencia. Las respuestas adicionales a la pregunta select_multiple no cambian este comportamiento.

selected(${previous_question}, 'A')

Recuperar un valor a partir de un archivo .csv

Puede usarse la función pulldata() de la columna calculation de una pregunta para precargar datos a partir de un archivo .csv. Hay dos formas de incluir un archivo .csv: colocar manualmente el archivo en la carpeta media de la encuesta o vincular a un archivo .csv alojado en ArcGIS.

La función pulldata() requiere la especificación de los cuatro parámetros siguientes en orden:

1. El nombre del archivo .csv que contiene la lista de valores. El nombre no incluye el sufijo de nombre de nombre de archivo .csv.
2. El nombre de la columna del archivo .csv que contiene el valor que se desea devolver.
3. El nombre del campo de clave del archivo .csv que se usará para buscar el valor.
4. El valor de clave que se debe buscar en el campo de clave.

Estos valores se pueden definir directamente o a través de variables definidas en cualquier otro punto de la encuesta. En el siguiente ejemplo, el cálculo devuelve la dirección de correo electrónico de alguien mencionado en una pregunta anterior de un archivo .csv llamado info:

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

La misma función pulldata() funciona también en la columna constraints e impide que el usuario envíe respuestas que no están en el archivo .csv. En la columna constraints, esta misma fórmula impide que el formulario acepte valores que no estén en la columna name del archivo .csv.

La función pulldata() tiene algunas limitaciones. El nombre del campo de clave tiene la misma limitación que la columna name de la hoja de cálculo choices, lo que significa que esos valores no pueden tener espacios ni caracteres que no sean ASCII. Además, como son archivos .csv, usar una coma en cualquiera de estos campos hace que la función pulldata() genere resultados incorrectos.

Si los valores de su archivo .csv tienen más de 255 caracteres, debe introducir un valor mayor en la columna bind::esri:fieldLength tanto para la pregunta que está completando con el contenido del .csv como para cualquier pregunta que se utilice como entrada de la función pulldata(). Si su archivo .csv contiene valores mayores que la longitud máxima de uno de estos campos, la respuesta a la encuesta no se puede enviar y muestra un error de Código 1000.

Nota:

No puede utilizar la función pulldata() para rellenar los valores de las preguntas select_multiple.

Al utilizar la función pulldata(), los nombres de las columnas del .csv no pueden estar en blanco ni contener espacios, guiones ni otros caracteres especiales.

Se recomienda codificar el archivo .csv mediante codificación de caracteres UTF-8. Si utiliza Microsoft Excel para crear el archivo .csv, guárdelo como CSV UTF-8.

Recuperar un valor a partir de un JSON

Puede usar la función pulldata("@json") para extraer propiedades individuales de un objeto JSON. Esta función se utiliza a menudo para complementar otras funciones, como pulldata("@javascript") y pulldata("@layer"). La función tiene la siguiente sintaxis:

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

Los parámetros de pulldata("@json") son los siguientes:

• question name: el nombre de la pregunta que contiene el objeto JSON, por ejemplo: ${json_response}.
• JSON property: la propiedad que desea recuperar del JSON. Utilice puntos para especificar la ubicación de la propiedad en la estructura JSON. Por ejemplo, para recuperar la propiedad City del objeto address, utilice "address.City".

En el siguiente ejemplo, el resultado de una operación de geocodificación inversa se devuelve como JSON en una pregunta de texto denominada json_response:

Se devuelve una respuesta del localizador similar a la siguiente:

{
    "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 función pulldata("@json") se utiliza para recuperar la propiedad City del objeto address:

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

La latitud y longitud se recuperan del objeto location:

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

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

Nota:

Se utiliza un punto para acceder a las propiedades individuales de un objeto principal. Cuando un punto también forma parte de una propiedad, debe estar entre corchetes [ ]. Por ejemplo, para recuperar una propiedad llamada City.Population del objeto address, la expresión sería pulldata("@json", ${json_response}, "address.[City.Population]").

Puede acceder a un objeto de una matriz de objetos especificando su posición en la matriz entre corchetes. El índice de una matriz JSON comienza en cero. A continuación se muestra un ejemplo de objeto JSON devuelto por atributos inteligentes. Contiene una matriz 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
        }
    ]
}

En el ejemplo anterior, la siguiente expresión devuelve la puntuación de 0,67421875 del primer objeto de la matriz classes:

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

Puede utilizar la propiedad length para devolver el número de objetos de una matriz. En el ejemplo anterior, la siguiente expresión devuelve una longitud de 3:

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

Consultar una capa de entidades

Puede usar la función pulldata("@layer") para consultar una capa de entidades, una tabla de entidades o un servicio de mapas habilitado para consultas. Puede realizar una consulta de atributos o una consulta espacial. Una consulta de atributos utiliza una operación getRecord o getValue:

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

Una consulta espacial utiliza una operación getRecordAt o getValueAt:

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

Nota:

La ubicación especificada en una consulta espacial debe ser una pregunta de geopunto.

Las operaciones getRecord y getRecordAt devuelven un objeto de entidad JSON que contiene una sola entidad y todos sus atributos. Las operaciones getValue y getValueAt devuelven un valor único del objeto de entidad, en lugar de toda la respuesta a la consulta.

Los parámetros de pulldata("@layer") son los siguientes:

Parámetro	Descripción
JSON property	Se requiere para las operaciones getValue y getValueAt. El valor que desea recuperar de la respuesta a la consulta. Ejemplos: "attributes.COUNTRY" "geometry"
location	Se requiere para las operaciones getRecordAt y getValueAt. La ubicación de punto que desea consultar con la capa de entidades. Debe ser una pregunta de geopunto. Ejemplo: ${location}
URL	Requerido. La URL de la tabla o capa de entidades que desea consultar. Este parámetro acepta parámetros de solicitud adicionales. Ejemplo: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Opcional. Una expresión WHERE que filtra la tabla o capa de entidades. Cuando no se proporciona la cláusula WHERE, se utiliza un valor predeterminado de "1=1". Ejemplo: "COUNTRY='Canada'"

Sugerencia:

La función pulldata("@layer") devuelve el primer registro de la respuesta a la consulta. Diseñe y pruebe la consulta para garantizar que obtiene los resultados deseados. Puede refinar su consulta mediante una cláusula WHERE y los parámetros de solicitud adicionales que se describen a continuación.

La función pulldata("@layer") almacena en caché las respuestas de las preguntas por motivos de eficacia. Para anular la caché y asegurarse de que se realiza una nueva solicitud cada vez que se ejecuta la función, agregue un parámetro tiempo=ahora a la URL, por ejemplo, concat(${layer_url}, "?t=", now()).

El siguiente ejemplo consulta una capa de entidades poligonales de zonas horarias mundiales y devuelve la zona horaria en la que se encuentra el geopunto:

La operación getRecordAt se utiliza para recuperar la zona horaria que interseca el geopunto con la siguiente sintaxis:

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

Luego, el atributo ZONE se extrae de la respuesta a la consulta con la función pulldata("@json"). Como alternativa, puede utilizar una operación getValueAt en el cálculo pulldata("@layer") para recuperar directamente el atributo ZONE, sin necesidad de una pregunta separada para almacenar la respuesta a la consulta. Vea el siguiente ejemplo:

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

Puede utilizar pulldata("@layer") en restricciones. Por ejemplo, puede aplicar una restricción a una pregunta geopoint para evitar que los usuarios envíen ubicaciones fuera de un área de interés.

La operación getRecordAt devuelve el objeto de entidad JSON para el país en el que se encuentra el geopunto utilizando la siguiente sintaxis:

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

El nombre del país se extrae en una pregunta de texto con pulldata("@json"). A continuación, se aplica una restricción de ${country}='Canada' a la pregunta geopoint para garantizar que la ubicación quede dentro de la región de Canadá.

Parámetros de solicitud

Puede refinar una consulta pulldata("@layer") con parámetros de solicitud adicionales, tales como distance, orderByFields y resultOffset. Para obtener más información sobre los parámetros de solicitud, consulte Consultar (servicio de entidades/capa). La función pulldata("@layer") solo admite solicitudes que devuelven un objeto de entidad.

Para incluir estos parámetros en una consulta, incorpórelos a la URL después de un signo de interrogación. Los parámetros adicionales se separan con el símbolo et. En el siguiente ejemplo, los parámetros orderByFields y resultOffset se incorporan a la URL de la capa de entidades para devolver el nombre del décimo condado más poblado de 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'")

Se puede utilizar una consulta agregada para devolver estadísticas en una capa de entidades con el parámetro outStatistics. Las estadísticas que pueden calcularse con este parámetro incluyen recuento, suma, mínimo, máximo, promedio, desviación estándar o varianza.

En el ejemplo siguiente se devuelve el recuento de condados del estado seleccionado:

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

En el ejemplo siguiente se devuelve la suma del campo POPULATION de todos los condados del estado seleccionado:

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 función pulldata("@layer") admite todos los parámetros de solicitud enumerados en Consulta (Servicio de entidades/Capa), excepto los siguientes:

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

Recuperar una ubicación de una lista

Puede permitir que los usuarios recuperen una ubicación de una capa de entidades en función de lo que se seleccione en una lista de opciones de una pregunta select_one. La selección se envía como texto y su geometría correspondiente se envía como ubicación para la respuesta de la encuesta. Este método equivale a una pregunta de lista de ubicaciones en el diseñador web de Survey123.

Para crear una lista de ubicaciones, agregue una pregunta select_one con apariencia de búsqueda y autocompletar. La apariencia de búsqueda rellena la lista con valores de una capa de entidades. La apariencia de autocompletar presenta los valores en una lista desplegable, que resulta útil cuando se devuelve una lista muy larga desde una capa de entidades.

Configure la expresión de search() para recuperar una lista de valores de una capa de entidades. En la pregunta de geopunto, geoforma o el geotrazado, agregue una expresión de pulldata("@layer") para recuperar la geometría correspondiente a la entidad seleccionada de la lista.

En el ejemplo siguiente, los encuestados seleccionan un contador de agua de una pregunta select_one denominada meter_id. La geometría del contador de agua se recupera de la capa de entidades de contadores de agua y se guarda en la pregunta de geopunto:

Para obtener más información sobre la apariencia de la búsqueda, consulte Buscar.