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.
A seguinte tabela contém todas as colunas suportadas do Survey123. Essas colunas estão incluídas na planilha de pesquisa no modelo Avançado e são listadas nesta tabela na ordem em que aparecem na planilha.
| Coluna | Descrição |
|---|---|
| tipo | Selecione um tipo de pergunta a partir da lista fornecida. Insira um nome de lista válida se utilizar uma pergunta select_one ou select_multiple. |
| nome | O nome do campo na camada de feição. |
| rótulo | O rótulo da pergunta exibido em sua pesquisa. |
| sugestão | As informações que podem ajudar a responder a pergunta de pesquisa. |
| guidance_hint | informações adicionais, exibidas somente apos pressionar um ícone. |
| aparência | Selecione a aparência deste campo em sua pesquisa. |
| exigido | Selecione sim para exigir um valor neste campo antes de completar a pesquisa. |
| required_message | Quando um campo exigido não tiver nenhuma resposta, a mensagem nesta coluna parecerá para iniciar uma resposta. |
| somente para leitura | Selecione sim para configurar os valores neste campo para somente leitura. Estes valores não podem ser editados na pesquisa. |
| padrão | Configure o valor padrão deste campo. Isto pré-preencherá a pesquisa com o valor padrão. Isto pode ser utilizado para economizar tempo ao fornecer uma resposta utilizada comumente ou mostrar o tipo de escolha de resposta que é esperada. |
| cálculo | Execute os cálculos utilizando os valores de perguntas precedentes (por exemplo, ${number} * 100). Referencie o campo de cálculo para exibir o resultado (por exemplo,The answer is ${calc}). |
| restrição | Limite a faixa de números que podem ser inseridos (por exemplo, .>0 e .<100). A função pode ser utilizada com todos os tipos de pergunta. |
| constraint_message | Quando as condições de restrição não são atendidas, esta mensagem parecerá para iniciar uma resposta válida. |
| relevante | Isto permite a você pular perguntas ou fazer perguntas adicionais parecerem com base na resposta para uma pergunta anterior. Uma pergunta se torna visível ao atender as condições na coluna relevante (por exemplo, ${name} = 'value'). Uma pergunta oculta por esta coluna envia somente valores nulos. |
| choice_filter | Ao utilizar seleção em cascata, este campo mantém a expressão para corresponder às colunas de atributo adicional na guia de opções (por exemplo, attribute = ${value}). |
| repeat_count | Este valor especifica o número de registros disponíveis em uma repetição. Após a contagem de repetição ter sido especificada, os registros não podem ser adicionados ou excluídos a partir da repetição. |
| media::audio | Copie um arquivo de áudio na subpasta de mídia para seu projeto e insira o nome do seu arquivo de áudio (por exemplo, audio.mp3) para apresentar o áudio com sua pergunta. |
| media::image | Copie um arquivo de imagem na subpasta de mídia do seu projeto e digite o nome do arquivo de imagem (por exemplo, image.jpg) para exibir uma imagem com sua pergunta. |
| bind::type | Um tipo de campo que substitui o tipo de campo padrão da pergunta. |
| bind::esri:fieldType | Define o tipo de campo alvo na camada de feição. Isto pode ser utilizado para substituir o tipo de campo padrão (por exemplo, campos calculate e select_one são strings por padrão. Para salvar os valores na camada de feição como inteiros, selecione (esriFieldTypeInteger). |
| bind::esri:fieldLength | Define o comprimento do campo de destino na camada de feição. Você pode usar isso para substituir o comprimento do campo padrão. |
| bind::esri:fieldAlias | Fornece valores para o nome alternativo do campo na camada de feição. Você pode usar isso para substituir os valores de nome alternativo de campo padrão, que são derivados do rótulo da pergunta. |
| body::esri:style | Fornece expressões para definir o estilo e o comportamento de uma pergunta (por exemplo, a cor de fundo para grupos e repetições). |
| bind::esri:parameters | Fornece parâmetros para uma pergunta que são específicos para Survey123 (por exemplo, parâmetros para controlar o comportamento de repetições ao editar sua pesquisa). |
| bind::esri:workflow | Fornece parâmetros para permitir que uma pesquisa esteja disponível para um modo de medição de telêmetro. |
| parametros | Fornece parâmetros XLSForm padrão para uma pergunta (por exemplo, os parâmetros start, end e step para uma pergunta de intervalo). |
| body::accept | Defina os tipos de arquivo aceitos para a pergunta do arquivo. Aceita extensões de arquivo, com várias extensões de arquivo separadas por vírgulas (por exemplo, .jpg, .png). |
| body::esri:visible | Isto permite a você pular perguntas ou fazer perguntas adicionais parecerem com base na resposta para uma pergunta anterior. Uma pergunta se torna visível ao atender as condições na coluna body::esri:visible (por exemplo, ${name} = 'value'). Uma pergunta oculta por esta coluna ainda contém e envia valores. |
| body::esri:inputMask | Forneça uma expressão para utilizar uma máscara de entrada para fornecer um configurar de configuração para entrada de dados utilizando caracteres e símbolos. |
| label::language (xx) | Forneça traduções para seus rótulos de perguntas. O idioma deve ser especificado por seu nome e código (por exemplo, label::Español (es)). Adicione uma nova coluna para cada idioma. A lista de idiomas aparecerá no menu suspenso na pesquisa. |
| hint::language (xx) | Forneça traduções para suas dicas de perguntas. O idioma deve ser especificado por seu nome e código (por exemplo, hint::Español (es)). Adicione uma nova coluna para cada idioma. A lista de idiomas aparecerá no menu suspenso na pesquisa. |
| guidance_hint::language (xx) | Forneça traduções para suas dicas de orientação. Você deve especificar o idioma por seu nome e código (por exemplo, guidance_hint::Español (es)). Adicione uma nova coluna para cada idioma. A lista de idiomas aparecerá no menu suspenso na pesquisa. |
| required_message::language (xx) | Forneça traduções para a mensagem que aparece se uma pergunta obrigatória não for respondida. O idioma deve ser especificado por seu nome e código (por exemplo, required_message::Español (es)). Adicione uma nova coluna para cada idioma. A lista de idiomas aparecerá no menu suspenso na pesquisa. |
| body::accuracyThreshold | Forneça um valor numérico para o limite (em metros) acima do qual os valores de posição não serão aceitos. Aplica-se ao ponto geográfico e aos vértices das perguntas de forma geográfica e traçado geográfico. |
| bind::esri:warning | Aplique uma expressão que mostre avisos se as condições não forem atendidas. |
| bind::esri:warning_message | A mensagem que exibe se as condições de bind::esri:warning não são atendidas. |
| bind::saveIncomplete | Configure para verdadeiro se o aplicativo for salvar automaticamente a resposta após a pergunta. |
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 |
| intervalo | 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_name1 | 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 |
| ponto geográfico | 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 |
| data | Entrada de data. | esriFieldTypeDate |
| hora | Entrada de hora. | esriFieldTypeString |
| dateTime | Aceita uma entrada de data e hora. | esriFieldTypeDate |
| imagem | 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 |
| calcular | Executa um cálculo nos valores do formulário. Este tipo de pergunta está oculto e não aparece no formulário. | esriFieldTypeString |
| username2 | 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 |
| email2 | 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 |
| código de barras | 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. Este tipo de pergunta está oculto e não aparece no formulário. | esriFieldTypeString |
| áudio | Registre uma amostra de áudio. | Anexo |
| file1 | Carrega um arquivo no dispositivo. | Anexo |
1—atualmente, os tipos de perguntas de arquivo e classificação são suportados apenas no aplicativo de campo Survey123.
2—uma opção mais flexível é usar a função pulldata("@property") para recuperar valores. Consulte Propriedades do dispositivo, usuário e pesquisa.
No Survey123 Connect, experimente o exemplo Tipos de perguntas para visualizar um formulário que inclui todos os tipos de perguntas suportados pelo Survey123. Consulte a Referência de tipos de perguntas para saber como esses tipos de perguntas são representados no Survey123 web designer.
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. |
| 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:
Anotação:
As dicas não são suportadas para perguntas iniciar repetição e iniciar grupo.
Você também pode adicionar dicas de orientação a uma pergunta usando a coluna guidance_hint . As dicas de orientação instruem ainda mais o usuário sobre como responder a uma pergunta, mas ficam ocultas até que o usuário toque 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 com aparência autocomplete), 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:
O texto do espaço reservado não é compatível com o aplicativo da web Survey123.
Atualizar modelo
Anotação:
Esta seção descreve uma funcionalidade que está disponível apenas no Survey123 Connect. Esta funcionalidade não está disponível no Survey123 Studio.
O Modelo avançado inclui todos os recursos do XLSForm suportados no aplicativo de campo Survey123 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 clique em Atualizar modelo de 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.
Caracteres especiais
Nomes de perguntas e nomes de opções não devem conter caracteres especiais, como espaços, vírgulas, hífens, parênteses, colchetes ou caracteres como $, % e #. É importante que os nomes das opções para perguntas select_multiple não contenham espaços ou vírgulas.