ArcGIS Survey123 Blog - Page 2

cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

Other Boards in This Place

Latest Activity

(195 Posts)
IsmaelChivite
Esri Frequent Contributor

The Survey123 web app supports a variety of URL parameters that can be used to initialize the contents, look and feel, and behavior of your online surveys. This article describes how you can make the use of URL parameters more secure, by encoding them.

In the following example, URL parameters are used to prepopulate and hide the submittedBy question:

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?field:submittedBy=Fernando%20Par...

Since the URL parameters are in clear text, a smart user could look at the web browser's navigation bar, figure out that a question is being hidden, and manipulate the URL parameters to show and change the question.

Here is the same URL, with encoded parameters:

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?code=ShFmaWVsZDpzdWJtaXR0ZWRCeXI...

Once the URL parameters are encoded, only the Survey123 web app can read them, making the URL much more secure.

Tip: If you are not familiar with Survey123 web app URL parameters, check these two blog posts:

Introduction to URL parameter encoding in Survey123

URL parameter encoding is a technique that allows you to obscure the contents of URL parameters. When parameters are encoded, it is not possible for end users to manipulate existing or add new parameters to the URL. This functionality is only available with Survey123 online forms published with version 3.11 or newer.

Tip: If you wish to upgrade your online forms to newer versions, see:

Encoding parameters manually (&encodeUrlParams=true)

Let's pretend you want to add a link to your survey in a website and Facebook. Using URL parameters, you prepopulate a hidden question so you can tell from which source (website or Facebook) the survey was sent. In this case, since you only need to create and encode two links, you can simply use your web browser. Here is how:

  • Create your own online survey URL and add parameters to it as usual.
  • Add &encodeUrlParams=true at the very end of the URL and reload your page.
  • The encoded URL will appear in your web browser's navigation bar.
  • Copy the URL and use it somewhere else.

This animation shows the process step by step.


Encoding parameters with the Survey123 REST API

Manually encoding your survey URLs is only practical when you have a handful of URLs to share. If you need to create many Survey123 links, or you need to create them dynamically, the best choice is to use the Survey123 REST API to programmatically encode your URL parameters.

The encodeUrlParams operation on the Survey123 REST API allows you to pass a collection of Survey123 parameters and get back the encoded URL string.

The URL endpoint of this operation is: https://survey123.arcgis.com/api/encodeUrlParams

It expects a POST request including a valid ArcGIS token and the parameters you want to encode. For example:

  {
"token": "<TOKEN>",
"params": {
        "field:submittedBy": "Fernando Paredes",
        "hide": ["field: submittedBy"]
}
"portalUrl": "<Portal URL>",  //Optional

  }

Note that it is not necessary to pass any information about your survey. All you need to pass are the URL parameters that you wish to encode and a token. The portalUrl parameter is only needed if you are working against ArcGIS Enterprise.

 

The response from the Survey123 REST API will look like the following:

{
"code": "ShBmaWVsZDpjdXNUcmFja05vchRmaWVsZDpjdXNUcmFja05vPTEyMw==",
    "success": true
}

The value of the code property represents your URL parameters, encoded.

Encoding parameters in bulk with the Survey123 REST API and Python

Say you wish to send an email to a very large group of people. You want the email to include a personalized Survey123 link, prepopulating a few questions in the survey based on the recipient's information you already have. You need to create a CSV file that you can import into an email marketing tool like MailChimp, Drip or MailerLite, including the email of the recipients and their corresponding Survey123 link. Of course, you want the Survey123 links to have the URL parameters encoded.

You can use the encodeUrlParams operation in the Survey123 REST API from any scripting language able to send a POST request. The example below highlights how links can be created from an ArcGIS Notebook. The code first performs a query on a feature service and generates a unique link for each record in the returned set. The script prints out the email and its corresponding Survey123 link with encoded parameters. Click here to preview the notebook.

Survey123 Notebook

As you can see, the code is straight-forward. A single POST request lets you specify the URL parameters you want to encode. The output of the Survey123 REST API can then be added to your Survey123 link.

Encoding parameters with the Survey123 REST API and Microsoft Power Automate

 

If you want to create a collection of links in bulk from some information you already have, the Python approach described above is a good fit. In other cases, you may need to create links dynamically.

For example, say you publish a survey for people to self-report damage to their property after a natural disaster. You would like respondents to automatically receive an email with a link that would allow them to update their own information. As you already know, using URL parameters it is possible to create a survey link to open a record in edit mode. You can also dynamically create such a link and email it right after a survey is submitted using Microsoft Power Automate and Integromat, but is it possible to also encode the URL parameters? Yes!

Overall, the Microsoft Power Automate flow could look like the following:

Survey123 Automate

Note that the trigger for the flow is the Survey123 connector. Every time a survey is submitted, the flow is executed. The payload of the trigger includes the globalId of the record just created, which is made available in Microsoft Power Automate as dynamic content.

The HTTP module is used to encode the URL parameters.

The HTTP method is set to POST. The URI parameter targets the encodeUrlParams operation in the Survey123 REST API. In the queries group, the token parameter is populated dynamically with the token value provided in the Survey123 webhook payload. The params parameter includes the URL parameters we want encoded. In this case, we pass edit for the mode and the globalId of the feature we want to edit. The globalId is coming as dynamic content from the Survey123 webhook payload as well.

 

Next the Parse JSON module is used, so that later we can easily extract the encoded values from the output of the Survey123 REST API.

Finally, the Send Email module is used to dynamically create a Survey123 link within the subject of the email. Note that the encoded parameters are dynamically added to the Survey123 link.

Summary

The Survey123 web app supports several URL parameters, allowing you to preload responses to questions, and change the look and feel and behavior of your online surveys. Using the encodeUrlParams operation in the Survey123 REST API, you can obscure these parameters to avoid manipulation by end users. 

You can generate Survey123 links with encoded parameters manually right from your browser, programmatically through scripting languages like Python, and dynamically through workflow automation in Microsoft Power Automate and Integromat.

more
2 12 2,758
IsmaelChivite
Esri Frequent Contributor

The ranking question lets people sort items in a list in order of preference. Here is an example where we ask respondents to rank a series of topics for an upcoming Survey123 workshop. Note how the ranking of a topic in the list can be changed by simply dragging it to the desired position. Users promote their favorite topics to the top of the list.

As the user submits the survey, choices in the ranking question are scored accordingly to their position in the list: The higher in the list, the higher the score. Survey123 lets you analyze survey responses to understand the average and variance of the scores for each item. The chart below shows preferences showed by respondents. The "Survey123 design best practices" ranked first with an average score of 6.53, followed by the "Survey123 reports" topic.

The Ranking question is a great resource anytime you want to measure people's preferences over a list of well defined choices.

This blog post describes how you can create your own Ranking questions with Survey123. It first presents how you can add this type of question using Survey123 designer. It then shows how you can explore results from the Survey123 website and ultimately, how you can use XLSForms to use this question type in Survey123 Connect.

Adding a Ranking question in the Survey123 designer

The Survey123 web designer lets you visually build your own surveys from a web browser. To add a Ranking question to your survey, drag it into the design preview. You can interactively add choices to the list, or add them in bulk as shown in the animation below.

Adding too many choices to a Ranking question will be overwhelming to users. It is recommended that you do not add more than 6 choices.

Choice randomization

It's human nature that people tend to either favor whatever choices are presented first (primacy effect) or last (recency effect). To avoid biased responses, you may want to randomize how choices are initially presented to the user. In Survey123, you can choose to randomize choices in all types of lists (dropdown, choice lists, checklists...). Randomization is particularly useful for the ranking question.  In the Survey123 web designer, you will find a 'Show choices in random order' option. It will be enabled by default when you add a new Ranking question, but you can choose to disable it.

Analyzing rank results

As the user submits the survey, choices in the Ranking question are scored. Here is how scoring works: If you have 5 choices in your list, the choice at the top gets a score of 5, the choice after that a 4, etc. If you have a list with 7 choices, the one at the top gets a score of 7... You get the point.

When you look at the results of your survey in the Survey123 website, you will be presented with a chart and a table. The chart sorts your choices using the average score. It also shows you the number of responses, and the number of times the question has been skipped (if appropriate). Here is an example. This chart will give you insight as to who are the winners, overall. 

The table is useful to understand the variance of the rankings. The table indicates what the average score is, and how many times a particular choice was ranked at each position.  For example, in the table below we see that the 'Survey123 design best practices' topic was selected as the top choice by 83 of the respondents (almost 30%).  We also see that while 'XLSForm advanced techniques' ranked third position, it was chosen as the first choice by a larger group than 'Survey123 reports', which ranks second.  This tells us that on average, the Survey123 reports topic is more popular than 'Advanced Techniques', but proponents of 'Advanced Techniques' care proportionally more about the topic.

If you were to look at the raw data stored in your GIS records, the output of a rank question is a comma separated list of values.  The first value in the list is the top choice for that record, followed in descending order by the rest.

Ranking questions in Survey123 Connect

If you work with Survey123 Connect, you can also add ranking questions. Use the rank question type and assign it a list from your choices worksheet. The syntax is similar to that of select_one and select_multiple questions, but you use rank instead.  If you want to randomize the choices, set the parameters value to randomize=true. It could look something like this:

typenamelabelparameters
rank topicstopics_rankedFavorite topicsrandomize=true

Ranked choices are stored as a comma separated list of choice names.

banana, apple, orange, kiwi

The comma-separated list of values honors the order of the user selection. In the example above, banana was placed at the top, followed by apple, orange and kiwi.

Keeping this in mind, you can do a few clever things with XLSForms. A common request is to be able to store the score of each choice as an attribute. Here is what I mean. Note how the scores for the fruits automatically calculate as the choices are ordered:

Once you know how to get the score of an item, you can use these values to implement your own custom validation or skip logic.

Getting the score values can be accomplished with the help of a simple JavaScript function and pulldata. If you are not familiar with using custom JavaScript functions with XLSForms, seehttps://community.esri.com/groups/survey123/blog/2020/08/07/extending-survey123-smart-forms-with-cus... 

Here is what the XLSForm could look like:

typenamelabelcalculationparameters
rank fruitsfruits_rkndFavorite fruitsrandomize=true
calculatebananaBananapulldata("@javascript","myJS.js","getScore","banana",${fruits_rnkd})
calculateappleApplepulldata("@javascript","myJS.js","getScore","apple",${fruits_rnkd})
calculatekiwiKiwipulldata("@javascript","myJS.js","getScore","kiwi",${fruits_rnkd})

And here is a JavaScript function to back it up:

function getScore (fruit, ranked_fruits)

{

         var fruits = ranked_fruits.split(',');
         return fruits.indexOf(fruit) + 1;

}

more
1 6 1,619
IsmaelChivite
Esri Frequent Contributor

The original release of the Survey123 report capabilities centered around the notion of producing reports for individual records.  With each Survey123 update, we progressively expand the report template syntax to help you build better reports. In this blog, I want to explore in detail summary sections, which were added in our July 2020 update. The content of the blog is not for beginners. I assume that you are already familiar with creating your own report templates. If not, I suggest you learn the basics from the following resources:

Summary sections are generally used to create a single report for a collection of survey records. This would commonly be referred to as a 'summary report'.  Below is an example of a Hydrant Inspection Report that illustrates this concept. Note that tables are used to categorize and report all the hydrants that have been inspected within a certain period. You can click on the image to enlarge it.

Water Hydrant Summary Table

Other examples where you may want to use reports like this include include:

  • Code violations by district report
  • Monthly hydrant inspections report
  • Property damage assessments by severity report
  • County household survey summary

A great way to get started with summary reports is to generate a Summary sample template on the Survey123 website.
The sample template demonstrates some useful summary syntax. You can then combine what you learn from the template with the Survey123 documentation to adapt the sample into your own report template.

In this blog, I will show you how to build a template completely from scratch. I want to do it that way, because I want to describe some aspects of the report template design process that will not be apparent when using the sample template.

The best way to follow this blog is hands-on. Set aside 90 minutes or so and let's build the hydrant report together.

Setting up the hydrant inspection survey sample

Before you can create a report template you need a survey with some data. We will use the Hydrant Inspections sample template that comes with Survey123 Connect:

  • Open Survey123 Connect and sign in using an account with publishing permissions.
  • Click on New Survey, and look for the Hydrant Inspection form in the Community group.

  • Make sure you set your own title for the form. In my case, I will call it Redlands Hydrant Inspections.
  • Before you publish your survey, go to the survey's Options dialog and enable the Inbox and disable the Sent folder.

  • Publish your survey and add three or four of records using the Survey123 field app.

Now that we have a survey and some data in it, let's proceed with the creation of our report template.

Getting started with the report template

We are going to progressively build up our hydrant report template. To get started, we will add a header, footer, title and a table to display a survey record selection. Below is a screenshot of our initial goal. From this humble beginning, we will add more and more contents one step at a time.

Headers and Footers

Adding a custom header and a footer to your template is generally a good practice. A descriptive header and footer make your report more presentable and provide useful information. Headers and footers cannot include Survey123 report placeholders, but you can insert Microsoft Word autotext elements and static information that will be displayed across all pages in your output report.  In my case I added an Esri logo and a fictitious address in the header. In the footer, I inserted autotext to automatically display the date when the report is created and also the page number.

You can add other Microsoft Word design elements, such as page borders, watermarks and backgrounds. Make sure you use these features wisely as they can help give your reports a professional touch.

Title and Table (Basic setup)

Next, we will add a title and a table into our report, as shown below. The table will display a handful of attributes from the survey records. For now, simply add a title and a table as shown below.

Understanding summary sections

Our template is still incomplete, but let's upload it to see how it works.

  • Sign in into survey123.arcgis.com.
  • Open the Data tab for your hydrant inspection survey. You should see the records you added earlier.
  • Open the Feature Report panel and click on the Manage templates link.

  • Click on Upload new template.
  • Browse for your report template and upload it.
  • Next, select three of the hydrant records you created and generate a preview sample report:
    • Select 3 records in the table
    • In the side report panel, make sure the report is executed against the selected records only.
    • In File options, select the option to merge into a single continuous document
    • Select your template
    • Click on the Preview sample report link

Your sample preview should look like this:

I bet the output is far from what you expected:

  • Why the table is empty? The table shows no records because we did not add instructions in the report template to fetch data from your survey. We just added a title and an empty table in it.
  • Why are the table and title repeated three times? The table is repeated because when you ask Survey123 to create a report for a selection of records, your report template is processed once for every record in your selection. Unless you enclose your template contents within a Survey123 summary section, this output is expected.

OK. So now let's add a summary section. A summary section is opened with $<$summary> and closed with $</>. Edit your template as shown below. Note that I highlighted the summary section tags in green. The formatting of the tags does not make any difference to the Survey123 report engine, but it can make your template more readable.

Note that the title is inside the summary section. As we just learned, contents outside of the summary section will be processed once for each selected record. We do not want multiple titles in our case, or multiple tables, so of these elements need to be placed inside the summary section. 

Finally, note that I added the $<$summary> opening tag in the same line as my title.  I did this on purpose, because I do not want to introduce an extra line in my output report. When the $<$summary> tag is on its own line, the line it occupies will not be removed in the output report. Sometimes you want to have $<$summary> in its own line, and sometimes you don't. It depends on what you want to do.

As we make changes in the report template, it is important to regularly upload it to the Survey123 website so we can check the syntax. Otherwise it can be challenging to figure out where exactly syntax errors happen.

  • From the report panel on the right side, click the Manage templates link.
  • Use the Edit icon in your template to upload your new version.

  • With your 3 records selected, click on Preview sample report.

At this moment, since you have no contents in your report template outside the summary section, the output of your report request is a single report, in a single file, with a single title and table.

Populating our table

We need to add instructions within our table to fetch information from the selected set of records. To do this, we need to reference in our template the layer and fields from which we want to retrieve the data. Since we may not remember the exact name of layers and fields, we will use the reference table from the Upload new template dialog.

  • From the report panel on the right side, click the Manage templates link.
  • Use the Edit icon in your template.
  • The Upload new template dialog shows the reference table at the bottom, as shown in the screenshot below.

We will use this reference table regularly, so keep this dialog open.

First, we will create what is known as repeat section. When a repeat section is encountered by the Survey123 report engine, all contents within the section are processed for every record referenced in the repeat. A repeat section is opened with ${#LayerName} and is closed with ${/}. As you can see in the screenshot below, the layer name needs to be replaced accordingly. You can get the layer name for your survey from the reference table in the Upload new template dialog.  In the context of Survey123 report template syntax, the # sign in the opening tag is an indication that the section is a repeat.

If you were to upload and run a report with the template above, new rows will be added to the table: one row per survey record. To complete the table, we need to make sure we have instructions to pull values from the corresponding fields.  The table for our survey will look like this:

It is important to note that out of all the Survey123 report template syntax we have added in our table, some parts will not be included at all in the output, and others will be replaced with data. 

  • The repeat section opening and closing tags will not be included at all. This means that you can use whatever formatting you want in your design to make it more legible.
  • The syntax to retrieve data from fields will be replaced with values from the records, so the formatting you apply to your report syntax matters. For example, if you insert an instruction like ${asset_id} setting the font color to blue, then the Asset ID will be rendered blue in the output report.

To be more exact, to define the formatting of your field values in the output report, you do not need to change the format for the entire Survey123 report template syntax. The only character that matters is the initial $ sign. This is important because sometimes the syntax can be long and interfere with your design. A good example is the Inspection Date in our sample. It uses three lines in the cell, affecting the height of the whole table in the design view.  To avoid this, use a smaller font size for the expression and apply the font style you want for the Inspection Date to the $ sign only. Here is an example of a sample preview report with various formatting styles applied:

At the end of the table, you can see an empty white row. If you do not like that, go into you report template design and remove it from the table.

So far, we have explored how to insert a table into our report to display all the input records as rows.  This is a basic, yet powerful technique that will help you model many reports you may be asked to build. Next, we will cover how to include multiple tables in a report and control the contents of these tables using filters.

Filtering and sorting report records

When defining your repeat section against the survey layer, you can use parameters to filter and sort records in your selection. For example:

${#H_Inspection | where: "last_status = 'needs_repair' " | orderByFields:"last_inspection_date DESC"}${/}

The where parameter filters the input selection from the report request. The orderByFields parameter is used to present rows sorted by inspection date in descending order.  Using filters in this way, you can insert into your report multiple tables, each for the different conditions found in your data.

Filters in your report template apply to only the collection of records selected for the report. For example, if you use the Survey123 website to select 100 records out of 2000 and then request a your summary report, the filters within the template only apply to the 100 selected records.

Statistics

A summary report might also include statistics. For example, in our hydrants example we may want to present a total count of all hydrants inspected, or a table showing a count per status. The following expression returns the total count of records from the Redlands_Hydrants layer that have been submitted to the report.

${Redlands_Hydrants |  stats:"count,objectid"}

This expression returns the total number of hydrants that need repair.

${Redlands_Hydrants | where:"last_status = 'needs_repair' " | stats:"count,objectid"}

To get the statistic, you need to pass the statistic you want (sum, max, min, count, avg) and also the field on which you want to calculate the statistic. Records with null values will be ignored.

Back to our template, we could do something like this:

And here is what I get in the final report with a selection of 3 records. The report is now looking a lot more like the summary we set out to create!

!important

The expressions we have used so far to process records within the survey layer, or to extract statistics out of it, are limited in scope to the survey records selected for the report.  By using the !important parameter, you can make the report engine work against all records in the layer you are referencing. 

For example:

Retrieve the count of all hydrants in the Redlands_Hydrants layer that need repair:

${Redlands_Hydrants | where:"last_status = 'needs_repair' !important " | stats:"count,objectid"}

Retrieve the count of all the selected hydrants in the Redlands_Hydrants layer that need repair:

${Redlands_Hydrants | where:"last_status = 'needs_repair' " | stats:"count,objectid"}

Create a repeat block to process all hydrants in the Redlands_Hydrants layer that need repair:

${#Redlands_Hydrants| where:"last_status = 'needs_repair' !important "} ${/}

Limit the repeat block to selected hydrants that need repair:

${#Redlands_Hydrants | where:"last_status = 'needs_repair' "} ${/}

The !important modifier must be used in the context of a where statement. For example, if you want to get the total number of records in a layer, you cannot do this:

${Redlands_Hydrants | !important | stats:"count,objectid"}

You have to do this:

${Redlands_Hydrants | where:"1=1 !important " | stats:"count,objectid"}

Additionally, this is incorrect, because the !important parameter is left out of the where statement.

${Redlands_Hydrants | where:"1=1" !important | stats:"count,objectid"}

This is correct, because !important is enclosed by the closing quote of the where statement

${Redlands_Hydrants | where:"1=1 !important " | stats:"count,objectid"}

An important (no pun intended) note when using !important in a repeat section is that the number of records retrieved will be limited by the maxRecordCount property in your target feature layer. Say, for example, you have 3,000 hydrants and you use !important to create a table with all 3,000 records. You will find that only the first 1,000 will be shown in the table, because the default maxRecordCount is generally set to 1,000.  If you want to alter the maxRecordCount property refer to How To: Update the maximum record count for feature services in ArcGIS Online 

The maxRecordCount threshold does not affect statistics. For example, if you use !important to do a count of all hydrants, you will get the correct number.

Group By Summary Tables

Sometimes, you may want to include in your report a table that groups a statistic for your records. In our hydrant report sample, we may want to include a table to show how many inspections (count statistic) were performed by each inspector (grouped by inspector).  In SQL jargon, this would be possible with a GROUP BY query. 

This can be accomplished by adding a repeat section, with a filter that includes a GROUP BY. Here is what the syntax would look like for the hydrant report:

InspectorInspections performed
${#H_Inspection | stats:"count,objectid,inspectionCount":"Inspector": "" | where:"1=1" | orderByFields:"Inspector DESC" }${Inspector}${inspectionCount}${/}

 

A screenshot of the resulting report is below. The blue table at the bottom shows the inspections by inspector.  The complete reference for these types of filters can be found in Feature report queries—ArcGIS Survey123 | Documentation 

Other considerations and tips

No images or maps within a summary section

Summary sections have some limitations. You cannot include a map or a photo within a summary section. If you want to include maps or images in your report, just make sure you reference them from outside the summary section.

'Straighten' your quotes

A mix of straight (" ") and cursive (“ ”) quotes in your Survey123 report template syntax can generate syntax validation and/or execution errors. For consistency, I personally like to use always straight quotes: (") for double quotes and (') for single quotes.  Microsoft Word tends to replace straight quotes with cursive (also known as smart quotes), but you can change this behavior as described at Smart quotes in Word - Word 

Embed Fonts in Microsoft Word report template (if needed)

If the output PDF files generated by your template do not show fonts the way you expect them, embed fonts in your template as described at Embed fonts in documents or presentations - Office Support 

Pricing

If your survey is hosted in ArcGIS Enterprise, you can create as many reports as you like for free. If your survey is hosted in ArcGIS Online, your reports will consume credits. Here is how credits are calculated:

  • If your survey includes all Survey123 syntax within a summary section, the cost is 0.5 credits for the entire report. It does not matter how many records are included in your summary section. 
  • If your report does not have a summary section, or you use Survey123 syntax outside a summary section, the cost of the report in credits is the result of multiplying the number of selected records you are including in the report by 0.5.

Get Creative (Cover pages and more)

The focus focus of this blog has been to show how summary sections can be used to embed tables within your report. You can, however, use summary section in more creative ways. As we saw earlier on, the contents of a summary section are only processed once during a report request. For this reason, they also make a good candidate for you to create a cover letter for a report where you want to include multiple merged individual reports.

The Damage Assessment Summary report below also shows a creative use of a summary section. The report shows a list of addresses, which has been obscured on purpose in the screenshot. The grid uses check-marks to indicate the type of property and the severity of damage.  This report template uses conditional statements extensively to evaluate if a particular cell must be checked or not.  At the very bottom of the report you can also see totals and category totals. These values are all extracted using statistical functions described in this blog and the Survey123 documentation.

more
4 11 3,679
BrettStokes
Esri Contributor

Some organizations have a requirement to work in completely disconnected environments, where access to the internet is unreliable or not available at all. For these types of environments, Esri has released the Survey123 website installer via the My Esri site. 

The Survey123 website installer lets you host your own copy of the Survey123 website and the Survey123 REST API, which is used by Survey123 Connect and the Survey123 web application.

The Survey123 website installer is designed to be configured against your ArcGIS Enterprise deployment, enabling you to work with Survey123 within the boundaries of your own network infrastructure.

Caution:

You should only install the Survey123 website if you have a specific requirement to host the Survey123 website or Survey123 REST API on your own infrastructure. There is no additional benefit to using the installed Survey123 website, but there are some disadvantages and limitations. For example, the setup and maintenance overhead, and the absence of the feature report functionality. In most cases survey123.arcgis.com should be the preference.

You can expect the near full functionality of the Survey123 system, including:

 

  • Access to your own hosted copy of the Survey123 website, allowing you to publish new surveys using the Survey123 designer, manage surveys and access the Data and Analyze survey tabs.
  • Publish surveys from Survey123 Connect to your ArcGIS Enterprise deployment.
  • Submit surveys from both the Survey123 field app and web app.

 

 A notable exception is the Survey123 feature report service, which cannot be installed locally.

Configuring a local copy of the Survey123 website is a process reserved for ArcGIS administrators with a good understanding of ArcGIS Enterprise and all of its components. Survey123 Connect can also be configured during this process to access survey templates and samples from ArcGIS Enterprise. For more details check out the Documentation and the following Knowledge Base articles:

Other Considerations

  • The Survey123 website can be installed alongside your ArcGIS Enterprise deployment or on a stand-alone web server. If installing on a stand-alone web server, the same Microsoft Windows operating system requirements and hardware requirements as ArcGIS Enterprise 10.7 apply.
  • The Survey123 website installer will support ArcGIS Enterprise 10.7 or later (versions that are in the General Availability phase of the product life cycle at the time of release). The Survey123 website installer is not linked to a specific version of ArcGIS Enterprise, so upgrades can be done independently.
  • A new version of the Survey123 website installer will be released approximately two weeks after each release of the Survey123 website, to ensure any hotfixes to the Survey123 website are included. Existing installations of the Survey123 website can be upgraded 'in place' by running the new version of the installer, which maintains all configuration settings.
  • The Survey123 website installer is only available for Windows.
  • The setup and post installation is in English only. Once installed, the website itself is available in all 38 languages that are currently supported by survey123.arcgis.com
  • The installed website contains a packaged version of the latest help documentation that can be accessed while offline, however external links used in the documentation will not work while offline. 

more
5 1 952
IsmaelChivite
Esri Frequent Contributor

This article describes how you can configure a file location provider in the Survey123 field app. This allows you to feed the Survey123 app with locations from a file where you can store, for example, a track.  This technique is useful for testing and for demonstrations.

This functionality is only available in Survey123 version 3.10 or newer

Use a File Location Provider to simulate locations in Survey123

As you may already know, the Survey123 field app can be configured with a custom location provider. This is typically used to connect your app to external GNSS receivers via Bluetooth or a network connection. These connections feed the Survey123 field app with NMEA messages, carrying location information from the GNSS receiver. 

You can also configure a location provider from a file, which is exactly what you need to do to simulate locations in Survey123. The file format Survey123 expects is (no surprise!) a NMEA log file. Most GNSS receivers can export NMEA logs, so if you get out in the field and want to replay your locations in Survey123, you can easily use those files as a location provider. If you do not have a GNSS receiver, there are a handful of utilities that you can use to create a NMEA file.

How to create a NMEA file using the Survey123 field app

You create a NMEA file, as you walk or travel, from Survey123. It is extremely simple:

  1. Tap on the satellite icon located in the top banner of the app. This opens the Location status dialog which describes the incoming data from your location provider.
  2. Tap on the red 'record' button at the bottom of the screen. This will immediately start recording your location in a NMEA file. You can now start moving if you like.
  3. Tap on the stop button to stop recording.

The NMEA file will get stored in the Survey123 directory automatically. You can now use them to replay them at any time. Lets see how next.

Configuring the file location provider in the Survey123 field app

Survey123 NMEA File

If you already have your NMEA file loaded into your device, all that's left to do now is target your NMEA file from the Survey123 app.

Here is how:

  1. While in the survey gallery, tap on your profile icon.
  2. Go to Settings
  3. Open the Location section
  4. Tap on Add location provider
  5. Select File
  6. Browse for your NMEA log file
  7. Tap on Add (IMPORTANT!)
  8. Return to the survey gallery and open your survey

Once the file location provider has been set, your location will loop through the coordinates in your NMEA file. Speed, direction of travel, fix time and other properties will be honored.

Tip: Use the loop at the end of file and update rate settings in the file provider about page to better control how your NMEA file is played.

While creating NMEA files right from within the Survey123 field app is very easy, there may be times when you can't really walk or drive the track you want to replay. Lets explore next other practical options to create NMEA files and move them into your device so you can use them from the Survey123 field app.

How to create a custom NMEA file using nmeagen.org

One particular tool I like to use to create NMEA files is https://nmeagen.org/. Here is a video showing how easy it is:

Creating a NMEA file with nmea.org

If you have a shapefile with a line representing a path, you can use the Feature Vertices To Points—Data Management toolbox | Documentation tool in ArcGIS Pro to create a point layer, then run the Add Geometry Attributes—Data Management toolbox | Documentation tool and export the coordinates to a CSV file. The CSV file can then be transformed into a NMEA file using nmeagen.org.

Moving your NMEA file into your device

If you plan to run Survey123 on Windows or macOS, keep your file in a known folder so you can browse to it in the field app. If you plan to use an Android or iOS mobile device, then you need to copy your file onto the device.

In iOS, you can move the NMEA file into your device using iTunes as shown in the animation below. With this workflow, you will need to connect your phone with your computer through a cable.

Copying data into your Survey123 iPhone folder with iTunes

Alternatively, in iOS, you can email the NMEA file to yourself as an attachment and then save it locally on your phone or tablet.

Survey123

Here are the steps:

  1. Open your email and tap on the attachment.
  2. At the bottom of your screen, a dialog will pop. Pull up the dialog until you see the Save to Files option.
  3. Navigate to on 'On My iPhone->Survey123' and then click on the Save option in the top-right corner. This will copy the file into the Survey123 app directory.

You can also Transfer files between your computer & Android device - Android Help.

Once you have the NMEA file in your computer, you are ready to configure the file location provider as described above to use it.



more
1 0 1,118
IsmaelChivite
Esri Frequent Contributor

It took longer than we expected, but a new update to Survey123 is now available! This update is part of our 3.10 release cycle, which commenced a few weeks ago with new features introduced in the Survey123 web app, website and report services. If you haven't already, check out the https://community.esri.com/groups/survey123/blog/2020/07/03/what-is-new-in-survey123-july-3-2020 announcement as it covers aspects of the 3.10 release that are not presented in this blog.

We believe you will be excited about the many new things included in this version. Before we start, here is a very quick video with some highlights:

And now for a more detailed discussion.

Streamlined Survey123 deployments

In this update we have bundled a handful of great new features to help you deploy and manage Survey123 more easily within your organization.

Administrator View in the Survey123 website

When you login into survey123.arcgis.com as a user with ArcGIS administration privileges, you will notice that a new Organization page is available. As an administrator, you have access to all surveys published in your organization. This new Organization page will help you more easily search and manage surveys created by other users. You will be able to filter surveys by owner and use the usual search and sorting options. Once you find the survey you were looking for, you will be able to do all things you, as an admin have been granted privileges to do: change the sharing properties, look at the data, update the survey questions etc.

Survey123 organization settings

Aside from the gallery of surveys within your organization, you will also find a new Settings tab. You can use these organizations settings to define the default behavior of a handful of important things. For example, you can define the group in your ArcGIS organization that sets the collection of basemaps that should be included in the basemap switcher in the Survey123 app. Finally, you can also define the basemap within that group that should be applied by default to all new designs in Survey123 designer and Connect.

Through an organization setting you can now also require all users of the Survey123 field app to update surveys in their mobile device when a new update is made available. Since this is an organization setting, it will override the 'require survey update' policy set by the owner of the survey from within Survey123 Connect (more on this later).

Survey123 organization settings are a powerful concept, allowing ArcGIS administrators to define certain behavior for survey users and designers. We envision progressively adding more settings over time.

MDM AppConfig support

If you choose to deploy the Survey123 field app through a Mobile Device Management (MDM) solution, you can now define certain behavior of the Survey123 app through the use of AppConfig properties. For example, you can use AppConfig to set the URL of the ArcGIS portal that the app will target by default, streamlining the initial setup of the app by end users. You can also disable certain features in the app, such as the ability to generate diagnostic logs or email data recovery files. Philip Wilson‌ describes all of this nicely in his https://community.esri.com/groups/survey123/blog/2020/08/04/configure-survey123-properties-in-your-m... blog post.

Silent installs of Connect and the Field App

It is not a secret anymore, we can say this out loud . Both Survey123 Connect as well as the Survey123 field app can now be installed and uninstalled silently (completely silently - no more popups!). Instructions to create your own installation scripts are included in the Unattended uninstall and install help topic.

silent-uninstall-install-ArcGISSurvey123Connect.bat

Survey123ConnectInstallFile.exe

Survey123 website installer update

For those of you who want to deploy a local copy of the Survey123 website and REST API in your own server, we are preparing a Windows installer. This will allow you to deploy Survey123 entirely in your own infrastructure, side by side with ArcGIS Enterprise, allowing you to work in completely disconnected environments. Installing the Survey123 website can also be of interest when working in remote areas with weak internet connection, or when you simply want to minimize external dependencies to better comply with security policies within your organization.

The first version of the Survey123 website installer will be made available in just a couple of weeks.

Better maps for your surveys

With this update, maps look better and most importantly, you can configure your surveys with your own custom maps too. 

Better looking basemaps in the Survey123 field app

The Survey123 field app now uses the ArcGIS Runtime map rendering engine. To start, this means that vector basemaps are now supported. As your ArcGIS organization basemap group is likely using vector basemaps, Survey123 will now be able to render them automatically. Vector basemaps deliver a much better experience than traditional raster tiled basemaps. They look crisper on your device, are more lightweight and include labels that rotate to remain readable as you change the direction of your map.

Survey123 field app showing a custom web map

Defining custom maps for your surveys

In the screenshot on the right, you can see how the map included in the survey is using a custom web map. It includes the Esri Topographic basemap and a parcel layer with a blue outline and labels on top. 

You can now tailor the map shown in your Survey123 smart form so it better fits the workflow at hand. Maps can provide important context to end users while completing the form. Starting with version 3.10, you can easily configure your surveys to use your own web maps, mobile map packages, vector tile packages etc.

As the author of a survey, you can configure your surveys to use your custom map by default, or simply add it into the basemap switcher. This is done through Survey123 Connect, using the new Linked Content dialog.

Custom maps set on your survey are honored in both the Survey123 web app and field* app.

* Note: Android devices with an armv7 architecture and 32 bit operating system are not capable of efficiently rendering ArcGIS vector tiles and offline maps. In these devices, Survey123 will default to standard Esri raster tiled basemaps and not honor custom maps defined in your survey.

Check out the https://community.esri.com/groups/survey123/blog/2020/08/07/survey123-tricks-of-the-trade-configurin... blog for more details.

Better Survey123 folders in the field app

The Survey123 field app models the organization of local survey records similar to how you organize your email. If you have a survey which you have not completed and you are not ready to send, you keep it in the Drafts folder. If your survey is ready to be sent, but your device is disconnected, then it goes into the Outbox. Once a survey is sent, it goes into the Sent folder. Finally, just like in your email, there is a folder for anything that needs attention, the Inbox. The Inbox brings existing records from ArcGIS, so you can open, update and resend them.

Survey123 records stored in these folders can be displayed as a list and as a map. In this release, the list view helps you more easily sort, search and navigate to the survey records. 

  • Sorting: Sort alphabetically, by date and by distance to your location.
  • Search and filtering: Enhanced with built-in barcode scanning capabilities.
  • Navigation: Display distance and direction indicators for each record and link to navigation apps on your device.

The illustration below shows how records in the Inbox can be sorted by distance. If the Inbox is used to list the assets assigned for inspection to the currently signed in user. This option helps promote to the top the assets that are closer to the inspector. The new location indicators are shown in the middle image. The arrow indicates the direction in which the asset can be found, as well as the distance. The direction and distance indicators update every few seconds while the end user is on the move. Finally, a handy shortcut allows users to easily load into third party navigation apps the location of the selected record. This, naturally, includes ArcGIS Navigator.

All these enhancements are particularly useful for routine inspection workflows, where the Inbox is used as a 'to do' list for the day, but the enhancements apply equally to the Drafts, Sent and Outbox as well. The behavior of the Survey123 folders is defined by the author of the survey according to the needs of the business workflow. See the Survey123 Connect section later in this blog for more details.

Better support for attachments: photos (image) and documents (file)

Survey123 has supported working with ArcGIS attachments for quite some time. ArcGIS attachments allow you to associate media (photos, images and documents) with existing GIS records. Survey123 uses ArcGIS attachments to store photos, signatures or drawings sketched from your survey. This release introduces significant enhancements and new features for working with attachments.

One image question, multiple photos

Up until this release, image questions in Survey123 allowed end users to take a single photo. With this limitation, if you needed users to take multiple photos in a survey, either you had to add multiple image questions to the survey or enclose the image question within a repeat. While both approaches worked in some cases, there were drawbacks associated with them. Starting with this update, you can configure an image question to allow multiple photos.

The screenshot below highlights how you can specify, from Survey123 designer, the number of photos that should be submitted with an image question. You can pick a fixed number, or a range.

The number of photos that can be submitted from an image question can also be controlled through XLSForm syntax in Survey123 Connect. In its simplest form, you can simply apply the multiline appearance to your image question. Additionally, you can also use the count-selected() function against an image question and it will return the number of photos in it. For a more in-depth discussion on this, check out the https://community.esri.com/groups/survey123/blog/2020/07/30/survey123-tricks-of-the-trade-photos blog post, which explores this in detail. If you have surveys already created with image questions, I bet you may want to make some adjustments in your form after learning about these enhancements.

As you work with the Survey123 field app, you will also notice that the experience to capture and manage photos from your device has changed. We made modifications to streamline the user experience when navigating through captured photos and for rotating and renaming the photos before submission.

Should users take a new photo or will they be allowed to browse for existing ones?

Many of you wanted to have your say on that critical question, and this release will please you. As the author of the survey, you can now use the method parameter in the body::esri:style to control if the image question should allow users to browse for existing photos from the gallery or if the camera should be used instead to take a new photo.

You will find more info about the method parameter in body::esri:style in the https://community.esri.com/groups/survey123/blog/2020/07/30/survey123-tricks-of-the-trade-photos blog post.

File type question

The file question allows end users to upload documents as part of a survey submission. PDF files, word documents, compressed files, etc. The complete list of file formats that you can upload through this question type is limited by the file formats supported by ArcGIS attachments. The complete list can be found at the bottom of the Edit tables—ArcGIS Online Help | Documentation topic.

File formats supported by the Survey123 file question: 7Z, AIF, AVI, BMP, CSV, DOC, DOCX, DOT, ECW, EMF, EPS, GIF, GML, GPKG, GTAR, GZ, IMG, J2K, JP2, JPC, JPE, JPEG, JPF, JPG, JSON, M4A, MDB, MID, MOV, MP2, MP3, MP4, MPA, MPE, MPEG, MPG, MPV2, PDF, PNG, PPT, PPTX, PS, PSD, QT, RA, RAM, RAW, RMI, SID, TAR, TGZ, TIF, TIFF, TXT, VRML, WAV, WMA, WMF, WMV, WPS, XLS, XLSX, XLT, XML, and ZIP.

The file question has been supported in Survey123 designer and the web app for quite some time. In this release we enhanced it to support uploading multiple files into a single question (just like the image question behaves). This release also adds support for the file question type in the Survey123 field app. This means that you can use the field app from Windows to upload local documents through a form, but also from iOS and Android!

Using XLSForm, you can leverage the mutliline appearance and count-selected() function against file questions.

Custom JavaScript functions

In every release we expand Survey123 to model more sophisticated logic via XLSForm. This is important, as XLSForm expressions are useful to create your own calculations, constraints and to model the visibility of questions and groups.  With this update, you can invoke your own custom JavaScript logic from the pulldata("@javascript") function. This is relevant because while XLSForm syntax is straight-forward, JavaScript allows you to model logic in ways that XLSForm expressions alone cannot handle. Complementing XLSforms with JavaScript is a winner!

Custom JavaScript functions are configured and published from Survey123 Connect. Using custom JavaScript functions in your smart forms is definitively an advanced workflow, but it is not rocket science. With a basic understanding of JavaScript, there is a lot you can do. You can read more in the https://community.esri.com/groups/survey123/blog/2020/07/16/extending-survey123-smart-forms-with-cus... blog post and the pulldata("@javascript") help topic to learn more about this feature and common use cases for it.

Survey123 Connect

Revised XLSForm templates

Survey123 Connect includes a couple of XLSForm templates to help you start your survey designs from scratch. These templates include a skeleton of the different worksheets and columns used in XLSForm documents as well as built-in tips, validation rules and a few other useful Microsoft Excel tricks to make your life easier.

Consolidating feedback and suggestions made over time, we decided to give these XLSForm templates a revision. They have not changed in a big way, as there was nothing fundamentally wrong with them, but they do incorporate small touches that make them better. To learn more, check out Jim Moore‌'s blog post https://community.esri.com/groups/survey123/blog/2020/08/05/updated-xlsform-templates-for-survey123.

Survey Options

The Settings > Options dialog in Survey123 Connect now helps you better control the behavior of your survey in the field app. This is likely worth an entire blog post on its own. I will highlight here a few of the things you can do:

  • Choose as the owner of the survey, if users are required to update their local copy of the survey if you update it.
  • Hide the Collect button. This is particularly useful if cases where you want users to always update existing records through the Inbox.
  • Show location indicators. This options adds a distance and direction of travel indicator to items in the Draft, Inbox (for editing existing records), Sent and Outbox folders. Location indicators are really useful to help field users navigate to existing records.
  • You can also use this dialog to enable the Inbox and Sent folder as well as control the size of images sent from the Survey123 field app and web app.

Other enhancements and fixes

Survey123 Connect and field app

  • BUG-000130126 The basemap selected for a geopoint question in Survey123 Connect is not honored when viewing the survey through survey123.arcgis.com.
  • BUG-000102606 Creating a Survey in Survey123 Connect for ArcGIS with a period in the Title results in two broken surveys being created.
  • BUG-000126810 The EXIF Sample Form in the Survey123 field app and the Survey123 Connect does not succeed in pulling the latitude and longitude of photos taken on Arrows F-04K and Arrows F-01K devices.
  • BUG-000103458 Survey123 for ArcGIS custom URL schemes do not include support callback parameters such as http://x-callback-url.com.
  • BUG-000095706 Unable to create a new survey or sign in using the Ubuntu version of Survey123 for ArcGIS app.
  • BUG-000131096 Incorrect spelling for settings in Survey123 in Portuguese OS
  • BUG-000125110 Basemaps do not display as expected for all scales when a survey is re-downloaded to a device after imagery updates.
  • BUG-000129238 Survey123 Connect for ArcGIS does not recognize the decimal numbers if the Windows language settings is in Portuguese (Brazil).
  • BUG-000124917 In Survey123 3.5 app for mobile devices, the geopoint question Default Map View button does not return the map extent to the designated default location and instead shows the null point in the Atlantic Ocean.
  • BUG-000113973 When accessing a publicly available survey published to Portal for ArcGIS using the Survey123 for ArcGIS app, if the portal connection is not configured in the app, the survey is inaccessible with the following error message, "Survey ID is not found."
  • BUG-000105957 Deleting a side loaded basemap (TPK file) using the Map Library within a Survey123 for ArcGIS app does not remove the TPK from an Android device.
  • BUG-000128449 Unable to view a web map published from Survey123 Connect for ArcGIS built from an existing feature service.
  • BUG-000132191 Please add directions in the description section of this 'Download Survey123 Data' item.
  • BUG-000132196 The documentation for Survey123, "Prepare for editing existing survey data" still shows information about using Non-Standardize Queries.
  • BUG-000131615 The linked content web maps no longer appear in the basemaps list for geopoint questions when opening in ArcGIS Survey123 field app V3.9.149.
  • BUG-000132302 Unable to add multiple images in ArcGIS Survey123 mobile app (iOS) in a survey that was created with ArcGIS Survey123 Web Designer.
  • ENH-000123885 Improve the process of capturing and sending Diagnostic Log files in the Survey123 for ArcGIS Field App.
  • ENH-000107685 The Survey123 for ArcGIS field app should allow different file formats as attachments while submitting form data
  • ENH-000130703 Allow Survey123 to integrate with other apps using Universal links
  • ENH-000118156 Allow for image attachments to be submitted through a webhook.
  • ENH-000123510 Send related record information to webhook providers
  • ENH-000131457 Ability to view photos taken with Survey123 on iOS and Android devices.
  • ENH-000115447 The Survey123 field app should search all internal storage locations for photos on Android devices
  • ENH-000130402 Provide the ability to submit multiple images from a mobile device in one form when submitting survey
  • ENH-000127042 Add ability to organize or filter downloaded surveys in the field app
  • ENH-000123765 Allow the Collect option to be disabled for users in Survey123 field app
  • ENH-000116753 Allow disable the upload image from device's files in survey 123
  • ENH-000116357 With Survey123 for ArcGIS, allow barcodes to be used to search for existing features in the Inbox
  • ENH-000105321 In Survey123 for ArcGIS application, user would like to request for the copy and edit survey feature to be placed under the 'Inbox' folder/feature instead of 'Sent' folder/feature.
  • ENH-000127282 Enhance the performance with Survey123 barcode scanner to include a greater ability to read codes other than black and white
  • ENH-000129448 Please provide documentation that demonstrates accessibility workflows across the ArcGIS Survey123 platform.
  • ENH-000130111 Provide the ability to run the silent installation completely silent without showing install or uninstall progress pop-up.
  • ENH-000122295 Close/Return to initial Application on submission when survey is launched from Custom URL
  • ENH-000107611 Provide the option for a Survey123 survey called outside of the application with the 'arcgis-survey123://?itemID=' Custom URL Scheme to open the 'Inbox' menu by default instead of the 'Collect' menu
  • ENH-000109445 Implement the ability to utilize a secured service as an online basemap in Survey123
  • ENH-000114786 Add ability to customize the map shown in the Geopoint question form in Survey123 for ArcGIS, either by choosing a custom Web Map or by adding boundary datasets within the default map.
  • ENH-000113866 Survey123 field app: add support for PortalURL property via Mobile Device Management (MDM) configuration to set default portal
  • ENH-000111185 Provide the ability to view feature layers as operational layers in a map in Survey123.
  • ENH-000107257 Display results of a survey submission in the map view of the Survey123 Field app when geopoint locations that were collected are a part of a repeat question.
  • ENH-000126047 The List and Map views are not available on the Sent page of the Survey123 for ArcGIS field app when a survey has a geopoint question within a repeat.
  • BUG-000132618 An error message, "ERR_TUNNEL_CONNECTION_FAILED" is returned when signing in to the ArcGIS Survey123 field app after removing a previous Portal for ArcGIS connection that utilized SAML authentication.

Survey123 website, web app, report services, Integromat and Microsoft Automate connectors

Next steps

We will be watching closely GeoNet and and the Esri Technical Support queue in case any adjustments are needed to this update. We have made quite a lot of changes and have added lots of new functionality, so we are not ruling out some focused patches. While this is ongoing, you will see before the end of August the release of the Survey123 website installer for Windows. On top of this, a Beta version of 3.11 should be made available for testing in late August or early September through the Survey123 Early Adopter Community website as well.

more
13 20 12.2K
Philip-Wilson
Esri Frequent Contributor

Starting with ArcGIS Survey123 version 3.10, you can now configure properties via Managed App Configuration (AppConfig) in your Mobile Device Management (MDM) solution or by configuring application property defaults when creating a custom build of Survey123 using ArcGIS AppStudio. By configuring Survey123 properties you can manage how the Survey123 field app is installed on mobile devices and ensure that the properties are standardized and configured according to your company policies in your enterprise environment.

Read more...

more
5 16 2,281
Jim-Moore
Esri Regular Contributor

The XLSForm templates for ArcGIS Survey123 have been updated with a fresh new look. The new templates are available in Survey123 Connect in the New Survey dialog under Templates. This blog post provides an overview of the new templates and some best practices for working in Excel. It also covers some tips for migrating an existing survey to a new template.

Read more...

more
7 3 3,063
IsmaelChivite
Esri Frequent Contributor

Survey123 includes great capabilities to help you specify how photos should be captured from your smart form. The 3.10 release, introduced even more: multiline appearance and the method setting in the body::esri:style column. This blog highlights these new features and a few other techniques so you can get the best out of photos in your smart forms.

Read more...

more
7 25 8,071
IsmaelChivite
Esri Frequent Contributor

Take a look at the two Survey123 projects below, both of them use custom maps. The Hydrant Maintenance form on the left uses a map showing the water network as well as color coded hydrants indicating the status of the last inspection performed in them. The hydrants are also labeled indicating both their Asset ID as well as the date of the last inspection performed. The Violation Report project on the right, combines an Esri Topographic basemap with a couple of feature layers: one representing parcel boundaries in blue, and one highlighting existing violation reports within the last year. Using Survey123 web or field app, it does not matter, you can always decide what map is best for the end users of your smart form.

Configuring the right map for the workflow at hand is important to provide the best possible experience to end users. The map used in the Hydrant Maintenance form helps users validate if the hydrant they are inspecting is in fact the one that should be inspected. The map provides good geographic context. It also gives a visual indication of when hydrants were inspected for the last time. The Violation Report map helps more clearly identify to which property the violation found belongs and if other violations have been reported in the area in the past.

In this blog, I will describe how using Survey123 Connect, you can control what maps should be presented to the users of the surveys you create. It all boils down to a couple of things: defining what is the standard collection of maps for surveys across your organization and what are the specific maps that should be included with each survey. This all comes together in the map gallery that gets presented in the Survey123 web and field apps, when users interact with the map. Lets start first getting clear on what I mean by the app map gallery, and then we will learn how to configure the maps that get shown in them.

Understanding the Survey123 app map gallery

When a user interacts with a map in any of the Survey123 apps (web or field), a map gallery (aka basemap switcher) is available for users to choose what map should be displayed. The illustration below shows that the map gallery can be accessed from the top-right corner of the map in the Survey123 web app. Once opened, the user selects the map to be shown.

The experience in the Survey123 field app is very similar. Below you can see that the end user has opened the Inbox map to look at all the hydrants that have been assigned for inspection today. The map gallery can be accessed to switch the map at any time.

The collection of maps in the gallery, is the combination of two sets: the collection of organization basemaps, and a collection of maps linked to the specific survey. 

Organization Basemaps

Organization basemaps are, no surprise, defined at the ArcGIS organization level and as such, they apply to all Survey123 projects. These are basemaps that will be made available, always, to all Survey123 users through the map gallery.

Traditionally, Survey123 pulled the list of maps from the basemap gallery defined at the ArcGIS (Online or Enterprise) level. However, in practice this may not quite work because often the collection of basemaps that makes sense to users of other ArcGIS apps, is not appropriate for Survey123 users. Starting with version 3.10, we introduced a new Survey123 specific organization setting so you can control the contents of the Survey123 basemap collection in the organization. This setting is honored by the Survey123 field app in 3.10 and will be also honored by the Survey123 web app in 3.11. 

Generally speaking, you do not want to include many basemaps at the organization level. One or two at most should do for the vast majority of cases. For context, the standard basemap gallery that comes predefined with ArcGIS Enterprise and ArcGIS Online has more than 20 choices. Definitively way too many for the average Survey123 end user. So many basemaps make sense for someone authoring a web map, but not for someone completing a built-for-purpose form. 

To create your own custom Survey123 organization basemap gallery:

  • Login into your ArcGIS organization with a user with administrative privileges.
  • Create a new Group in ArcGIS.
  • Share web maps with that group, ensuring that the web maps are also shared with Everyone, or at the very least with all users within your organization.
  • Login into the Survey123 website. You should see an Organization tab (only administrators see this tab).
  • Click on Organization and then activate the organization Settings tab.
  • Choose the group from which the maps should be shown and optionally the default map.

It is ultimately your call, but generally speaking, one or at most two maps in this group should probably do. Keep in mind that these maps will be shown in all surveys, so you really want to keep the list to a minimum.

Survey Basemaps

In addition to the maps set by the ArcGIS administrator in the Survey123 organization basemap gallery setting, survey authors can optionally add maps to their own surveys. This is done through Survey123 Connect.

In Survey123 Connect, select a published survey and navigate to your Survey Settings -> Map tab. The map gallery will display choices from your organization Survey123 basemap. While the default map selected is set at the organization, as a survey author you can override it by selecting another one from the list.

Most importantly, if you switch to the Linked Content tab you will be able to link your survey with other maps, specific to your project. Linked maps will also show in the survey map gallery. You can also select any of the linked maps as the default map of your survey.

Lets do this step by step:

  • In Survey123 Connect, select a survey and click on survey Settings
  • Click on Linked Content and link a map
  • Optionally, go to the survey Map tab, open the map gallery and select your linked map as the default map, then publish for the default map change to take effect.

In many cases, users may not even need to ever switch maps. That is ideally what you want to happen!  If you set the right basemap that will help users do their job, then there will be no need for users switching basemaps.

Before we finish, just a few additional notes and considerations:

  • Before you can link a map to your survey, you must first publish the survey. It is not possible to link maps to a survey that is not published.
  • Once you link a map using Survey123 Connect, you do not need to republish the survey for end-users to see the new map. However, if you want your linked map to also be the default map of the survey, then you need to re-publish.
  • You can link web maps, and also vector tile packages and mobile map packages. Now, if you link offline maps, then end users will need to manually download those linked maps before they can be used. Linked offline maps do not get automatically downloaded when the survey is downloaded or refreshed in the field app.
  • You are responsible for ensuring that linked maps have been consistently shared with your end users. For example, if you link a map that is not shared with Group A, and you share your survey with Group A, then people in that group will be able to use your survey but not access your linked map. You can, of course, take this to your own advantage . For example, if you work with users in 5 separate regions, it may make sense for you to share a single survey with all of them, link the corresponding 5 regional maps and share your linked apps accordingly so only users will only see maps for their own region.

more
8 12 5,165