Fórmulas

Você pode utilizar fórmulas para criar formulários mais inteligentes com ArcGIS Survey123.

As perguntas anteriores devem sempre ser referidas nas fórmulas com o formato ${field_name}.

Operadores

Os seguintes operadores são suportados no Survey123.

Operador	Descrição	Exemplo
.	A resposta atual	.=1
+	Adição	${question_one} + 4
-	Subtração	${question_one} - 4
*	Multiplicação	${question_one} * 4
div	Divisão	${question_one} div 4
=	Igual	${price}=9.80
!=	Diferente de	${price}!=9.80
<	Menor que	${price}<9.80
<=	Menor ou igual a	${price}<=9.80
>	Maior que	${price}>9.80
>=	Maior ou igual a	${price}>=9.80
and	E	${price}>9.00 and ${price}<9.90
mod	Módulos (divisão remanescente)	${question_one} mod ${question_two}
or	Ou	${price}=9.80 or ${price}=9.70

Funções

As funções seguintes são suportadas no Survey123:

Função	Descrição	Exemplo
boolean(question, expression, or value)	Retorna verdadeiro se o valor fornecido não for nulo. É recomendado a você utilizar boolean-from-string () ao vez disto. Aviso: Essa função sempre retorna verdadeiro no aplicativo da web Survey123. Para alternativas, consulte Valores vazios.	boolean(${question_one})
boolean-from-string()	Retorna verdadeiro se a string fornecida for 'true' ou '1'. Caso contrário, retorna falso.	boolean-from-string(${question_one})
coalesce(value1, value2)	Retorna o primeiro valor não vazio. Esta função suporta apenas dois valores.	coalesce(${question_one}, ${question_two})
concat(value1, value2, …)	Retorna a concatenação dos valores de string.	concat(${question_one}, ' and ', ${question_two})
contains(string, substring)	Retorna verdadeiro se a string fornecida tiver uma substring.	contains(${question_one}, 'red')
count(repeat)	Retorna a quantidade de respostas para uma pergunta fornecida através de repeticões. Para mais informações, consulte Funções de Agregar. Anotação: Quando utilizada na aplicação de campo Survey123, esta função pode ser colocada dentro ou fora da repetição. Se a função for usada no aplicativo da web Survey123, ela deve ser colocada fora da repetição. Um valor de contagem de fora da repetição pode ser referenciado em um cálculo dentro da repetição.	count(${question})
count-selected(question)	Retorna o número de respostas selecionadas para select_one e perguntas select_multiple. Esta função retorna o número de arquivos anexados para as perguntas de imagem, áudio e arquivo usando a aparência multilinha.	count-selected(${question_one})
date(question, expression, or value)	Converte um número ou string para um objeto de data, sem preservar tempo.	date('2017-05-28T04:39:02+10:00')
date-time(question, expression, or string)	Converte um número ou string para um objeto de data.	date-time('2017-05-28T04:39:02+10:00')
decimal-date-time(question, expression, or string)	Converte um objeto de data em um número de data-hora decimal.	decimal-date-time(${date_question})
decimal-time(question, expression, or string)	Converte um objeto de tempo em um número que representa um dia fracionário no fuso horário do dispositivo.	decimal-time(${time_question})
ends-with(string, substring)	Retorna verdadeiro se a string fornecida finalizar com uma substring.	ends-with(${question_one}, 'hand.')
false()	Falso	false()
format-date()	Ajusta um valor de data ou hora existente a um formato definido.	format-date(${previous_time}, '%H:%M')
if(condition, a, b)	Se a condição for avaliada como verdadeira, retorna a; caso contrário, retorna b.	if(selected(${question_one}, 'yes') and selected(${question_two}, 'yes'), 'yes', 'no')
indexed-repeat(question, repeat, index number)	Retorna o valor de uma pergunta específica em um registro de repetição. Para mais informações, consulte Repetições.	indexed-repeat(${room_no}, ${floor}, 3)
int(question, expression, or value)	Converte para inteiro. A conversão varia dependendo do tipo de dados. Anotação: Se esta função estiver vazia, ela retornará NaN e a pergunta permanecerá vazia.	int(${question_one})
join(separator, question)	Concatena todas as respostas para uma determinada pergunta em uma repetição, separadas pelo separador fornecido. Anotação: Quando utilizada na aplicação de campo Survey123, esta função pode ser colocada dentro ou fora da repetição. Se a função for usada no aplicativo da web Survey123, ela deve ser colocada fora da repetição. Um valor de ligação de fora da repetição pode ser referenciado em um cálculo dentro da repetição.	join(',', ${question_in_repeat})
jr:choice-name(choice_name, 'question')	Utilizado para peruntas select_one. Retorna o rótulo associado ao nome da opção na pergunta fornecida. Esteja ciente que a pergunta deve ser definida dentro de aspas.	jr:choice-name(${select_one}, '${select_one}')
	Utilizado para perguntas select_multiple. Retorna o rótulo associado ao nome da opção na pergunta fornecida. A função selected-at() deve ser usada para extrair o rótulo de respostas individuais. Esteja ciente que a pergunta deve ser definida dentro de aspas.	jr:choice-name(selected-at(${select_multiple}, 3), '${select_multiple}')
max(value1, value2, ...)	Retorna o valor máximo em um intervalo fornecido ou para uma única pergunta através das repetições.	max(${question_one}, ${question_two})
min(value1, value2, ...)	Retorna o valor mínimo em um intervalo fornecido ou para uma única pergunta através das repetições.	min(${question_one}, ${question_two})
not(expression)	Retorna um valor falso se a expressão retornar verdadeiro e um valor verdadeiro se a expressão retornar falso.	not(selected(., 'yes'))
now()	Retorna um espaço de tempo para este momento. Esta função é usada em perguntas de tempo e data/hora. Ele se comporta da mesma forma que today() em perguntsas de data.	now()
number(question, expression, or value)	Converte para número. A conversão varia dependendo do tipo de dados. Anotação: Se esta função estiver vazia, ela retornará NaN e a pergunta permanecerá vazia.	number(${question_one})
once()	Se uma pergunta já tiver um valor, retorna o valor existente. Esta função é útil ao usar random() ou uuid() em uma pergunta repetida para garantir que o valor não mude quando você navegar pelos registros repetidos no formulário.	once(uuid())
position(..)	Retorna o índice do registro atual em uma repetição. Para mais informações, consulte Repetições.	position(..)
pulldata()	Retorna um valor de um arquivo CSV externo. Para obter mais informações, consulte Recuperar um valor de CSV.	pulldata('users', 'email', 'name', ${respondent_name})
pulldata("@exif")	Retorna um valor dos metadados EXIF ​​em uma imagem. Para obter mais informações, consulte Extrair metadados de imagem.	pulldata("@exif", ${photo}, "GpsLatitude")
pulldata("@geopoint")	Retorna um valor de uma pergunta de ponto geográfico. Para obter mais informações, consulte Extrair valores de pontos geográficos.	pulldata("@geopoint", ${location}, "horizontalAccuracy")
pulldata("@javascript")	Executa uma função JavaScript no formulário e retorna o resultado. Para obter mais informações, consulte Funções JavaScript em formulários de pesquisa.	pulldata("@javascript", "functions.js", "uniqueID", ${buildings})
pulldata("@json")	Retorna um valor de um objeto JSON. Para mais informações, consulte Recuperar um valor de JSON.	pulldata("@json", ${json_output}, "attributes.ZIP_CODE")
pulldata("@layer")	Consulta uma camada de feição do ArcGIS, tabela de feição ou serviço de mapa habilitado para consulta e retorna o resultado. Para mais informações, consulte Consultar uma camada de feição.	pulldata("@layer", "getRecordAt", "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/World_Time_Zones/FeatureServer/0", ${location})
pulldata("@property")	Retorna informações sobre o dispositivo ou usuário conectado. Para obter mais informações, consulte Propriedades do dispositivo e do usuário.	pulldata("@property", 'username')
random()	Retorna um valor aleatório entre 0 (inclusivo) e 1 (exclusivo).	random()
regex()	Aplica uma expressão regular à entrada da pergunta. Retorna verdadeiro se o padrão for correspondido. Para mais informações, consulte Expressões regulares.	regex(., '^\d{5}$')
selected(question, value)	Verifica se a resposta está selecionada. Esta função é utilizada para perguntas select_one e select_multiple.	selected(${question_one}, 'a')
selected-at(question, number)	Utilizado para perguntas select_multiple. Retorna o nome da opção selecionada para o número fornecido, contado a partir de zero; por exemplo, '2' retornará a terceira opção selecionada.	selected-at(${question_one}, 2)
starts-with(string, substring)	Retorna verdadeiro se a string fornecida iniciar com uma substring.	starts-with(${question_one}, 'The')
string(question, expression, or value)	Converte para string. A conversão varia dependendo do tipo de dados.	string(${question_one})
string-length(question, expression, or value)	Retorna o comprimento de uma string não vazia.	string-length(${question_one})
substr(question, start, end)	Retorna a substring começando no início especificado e estende até o caractere no índice final -1, onde início e final começa em 0.	substr(${question_one}, 1, 2)
sum(repeat)	Retorna a soma de todas as respostas para uma pergunta fornecida através de repetições. Para mais informações, consulte Funções de Agregar. Anotação: Quando utilizada na aplicação de campo Survey123, esta função pode ser colocada dentro ou fora da repetição. Se a função for usada no aplicativo da web Survey123, ela deve ser colocada fora da repetição. Um valor de soma de fora da repetição pode ser referenciado em um cálculo dentro da repetição.	sum(${question})
today()	Retorna a data de hoje, armazenada internamente como meio-dia local. Esta função é usada em perguntas de data.	today()
true()	Verdadeiro	true()
uuid()	Retorna uma string UUID aleatória.	uuid()
version()	Retorna a versão da pesquisa definida nas configurações da planilha.	version()

As seguintes funções matemáticas são suportadas no Survey123:

Função	Descrição	Exemplo
acos(value)	Retorna o arco cosseno do valor.	acos(${question_one})
asin(value)	Retorna o arco seno do valor.	asin(${question_one})
atan(value)	Retorna o arco tangente do valor.	atan(${question_one})
atan2(value1, value2)	Retorna o arco-tangente do quociente dos valores.	atan2(${question_one}, ${question_two})
cos(value)	Retorna o cosseno do valor como um ângulo em radianos.	cos(${question_one})
sin(value)	Retorna o seno do valor como um ângulo em radianos.	sin(${question_one})
tan(value)	Retorna a tangente do valor como um ângulo em radianos.	tan(${question_one})
exp(value)	Retorna o expoente natural do valor.	exp(${question_one})
exp10(value)	Retorna 10 para a potência do valor.	exp10(${question_one})
log(value)	Retorna o logaritmo natural do valor.	log(${question_one})
log10(value)	Retorna o logaritmo de base dez do valor.	log10(${question_one})
pi()	Retorna pi.	pi()
pow(value, power)	Retorna o valor da potência especificada.	pow(${question_one}, 3)
round(value, places)	Retorna o valor arredondado.	round(${question_one}, 5)
sqrt(value)	Retorna a raiz quadrada do valor.	sqrt(${question_one})

Restrições

A adição de uma restrição a uma pergunta de pesquisa restringe as entradas aceitas para uma resposta. Isso pode incluir um intervalo de números específico, combinações de letras e números ou correspondência de padrões geral. Na sua planilha, a expressão de restrição é inserida no campo de restrição e o texto informativo é inserido na coluna constraint_message da planilha de pesquisa. Na expressão de restrição, a entrada para a pergunta é sempre representada por um ponto.

Por exemplo, você pode utilizar a seguinte fórmula para restringir a entrada de um campo inteiro para números positivos somente:

.>= 0

Esta fórmula, quando aplicada a um campo date, impede que o usuário insira um valor anterior ao de hoje:

.>= today()

Você também pode utilizar cálculos em restrições. Esta fórmula executa um cálculo para permitir ao usuário selecionar somente datas entre hoje e 14 dias a partir de hoje:

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

Dica:

Para evitar erros inesperados, se a sua fórmula incluir valores decimais entre -1 e 1, certifique-se de incluir um zero à esquerda em seus valores. Sem o zero à esquerda, o decimal poderá ser confundido com o caractere de operação . (or -.). Por exemplo, a seguinte expressão falhará:

.> .25 and .< 24.25

A seguinte expressão será executada conforme esperado:

.> 0.25 and .< 24.25

Expressões regulares

Uma expressão regular é uma sequência de caracteres usada para corresponder a padrões em strings. No Survey123, se o padrão corresponder, a expressão retornará verdadeiro, caso contrário, se o padrão não corresponder, a expressão retornará falso.

Você pode utilizar expressões regulares de várias maneiras para que a correspondência aos padrões restrinja as respostas válidas a um determinado formato ou para garantir que tenha conteúdo específico. Este exemplo exige que a resposta à pergunta inclua a palavra road em algum lugar dela:

regex(., 'road')

O período utilizado no início destes exemplos aplica a expressão ao campo atual. A adição do nome de outro campo em seu lugar, em vez disso, aplica a expressão regular a este campo, o que é ideal para expressões relevantes. A vírgula atua como um separador entre esta definição de campo e a expressão.

Esta expressão regular garante que a resposta corresponda exatamente à palavra estrada, sem nada antes ou depois.

regex(., '^road$')

As expressões regulares são ideais para limitar a entrada de uma pergunta a um formato padrão. Este exemplo aceita somente a entrada de um CEP de cinco dígitos dos Estados Unidos:

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

Este exemplo corresponde à resposta ao formato atual das placas de licenças da Indonésia como na seguinte foto:

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

Formatos menos padronizados podem exigir expressões regulares complexas. Esta expressão regular utilizada pelo aplicativo da web Survey123 restringe a entrada de um campo de string para corresponder ao formato de um endereço de 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,}))$')

Esta modificação da expressão acima restringe a entrada para corresponder ao formato de um endereço de e-mail, enquanto aceita caracteres não 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 exemplo, também utilizando uma expressão regular do aplicativo da web Survey123, limita um campo somente a aceitar respostas que correspondem ao formato de um endereço da 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 mais informações sobre expressões regulares, consulte a documentação do Mozilla Developer Network. Para obter uma lista de caracteres e suas funções em expressões regulares, consulte a planilha de Referência nos modelos Survey123 ou consulte Referência rápida.

Cálculos

Os cálculos são realizados na coluna de cálculo para uma pergunta. Os cálculos são normalmente associados com o tipo da pergunta de cálculo, mas também podem ser aplicados a perguntas de texto, inteiro, decimal e select_one. O resultado do cálculo pode ser utilizado para preencher expressões relevantes ou de restrição, consultando o nome de campo da pergunta de cálculo.

O tipo de pergunta de cálculo está oculto e não é exibido em um formulário. Isto significa que pode ser utilizado para conter valores que não precisam ser exibidos no formulário, mas que estão incluídos na camada de feição.

Por exemplo, você pode criar uma pergunta do tipo de cálculo, nomeá-la para calc, e inserir a seguinte expressão na sua coluna de cálculo:

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

Utilize o resultado para definir a relevância para a próxima pergunta:

${calc} <= 100

Os cálculos podem ser utilizados com as respostas nos campos date. Este cálculo estima o número de anos entre uma data inserida e hoje, ideal para calcular a idade de alguém:

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

Às vezes você precisa somente de parte de um valor ou uma versão truncada de uma resposta completa. O operador substr retorna somente parte de uma string, definida pelos números após ele. O primeiro caractere determina o ponto inicial da seleção, enquanto o segundo valor determina o comprimento (se um segundo valor não estiver presente, ele continuará até o final da string). Neste exemplo, o operador substr remove tudo, exceto a string dos caracteres 10 a 15:

substr(${previous_question}, 10, 15)

Quando o primeiro número for negativo, substr começará a contar a partir do final da string, ao invés do começo. Este exemplo retorna somente os últimos cinco caracteres da resposta:

substr(${previous_question}, -5)

Você pode usar o parâmetro calculationMode para controlar quando os cálculos são calculados no formulário. Para mais informações, consulte Modo de cálculo.

Você também pode utilizar a coluna de cálculo para funções agregadas em repetições. Para mais informações, consulte Repetições.

Siga as seguintes práticas recomendadas ao utilizar cálculos:

• Ao utilizar random(), considere adicionar uma constante para evitar obter zero (0) como resultado, por exemplo, random()+0.5. Um valor de 0 pode resultar em uma resposta em branco.
• Como nas restrições, certifique-se que todos os valores decimais entre -1 e 1 na sua fórmula tenham um 0 à esquerda, pois iniciar como um ponto decimal causa erros.
• O tipo de dados de um resultado de cálculo depende do tipo de dados de cada elemento do cálculo. Se um cálculo for executado em dois inteiros, o resultado do cálculo será um inteiro. Se um cálculo incluir um tipo de dados de string, você pode achar que um operador + concatenará valores, ao invés de adicioná-los. Para evitar resultados inesperados, utilize a função number() para garantir que valores de string em um cálculo sejam tratados como números. Por exemplo, o cálculo para adicionar question1 (do tipo inteiro) em question2 (do tipo texto) é ${question1} + number(${question2}).

Dica:

O tipo de vínculo padrão do XLSForm para uma pergunta de cálculo é string. Para substituir esse padrão, insira o tipo necessário (por exemplo, int ou decimal) na coluna bind::type para sua pergunta. Como alternativa, você pode usar o tipo de pergunta desejado (por exemplo, integer ou decimal) e definir a aparência desta pergunta para hidden.

Aviso:

Usar funções matemáticas ou operadores com perguntas de texto retorna um resultado de NaN no aplicativo da web Survey123. Para concatenar perguntas de texto, use a função concat() em vez do operador +.

Funções matemáticas complexas

A coluna de cálculo também pode lidar com operações matemáticas mais complexas. Este exemplo determina a área de um gráfico dado seu raio, usando as funções pi e potência:

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

Um método comum de medir a altura de uma árvore é medir o ângulo do nível dos olhos em um ponto de observação até o topo da árvore e a distância do mesmo ponto de observação até a base da árvore. Se o ângulo para o topo da árvore for medido em graus, o seguinte cálculo seria usado para convertê-lo em radianos:

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

Com a medição do ângulo agora em radianos, a altura da árvore (arredondada para duas casas decimais) pode ser determinada com o seguinte cálculo:

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

Formatação de data

Você pode utilizar a função format-date no campo calculation para formatar valores de data e hora. Isto pode ser útil quando você deseja exibir porções de datas para usuários ou persisti-las como strings.

Neste exemplo, o valor contido em uma hora anterior ou na pergunta dateTime é retornado em 24 horas:

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

Os qualificadores que você pode utilizar na função format-date são os seguintes:

Qualificador	Descrição
%3	0-pontos de milesegundos acolhedor (000-999)
%a	Dia de texto curto de três letras
%b	Nome do mês abreviado
%d	0-dia do mês acolhedor
%e	Dia do mês
%h	Hora (tempo de 24 horas)
%H	0-hora acolhedora (tempo de 24 horas)
%m	0-Mês acolhedor
%M	0-minuto acolhedor
%n	Mês numérico
%S	0-segundo acolhedor
%W	Número de semana Anotação: O qualificador %W não pode ser utilizado em uma função format-date na qual a pergunta de data utiliza um cálculo. Este qualificador funciona com uma pergunta de data que tem um padrão.
%y	Ano de 2 dígitos
Y	ano de 4 dígitos

Anotação:

dateTime não oferecem suporte a resoluções de tempo abaixo de um minuto. Para capturar uma resolução de tempo com datas inferiores a um minuto, considere usar as perguntas start e end.

Valores vazios

Ao utilizar restrições e cálculos que se referem a outras perguntas, considere o que ocorre quando esta pergunta está vazia (ou seja, não tem resposta). Os valores vazios são representados como segue:

• NaN (não é um número) para perguntas de integer e decimal. Este é um valor especial que representa a ausência de um valor válido.
• '' (uma string vazia) para perguntas de texto. O tipo de dados padrão para as perguntas select_one, select_mulitple, rank e hidden também é texto. Quando os tipos de pergunta select_one, select_multiple e hidden estiverem vazios, ou quando uma pergunta de rank não for alterada pelo usuário, eles conterão uma string vazia.

Dependendo se o valor for um número ou texto, o comportamento nos cálculos será diferente.

Em perguntas de inteiro ou decimal, ocorrem os seguintes comportamentos:

• Qualquer expressão matemática com um valor de NaN falha ao completar, e a pergunta permanece vazia.
• As funções min() e max() completam e ignoram quaisquer valores de NaN.
• O valor NaN comparado a qualquer outro valor só é verdadeiro em um cálculo de comparação de um valor is not equal. Todas as outras expressões resultam em falso.

Em perguntas de texto, ocorrem os seguintes comportamentos:

• A concatenação de perguntas de texto é concluída se valores vazios estiverem presentes. Por exemplo, concat("Hello" + ${firstName}, ", how are you?") resulta em "Hello , how are you?" quando a pergunta firstName está vazia.
• As funções min() e max() completam e ignoram quaisquer strings vazias.
• Uma resposta de texto vazia é igual a outra resposta de texto vazia e é sempre menor do que qualquer texto não vazio.

Você pode determinar se uma pergunta está vazia utilizando a função string-length. A função string-length pode ser utilizada com todos os tipos de pergunta. Por exemplo, string-length(${Question1}) retorna 0 se Question1 estiver vazia.

Você pode determinar se uma pergunta select_one ou select_multiple está vazia utilizando a função count-selected. Por exemplo, count-selected(${question2}) returna 0 se nenhuma seleção tiver sido criada para question2.

Perguntas select_multiple e rank

As respostas para os tipos de pergunta select_multiple e rank são armazenadas de forma diferente de todos os outros tipos de perguntas. Cada resposta marcada em uma pergunta de select_multiple é inserida na ordem na qual foi selecionada, separada por vírgulas. Por exemplo, a seleção de respostas 'A' e 'B' nesta ordem apresenta a resposta como ‘A,B’. Uma pergunta de rank também armazena suas respostas em uma lista separada por vírgulas, da classificação mais alta até a mais baixa no momento do envio.

Alguns recursos do XLSForm não funcionam com perguntas de select_multiple e rank. Por exemplo, se você inserir a resposta 'A' na coluna relevante de uma pergunta que faz referência à sua pergunta de select_multiple e a resposta da pesquisa for 'A,B', a resposta não será considerada relevante. Neste caso, a solução é utilizar a função selected(), que determina se algum dos valores aparece na lista.

A seguinte expressão, quando utilizada na coluna relevante de uma pergunta, exibe a pergunta se o usuário tiver selecionado 'A' como uma das respostas na pergunta referenciada na pergunta de select_multiple. Respostas adicionais na pergunta de select_multiple não alteram este comportamento.

selected(${previous_question}, 'A')

Recuperar um valor de um arquivo .csv

Você pode usar a função pulldata() na coluna de cálculo de uma pergunta para pré-carregar dados de um arquivo .csv. Há duas maneiras de incluir um arquivo .csv: coloque manualmente o arquivo na pasta da pesquisa media ou link para um arquivo .csv hospedado no ArcGIS.

A função pulldata() exige que os seguintes quatro parâmetros sejam especificados para:

1. O nome do arquivo .csv que contém a lista de valores. O nome não inclui o sufixo .csv de nome do arquivo.
2. O nome da coluna no arquivo .csv que contém o valor que você deseja retornar.
3. O nome do campo-chave no arquivo .csv que você utilizará para procurar o valor.
4. O valor-chave para procurar no campo-chave.

Estes valores podem ser definidos diretamente ou através de variáveis definidas em outra parte da pesquisa. No seguinte exemplo, o cálculo retorna o endereço de e-mail de alguém nomeado em uma pergunta anterior de um arquivo .csv denominado info:

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

A mesma função pulldata() também funciona na coluna de restrição, impedindo o usuário de enviar respostas que não estão no arquivo e .csv. Na coluna de restrição, esta mesma fórmula impede o formulário de aceitar quaisquer valores que não estejam na coluna .csv de nome do arquivo.

Há algumas limitações na função pulldata(). O nome do campo-chave tem a mesma limitação que a coluna de nome na planilha choices , o que significa que estes valores não podem ter espaços ou caracteres diferentes de ASCII. Além disso, como estes são arquivos .csv, o uso de uma vírgula em qualquer um destes campos faz com que sua função pulldata(), produza resultados incorretos.

Se valores no seu arquivo .csv excederem 255 caracteres, você deverá inserir um valor maior na coluna bind::esri:fieldLength para a pergunta que você está preenchendo com o conteúdo do .csv e quaisquer perguntas utilizadas como entrada para a função pulldata(). Se o seu arquivo .csv incluir valores que sejam maiores que o comprimento máximo de um destes campos, uma resposta na pesquisa falhará ao enviar e exibirá um erro de Code 1000.

Anotação:

A função pulldata() não pode ser utilizada para preencher os valores das perguntas de select_multiple.

Ao usar a função pulldata(), seus nomes de coluna .csv não podem ficar em branco e não podem conter espaços, hífens ou outros caracteres especiais.

É recomendado que você codifique o arquivo .csv usando a codificação de caracteres UTF-8. Se você estiver usando Microsoft Excel para criar seu arquivo .csv, salve-o como CSV UTF-8.

Recuperar um valor de JSON

Você pode usar a função pulldata("@json") para extrair propriedades individuais de um objeto JSON. Esta função é normalmente usada para complementar outras funções, como pulldata("@javascript") e pulldata("@layer"). A função tem a seguinte sintaxe:

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

Os parâmetros para pulldata("@json") são os seguintes:

• question name—O nome da pergunta que contém o objeto JSON, por exemplo: ${json_response}.
• JSON property—A propriedade que você deseja recuperar do JSON. Use pontos para especificar o local da propriedade na estrutura JSON. Por exemplo, para recuperar a propriedade City do objeto address, use "address.City".

No exemplo a seguir, o resultado de uma operação de geocódigo reverso é retornado como JSON em uma pergunta de texto chamada json_response:

Uma resposta do localizador semelhante à seguinte é retornada:

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

A função pulldata("@json") é usada para recuperar a propriedade City do objeto address:

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

A latitude e a longitude são recuperadas do objeto location:

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

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

Anotação:

Um ponto é usado para acessar propriedades individuais de um objeto pai. Quando um ponto também fizer parte de uma propriedade, ele deve ser colocado entre colchetes [ ]. Por exemplo, para recuperar uma propriedade denominada City.Population do objeto address, a expressão seria pulldata("@json", ${json_response}, "address.[City.Population]").

Você pode acessar um objeto em uma matriz de objetos especificando sua posição na matriz entre colchetes. O índice de uma matriz JSON começa em zero. A seguir está um exemplo de um objeto JSON retornado por atributos inteligentes. Ele contém uma 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
        }
    ]
}

Para o exemplo acima, a seguinte expressão retorna a pontuação de 0.67421875 do primeiro objeto na matriz classes:

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

Você pode usar a propriedade length para retornar o número de objetos em uma matriz. Para o exemplo acima, a seguinte expressão retorna um comprimento de 3:

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

Consultar uma camada de feição

Você pode usar a função pulldata("@layer") para consultar uma camada de feição, tabela de feição ou consultar serviço de mapa ativado. Você pode realizar uma consulta de atributo ou uma consulta espacial. Uma consulta de atributo usa uma operação getRecord ou getValue:

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

Uma consulta espacial usa uma operação getRecordAt ou getValueAt:

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

Anotação:

O local especificado em uma consulta espacial deve ser uma pergunta de ponto geográfico.

As operações getRecord e getRecordAt retorna um Objeto de feição JSON contendo uma única feição e todos os seus atributos. As operações getValue e getValueAt retornam um único valor do objeto de feição, em vez de toda a resposta da consulta.

Os parâmetros para pulldata("@layer") são os seguintes:

Parâmetro	Descrição
JSON property	Necessário para as operações getValue e getValueAt. O valor que você deseja recuperar da resposta da consulta. Exemplos: "attributes.COUNTRY" "geometry"
location	Necessário para as operações getRecordAt e getValueAt. A localização do ponto que você deseja consultar com a camada de feição. Esta deve ser uma pergunta de ponto geográfico. Exemplo: ${location}
URL	Obrigatório. A URL da camada de feição ou tabela que você deseja consultar. Este parâmetro aceita parâmetros de solicitação adicionais. Exemplo: "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/World_Countries/FeatureServer/0"
WHERE clause	Opcional. Uma expressão WHERE que filtra a camada de feição ou tabela. Quando a cláusula WHERE não for fornecida, um padrão de "1=1" será utilizado. Exemplo: "COUNTRY='Canada'"

Dica:

A função pulldata("@layer") retorna o primeiro registro na resposta da consulta. Projete e teste sua consulta para garantir que você obtenha os resultados desejados. Você pode refinar sua consulta usando uma cláusula WHERE e os parâmetros de solicitação adicionais descritos abaixo.

A função pulldata("@layer") armazena em cache as respostas da consulta para maior eficiência. Para anular o cache e garantir que uma nova solicitação seja feita sempre que a função for executada, adicione um parâmetro time=now a URL—por exemplo, concat(${layer_url}, "?t=", now()).

O exemplo a seguir consulta uma camada de feição de polígono de fusos horários mundiais e retorna o fuso horário em que o ponto geográfico está localizado:

A operação getRecordAt é usada para recuperar o fuso horário que o ponto geográfico cruza usando a seguinte sintaxe:

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

O atributo ZONE é então extraído da resposta da consulta usando a função pulldata("@json") . Alternativamente, você pode usar uma operação getValueAt no cálculo pulldata("@layer") para recuperar o atributo ZONE diretamente, sem a necessidade de uma pergunta separada para armazenar a resposta da consulta. Veja os seguintes exemplos:

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

Você pode usar pulldata("@layer") em restrições. Por exemplo, você pode aplicar uma restrição a uma pergunta de ponto geográfico para impedir que os usuários enviem locais fora de uma área de interesse.

A operação getRecordAt retorna o objeto de feição JSON para o país em que o ponto geográfico está usando a seguinte sintaxe:

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

O nome do país é extraído em uma pergunta de texto usando pulldata("@json"). Uma restrição de ${country}='Canada' é então aplicada à pergunta do ponto geográfico para garantir que a localização esteja dentro da região do Canadá.

Solicitar parâmetros

Você pode refinar uma consulta pulldata("@layer") com parâmetros de solicitação adicionais, como, como distance, orderByFields e resultOffset. Para obter mais informações sobre parâmetros de solicitação, consulte Consulta (Serviço de Feição/Camada). A função pulldata("@layer") suporta apenas solicitações que retornam um objeto de feição.

Para incluir esses parâmetros em uma consulta, anexe-os à URL após um ponto de interrogação. Parâmetros adicionais são separados por e comercial. No exemplo a seguir, os parâmetros orderByFields e resultOffset são anexados à URL da camada de feição para retornar o nome do décimo condado mais populoso da Califórnia:

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

Uma consulta agregada pode ser usada para retornar estatísticas em uma camada de feição usando o parâmetro outStatistics. As estatísticas que podem ser calculadas com este parâmetro incluem contagem, soma, mínimo, máximo, média, desvio padrão ou variância.

No exemplo a seguir, é retornada a contagem de municípios no estado selecionado:

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

No exemplo a seguir, é retornada a soma do campo POPULATION para todos os municípios do estado selecionado:

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

Anotação:

A função pulldata("@layer") suporta todos os parâmetros de solicitação listados em Consulta (Serviço de Feição/Camada) exceto o seguinte:

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

Recuperar um local de uma lista

Você pode permitir que os usuários recuperem um local de uma camada de feição, com base na seleção deles em uma lista de opções em uma pergunta select_one. A escolha é enviada como texto e sua geometria correspondente é enviada como local para a resposta da pesquisa. Essa abordagem é equivalente a uma pergunta de lista de locais no web designer Survey123.

Para criar uma lista de locais, adicione uma pergunta select_one com aparências de pesquisa e preenchimento automático. A aparência da pesquisa preenche a lista com valores de uma camada de feição. A aparência de preenchimento automático apresenta os valores em uma lista suspensa, o que é útil quando uma lista muito longa é retornada da camada de feição.

Configure a expressão search() para recuperar uma lista de valores de uma camada de feição. Na pergunta de ponto geográfico, traço geográfico, forma geográfica, adicione uma expressão pulldata("@layer") para recuperar a geometria da feição selecionada na lista.

No exemplo a seguir, os entrevistados selecionam um hidrômetro de uma pergunta select_one chamada meter_id. A geometria do hidrômetro é recuperada da camada de feição Medidores de Água e salva na pergunta do ponto geográfico:

Para obter mais informações sobre a aparência da pesquisa, consulte Pesquisar.