Fundamentos do XLSForm

XLSForm é um padrão aberto que simplifica a criação de formulários. A criação é realizada em um formato legível por humanos utilizando uma planilha. Para informações sobre XLSForm, visite https://xlsform.org/. O Survey123 suporta a maioria (mas não todos) dos recursos no XLSForm padrão.

Há muitas opções para criar planilhas compatíveis com XLSForm. Microsoft Excel é mais comumente utilizado, mas outras opções incluem Kingsoft Spreadsheets, Google Sheets e OpenOffice Calc. Há também construtores de XForms online que exportam planilhas do XLSForm que você pode usar com ArcGIS Survey123.

Para ajudá-lo a criar seus formulários, oArcGIS Survey123 inclui a ferramenta de desktopSurvey123 Connect , que funciona lado a lado com sua ferramenta de criação do XLSForm para criar arquivos XLS. O Survey123 Connect permite a você visualizar seus arquivos XLSForm à medida que os cria ou edita, publicar seus formulários no ArcGIS Online e ArcGIS Enterprise, e criar camadas de feição com base em sua especificação de formulário para coleta de dados. O ArcGIS Survey123 Connect está disponível para Windows.

Após seus formulários serem publicados no ArcGIS, você poderá utilizar o site da web Survey123 para compartilhar seus formulários com membros das suas organizações do ArcGIS. Você também pode analisar mapas e tabelas para quaisquer dados coletados pelo Survey123 field app, como também, exportar seus resultados da pesquisa.

Para a finalidade deste tópico, suponha que você esteja utilizando o ArcGIS Survey123 Connect e Microsoft Excel para criar seus formulários.

Cada livro de tarefas do Excel normalmente tem duas planilhas: pesquisas e opções. Uma terceira planilha, configurações, também está descrita abaixo. As planilhas têm um conjunto de colunas obrigatórias que devem estar presentes para o formulário funcionar. Além disso, cada planilha tem um conjunto de colunas opcionais que permite um controle adicional sobre o comportamento de cada entrada no formulário. Cada entrada deve ter valores para cada uma das colunas obrigatórias, mas as colunas opcionais podem ser deixadas em branco. As colunas adicionadas no seu livro de tarefas do Excel , sejam obrigatórias ou opcionais, podem aparecer em qualquer ordem. Você pode omitir colunas opcionais e deixar qualquer número de linhas em branco. Toda formatação de arquivo .xls é ignorada, portanto, você pode utilizar linhas de divisão, sombreamento e outra formatação de fonte para tornar o formulário mais legível.

Planilha da pesquisa

Esta planilha fornece ao seu formulário sua estrutura geral. Ela contém a lista completa de perguntas e informações sobre como elas aparecerão no formulário. Cada linha geralmente representa uma pergunta; no entanto, há mais recursos descritos abaixo que você pode adicionar ao formulário para melhorar a experiência do usuário.

A planilha de pesquisa tem três colunas obrigatórias: tipo, nome e rótulo ou dica.

• A coluna de tipo especifica o tipo de pergunta do XLSForm que você está adicionando. Há uma lista bem definida de possíveis tipos de perguntas para esta coluna.
• A coluna de nome determina o nome do campo na camada de feição no qual as respostas à pergunta serão armazenadas. Nenhum espaço ou caracteres especiais são permitidos nesta coluna. Os nomes devem ser exclusivos para todas as perguntas em cada camada.
• As colunas de rótulo e dica contêm o texto para suas perguntas. Este é o texto que você visualizará no formulário. Uma pergunta exige pelo menos um rótulo ou dica; fornecer um rótulo é recomendado para evitar mensagens de aviso. Espaços e caracteres especiais são permitidos nestas colunas. Alternativamente, você pode usar colunas de tradução. Rótulos e dicas também oferecem suporte a código HTML limitado e variáveis que serão substituídas em sua pesquisa pela resposta de outra pergunta. Para mais informações, consulte Anotações.

Para obter uma visão geral das colunas na planilha de pesquisa, consulte Colunas da planilha de pesquisa.

Planilha de opções

Esta planilha é utilizada para especificar as opções de resposta para perguntas de múltipla escolha. Cada linha representa uma opção de resposta. As opções de resposta com o mesmo nome de lista são consideradas parte de um conjunto de opções relacionadas e aparecem juntas para uma pergunta. Isto também permite que um conjunto de opções seja reutilizado para múltiplas perguntas (por exemplo, perguntas de sim ou não).

A planilha de opções tem três colunas obrigatórias: nome da lista, nome e rótulo.

• A coluna de nome da lista permite a você agrupar um conjunto de opções de resposta relacionadas. As opções com o mesmo nome da lista são apresentadas como o conjunto de respostas para uma pergunta.
• A coluna de name especifica o valor que é persistido no ArcGIS. Os valores na coluna de nome não aceitam caracteres especiais. Não é recomendado incluir nomes de opções duplicados em uma lista de opções. Para mais informações sobre incluir nomes de opções duplicados, consulte Perguntas de múltipla escolha.
• A coluna de rótulo mostra a opção de resposta exatamente como você deseja que ela apareça no formulário. Alternativamente, você pode usar rótulo das colunas de tradução.

Ao criar formulários no Excel, a sintaxe que você utiliza deve ser precisa. Por exemplo, se você escrever Choices ou choice em vez de choices, o formulário não funcionará.

Planilha de configurações

A planilha de configurações é opcional, mas permite a você personalizar ainda mais seu formulário. A personalização disponível inclui um título que é exibido enquanto o formulário está sendo editado, um nome de instância para identificar exclusivamente cada formulário preenchido, um identificador de versão exclusivo para sua pesquisa entre outros. Para mais informações, consulte Configurações.

Planilhas suplementares

Os modelos do Survey123 incluem planilhas que contêm as propriedades, operadores e funções que você pode utilizar em seu formulário. Estas planilhas também são utilizadas para preencher as listas suspensas e outras regras de validação de dados nas planilhas de pesquisa e configurações. Para garantir que a validação de dados funcione conforme o esperado, é recomendável que você não modifique o conteúdo das planilhas suplementares.

Tipos de perguntas

O XLSForm suporta vários tipos de perguntas. Por exemplo, para coletar o nome e a localização de uma loja, escreva o seguinte:

A seguinte tabela lista as perguntas que você pode inserir na coluna de tipo do seu XLSForm, qual entrada é aceita para a pergunta e o tipo de campo que é criado na camada de feição do ArcGIS associada à esta pergunta quando o formulário é publicado. O autor da pesquisa pode alterar o tipo de campo para muitos desses tipos de pergunta. Para mais informações sobre os tipos de campo, consulte Colunas personalizadas da Esri.

Tipo de perguntas	Entrada da resposta	Tipo de campo padrão
integer	Entrada de número inteiro.	esriFieldTypeInteger
decimal	Entrada de decimal.	esriFieldTypeDouble
range	Entrada para um intervalo de números fornecidos.	esriFieldTypeInteger
text	Resposta de texto livre.	esriFieldTypeString
select_one list_name	Pergunta de múltipla escolha em que o usuário pode selecionar apenas uma resposta. Substitua list_name pelo nome da sua lista de opções. Você pode alterar o tipo de campo; no entanto, o nome da escolha é sempre tratado como uma string no aplicativo de campo quando usado em expressões.	esriFieldTypeString
select_multiple list_name	Pergunta de múltipla escolha em que o usuário pode selecionar várias respostas. Substitua list_name pelo nome da sua lista de opções. Você não pode alterar o tipo de campo, e o nome da escolha é sempre tratado como uma string no aplicativo de campo quando usado em expressões.	esriFieldTypeString
rank list_name	Pergunta de classificação; classifica uma lista de opções em ordem. Substitua list_name pelo nome da sua lista de opções. Você não pode alterar o tipo de campo, e o nome da escolha é sempre tratado como uma string no aplicativo de campo quando usado em expressões.	esriFieldTypeString
note	Exibe uma anotação na tela; não utiliza nenhuma entrada. Pode exibir cálculos ocultos.	esriFieldTypeString
geopoint	Coleta uma única coordenada do GPS. Você não pode alterar o tipo de campo.	esriFieldTypeGeometry
geotrace	Coleta uma linha no mapa. Você não pode alterar o tipo de campo.	esriFieldTypeGeometry
geoshape	Coleta um polígono no mapa. Você não pode alterar o tipo de campo.	esriFieldTypeGeometry
date	Entrada de data.	esriFieldTypeDate
time	Entrada de hora.	esriFieldTypeString
dateTime	Aceita uma entrada de data e hora.	esriFieldTypeDate
image	Tirar uma foto.	Anexo
begin group	Começa um grupo de perguntas.	Não aplicável
end group	Finaliza um grupo de perguntas.	Não aplicável
begin repeat	Começa um conjunto de perguntas repetidas.	Não aplicável
end repeat	Finaliza um conjunto de perguntas repetidas.	Não aplicável
calculate	Executa um cálculo nos valores do formulário. Este tipo de pergunta está oculto e não aparece no formulário.	esriFieldTypeString
username¹	Ao entrar no ArcGIS Online ou ArcGIS Enterprise, este campo é preenchido automaticamente com o nome de usuário da conta. Este tipo de pergunta está oculto e não aparece no formulário.	esriFieldTypeString
email¹	Ao entrar no ArcGIS Online ou ArcGIS Enterprise, este campo é preenchido automaticamente com o endereço de e-mail da conta. Este tipo de pergunta está oculto e não aparece no formulário.	esriFieldTypeString
hidden	Um campo que não aparece no formulário. Utilize as colunas bind::esri:fieldType e bind::esri:fieldLength para especificar esquema de dados.	esriFieldTypeString
barcode	Digitaliza um código de barras.	esriFieldTypeString
start	Inicia a data e hora da pesquisa.	esriFieldTypeDate
end	Finaliza a data e hora da pesquisa.	esriFieldTypeDate
deviceid	ID Único gerado no Survey123 representando o dispositivo específico no qual a pesquisa foi realizada. Isto é diferente da International Mobile Equipment Identity (IMEI) de um dispositivo móvel, pois o Survey123 executa em dispositivos que podem não ter um IMEI.	esriFieldTypeString
audio	Registre uma amostra de áudio.	Anexo
file	Carrega um arquivo no dispositivo.	Anexo

¹Uma opção mais flexível é usar a função pulldata("@property") para recuperar valores. Consulte Propriedades do usuário e dispositivo.

A amostra Tipos de Perguntas, inclui todos os tipos de pergunta suportados no ArcGIS Survey123. Você também pode consultar a Referência rápida para verificar como estes tipos de perguntas são representados no Survey123 web designer e aplicativo da web.

Metadados

O XLSForm tem as seguintes opções de tipo de dados para a coleta de metadados:

Tipo de metadados	Descrição
start	Inicia a data e hora da pesquisa.
end	Finaliza a data e hora da pesquisa.
username	Registre o nome de usuário do usuário atual registrado no ArcGIS Online ou ArcGIS Enterprise. Este tipo de dados não utiliza entrada.
email	Registre o endereço de e-mail do usuário atual registrado no ArcGIS Online ou ArcGIS Enterprise. Este tipo de dados não utiliza entrada.
deviceid	ID Único gerado no Survey123 representando o dispositivo específico no qual a pesquisa foi realizada. Isto é diferente da IMEI de um dispositivo móvel, pois o Survey123 executa em dispositivos que podem não ter uma IMEI.

Anotação:

Estes elementos de metadados do XLSForm não são suportados: subscriberid, simserial e phonenumber.

Para coletar todos estes metadados, adicione o seguinte no início da sua pesquisa:

As entradas de metadados descritas acima são automaticamente capturadas pelo ArcGIS Survey123. Se o seu arquivo não tiver um cabeçalho de coluna ou tiver uma vírgula no final das linhas do arquivo, o arquivo não será importado para a pesquisa.

Quando você adicionar os tipos inicial e final, o ArcGIS Survey123 habilitará automaticamente o tempo da camada de feição para sua pesquisa. Desta maneira, você pode filtrar o conteúdo da sua pesquisa com base na data na qual os dados foram enviados. Adicionar as entradas inicial e final também é útil se você deseja saber exatamente quanto tempo passou entre o momento no qual o formulário foi aberto e quando foi marcado como concluído.

Dicas

Às vezes você deseja adicionar uma pequena dica a uma pergunta no seu formulário, instruindo o usuário como responder a pergunta, mas você não deseja que a dica faça parte da pergunta. Você pode adicionar dicas às perguntas no XLSForm. Adicione uma coluna de dica e adicione sua mensagem de sugestão. Veja o seguinte para um exemplo:

Você também pode adicionar dicas de orientação a uma pergunta usando a coluna guidance_hint . As dicas de orientação instruem o usuário sobre como responder a uma pergunta, mas ficam ocultas até que o usuário clique no botão de dica de orientação que aparece ao lado da dica. As dicas de orientação podem ser usadas somente se já houver uma dica para a pergunta.

Texto do placeholder

Você também pode fornecer texto de espaço reservado para perguntas que aceitam uma entrada digitada (como perguntas de texto, número inteiro e decimal, e perguntas select_one com aparência de preenchimento automático), definindo o parâmetro placeholderText na coluna body::esri:style. Com placeholderText=@[hint] ou placeholderText=@[guidance_hint], a dica ou dica de orientação fica oculta e o texto da dica é colocado dentro da área de entrada da pergunta. O texto do espaço reservado aparece na área de entrada quando a pergunta está vazia.

Anotação:

As dicas não são suportadas para perguntas iniciar repetição e iniciar grupo.

O texto do espaço reservado não é compatível com o aplicativo da web Survey123.

Atualizar modelo

O Modelo Avançado inclui todos os recursos XLSForm suportados noSurvey123 e está disponível na caixa de diálogo Nova Pesquisa no Survey123 Connect. Este modelo é atualizado regularmente para adicionar novas funcionalidades e aprimorar a experiência de criação de pesquisas. Embora você possa continuar usando as versões anteriores do modelo sem problemas, talvez queira atualizar suas pesquisas existentes para o modelo XLSForm mais recente para aproveitar as alterações mais recentes.

A ferramenta Atualizar modelo XLSForm atualiza o XLSForm existente para uma pesquisa para a versão mais recente do modelo avançado. Ele faz isso copiando o conteúdo das planilhas de pesquisa, opções e configurações para suas respectivas linhas e colunas no novo modelo. Quaisquer colunas que você adicionou também são copiadas para o novo modelo, como também, a planilha external_choices se você estiver usando seleções externas.

Para executar a ferramenta, você deve configurar um ambiente Python no Survey123 Connect. Para mais informações, consulte Configurar o Python.

No Survey123 Connect, abra a pesquisa que deseja atualizar. Clique em Ferramentas e, em seguida, clique em Atualizar modelo XLSForm. Uma caixa de diálogo exibe mensagens enquanto a ferramenta está em execução. Quando o processo for concluído, o arquivo .xlsx na pasta de pesquisa será atualizado para o modelo mais recente e a visualização do formulário no Survey123 Connect será recarregada. Se um erro for encontrado enquanto a ferramenta estiver em execução, o XLSForm existente será preservado.

Anotação:

O XLSForm da pesquisa deve ser um arquivo .xlsx. A ferramenta Atualizar modelo XLSForm não pode ser executada em arquivos .xls.

É recomendado verificar se as colunas, validação de dados, formatação de células e estilos de fonte do XLSForm original estão presentes no XLSForm atualizado. A ferramenta cria uma cópia de segurança do XLSForm existente e um arquivo de log em C:\Users\<username>\ArcGIS\My Survey Designs\<surveyName>\debug\template_updater. Para restabelecer uma pesquisa a partir de uma cópia de segurança, copie o arquivo .xlsx da pasta template_updater para a pasta raiz da pesquisa. Exclua o XLSForm existente e renomeie a cópia de segurança para corresponder ao original.

Anotação:

A cor de preenchimento da célula na primeira coluna de cada linha é aplicada a toda a linha no modelo atualizado.

Para pesquisas multilíngues, as colunas de idioma padrão, como label::language (xx) e hint::language (xx), serão excluídas do modelo atualizado.