Skip navigation
All Places > ArcGIS Survey123 > Blog > 2020 > August
2020

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.

 

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. 

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.

 

 

 

 

 

 



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 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 Configure Survey123 Properties in your MDM with AppConfig 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 Survey123 Tricks of the Trade: Configuring survey maps 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 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 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 Extending Survey123 smart forms with custom JS functions 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 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.

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.

 

What are EMMs and MDMs?

 

Enterprise Mobility Management (EMM) is a set of people, processes and technology focused on securely and efficiently managing systems and devices (desktop, server, and mobile). This includes setting policies, pre-configuring settings, applying restrictions, deploying apps, and setting profiles and assignment policies to deliver apps to your managed devices. The management of mobile devices is one of the many components available as part of an EMM solution.

 

There are a number of Mobile Device Management (MDM) solutions that can help you implement your EMM solution for managing your enterprise mobile devices, and these MDM solutions include support for what is known as Mobile Application Management (MAM). Here are just a few of the available MDM solutions that many of the Esri mobile apps have already been tested and successfully deployed with: VMware Airwatch, Microsoft Intune, MobileIron Cloud, Samsung Knox, Citrix XenMobile, IBM MaaS360, and Cisco Meraki.

 

What is Managed App Configuration?

 

Managed app configuration allows apps to be remotely configured through an EMM solution. In order to use managed app configuration, the app must be installed on the device and managed via an MDM solution. While managed app configuration is a feature supported by most of the popular MDM providers, it's best to check with your provider if this feature is supported.

 

In general, MDM providers support AppConfig using key-value pairs. In Survey123 we follow the guidelines found within the AppConfig community's XML standard specification for iOS, Windows, MacOS and Linux. On Android, we support Android's Restriction Manager XML spec.

 

Currently, managed app configuration in Survey123 via an MDM is only supported on iOS and Android.

 

Supported AppConfig Properties

 

The following properties can be configured for the Survey123 field app via AppConfig key-value pairs set in your MDM provider. These properties can also be configured as application property defaults in a custom build of Survey123 by modifying the application properties found in the settings menu of your custom application in ArcGIS AppStudio.

 

Key NameTypeDefaultDescription
portalURLstringhttps://www.arcgis.comDefault portal URL.
portalNamestringArcGIS OnlineDefault portal display name. If portalURL is configured then this property should also be configured.
portalAuthenticationstringN/ADefault portal authentication parameters. Comma separated, case insensitive.
  • Blank for default authentication configuration
  • IWA - Integrated Windows Authentication
  • SSO - Enables single sign on for Windows clients when combined with IWA.
portalResourceKeystringSurvey123PropertiesResource name used for organization level properties.
requireSignInbooleanfalseUsers are required to sign in to continue to gallery page.
enablePortalManagementbooleantrueUser can manage ArcGIS Connections (add or remove portal configurations).
enableDiagnosticsbooleantrueEnable diagnostics options in Settings menu.
enableDataRecoverybooleanfalseEnable data recovery to send survey database and attachments.

 

If your portal uses IWA authentication and you are configuring the default portal connection in your MDM or in an AppStudio custom app using the portalURL property, the following three properties must be set:

 

  • portalURL
  • portalName
  • portalAuthentication (set as IWA)


Failure to set the portalAuthentication type on an IWA portal will cause an issue in deploying the AppConfig settings when adding the portal to the list of ArcGIS connections in the Survey123 field app.

 

Adding managed app configuration settings in your MDM provider

 

Below is an example of how to set the key-value pairs when creating an app assignment for your Survey123 application, in this case using the VMware AirWatch MDM console. Note that the UI and available options will differ in each MDM solution so please check with your MDM provider and relevant documentation about how to set AppConfig properties.

 

VMware AirWatch MDM AppConfig

 

Setting application property defaults via ArcGIS AppStudio

 

Below is an example of how to set application property defaults via ArcGIS AppStudio for your custom Survey123 application:

AppStudio Survey123 Properties

AppStudio Survey123 Properties

 

For more information on configuring Survey123 properties, please refer to the ArcGIS Survey123 online documentation.

 

If you would like to know more about Esri's approach to Mobile Application Management, please read the ArcGIS Secure Mobile Implementation Patterns document available from the ArcGIS Trust website.

The XLSForm templates for ArcGIS Survey123 have been updated with a fresh new look in version 3.10. The new templates are available in Survey123 Connect in the New Survey dialog under Templates.

 

XLSForm templates in the New Survey dialog in Survey123 ConnectIt's important to note that your existing XLSForms will continue to work as normal! This blog post provides an overview of Survey123's templates and what's new in 3.10, as well as some best practices for working with the templates. But first, a quick XLSForm recap...

 

XLSForm and Survey123

 

Survey123 is based on XLSForm, a standard specification for authoring survey forms. Survey123 Connect takes an XLSForm and converts it into a format that respondents can fill out. Surveys authored in the Survey123 web designer also rely on XLSForm; when you publish a survey in the web designer an XLSForm is created automatically behind the scenes.

 

An XLSForm can be any .xls or .xlsx file that satisfies the minimum XLSForm requirements. For more information on the required sheets and columns, refer to XLSForm essentials—Survey123 for ArcGIS | Documentation. Beyond the required sheets and columns, the Excel file can include any other worksheets you like. You can also change the formatting on any of the sheets (for example, cell shading or font size) and remove any unused columns (with the exception of the required columns) without affecting the function of the XLSForm. So long as the right values are in the right columns on the right sheets, your design should convert to a survey form in Connect without issue. While it's possible to make your own XLSForm from scratch, Survey123's templates provide everything you need to get started with your survey designs.

 

The templates you download in Survey123 Connect are designed to help you conform to the XLSForm specification. The templates contain the required sheets and columns, and include data validation rules and drop-down lists to help you fill out your XLSForm correctly.

 

While we've progressively added new columns, question types and appearances to the template with each release of Survey123, we thought it was time to give the look and feel of the templates a refresh and also introduce a new Standard template.


What's new?

 

Prior to version 3.10 Survey123 had two templates: Advanced and Basic. At 3.10, Advanced has been updated and Basic has been replaced by Standard.

 

Advanced template

 

The updated Advanced template is very similar to the previous one, in that it includes all of the XLSForm question types, appearances, and columns supported in Survey123. Here are the key changes to the new version:

 

  • The types worksheet has been replaced by a set of six supplementary sheets (more details in the worksheets table, below).

 

Excel worksheet tabs in the updated XLSForm templates

 

  • Columns on the survey sheet have been rearranged into a more logical order. The most commonly used columns are closer to the left of the worksheet, where they're easier to access. Because the order of columns has changed, please take extra care when migrating existing surveys to the new template (see more on this, below).
  • Colours, fonts and styles have been refreshed to give the template a more modern look and feel. Arial is so 2004!
  • In the drop-down for the type column on the survey sheet, the square brackets around "list_name" for select_one select_multiple questions have been removed. These brackets should not be included when specifying the list name, and their inclusion in the previous templates was the source of some confusion! As an example, to use a choice list named "fruits" for a select_one question, enter select_one fruits in the type column.

 

Standard template

 

The new Standard template replaces the Basic template, which was deemed to be, well, a bit too basic! The Standard template is essentially a "cut-down" version of the Advanced template that includes only those question types and appearances that are supported in both the Survey123 field app and Survey123 web app. The Standard template is useful for surveys intended to be used in both apps, where you want a comparable experience in the field app and on the web.

 

Some columns have also been omitted to further simplify the Standard template. The language columns have been removed from the choices and settings sheets and a handful of the more specialised columns have been omitted from the survey sheet, as follows: body::esri:inputMask, label::language (xx), hint::language (xx), body::accuracyThreshold, bind::esri:warning, bind::esri:warning_message, and bind::saveIncomplete.

 

Worksheets

 

The following table outlines the contents of each worksheet in both the Advanced and Standard templates. The green shading denotes a required XLSForm sheet and the blue shading denotes a new supplementary sheet:

 

WorksheetDescription
surveyContains all questions, calculations, appearances and other features that make up your survey form design.
choicesChoice lists for multiple choice questions (select_one and select_multiple) are stored here.
settingsGeneral settings for your survey, like form title.
VersionInformation about when the template was last revised. In the Advanced template, the compatibility information on the Question types and Appearances sheets might change with each revision, so it's important to refer to the revision date to determine the currency of this information.
Question typesList of question types you can use in the type column on the survey sheet. In the Advanced template, columns C and D indicate if the question type is supported in the field app and web app, respectively.
AppearancesList of appearances you can use in the appearance column on the survey sheet. In the Advanced template, columns D and E indicate if the appearance is supported in the field app and web app, respectively.
Field typesList of Esri field types and form bind types you can use in the bind::esri:fieldType and bind::type columns on the survey sheet.
ReferenceUseful reference information for functions, operators, HTML formatting, and regular expressions.
ReservedA list of reserved keywords that cannot be used in the name column on the surveys sheet.

 

Best practices

 

Here are some best practices for getting the most out of the Survey123 templates and avoiding common headaches. For a more detailed resource of excellent Excel tips, see Ismael Chivite's blog post Survey123 Tricks of the Trade: Microsoft Excel.

 

  • Do not modify the contents of the supplementary sheets. These sheets contain tables and named ranges that are used in the data validation on the survey and settings sheets, so it's best to leave them alone.
  • When copying and pasting cells or rows, always use the paste values option to preserve data validation:

 

Paste values in an Excel worksheet

 

This is especially important when copying cells or rows from another workbook; unless you paste the values only, you will likely retain a link to the data validation in the other workbook, which can lead to errors:

 

Warning message for links in Excel workbook

 

  • If you're a dab hand with XLSForm you can simply remove the data validation if it's annoying you. Survey123 Connect will validate your form as it's updated, so your syntax will be checked in any case. To remove data validation in Excel:
    • Select a cell, range, row or entire sheet.
    • On the Data ribbon, click Data Validation.
    • Click the Clear All button to remove all data validation rules for the selected cell(s).

 

Clear data validation in Excel

 

Migrate an existing survey to a new template

 

While using the new templates is not essential, you might want to update an existing survey to the new look and feel. Here are some tips for migrating an existing survey to the new template:

 

  • Download a template from one of the following links: Advanced or Standard.
    • Alternatively, create a new survey in Connect to get a copy of the template.
  • In your existing Excel file, column-by-column, copy the contents of the survey, choices and settings sheets and paste into the corresponding column in the new template. As mentioned, the column order has changed so a straight copy-paste of the entire sheet isn't going to work. Remember to use the paste values option!
  • Replace the existing .xlsx file in the survey's folder in your C:\Users\UserName\ArcGIS\My Survey Designs directory with the new version, ensuring the file name is identical to the original.
  • Republish your survey.


For those with a keen eye, here's a list of other changes:

 

  • Added the file question type, which is supported in the field app as of 3.10.
  • Modified the data validation rules in places to make it more user-friendly.
  • Removed the yellow input messages (tool tips) on the survey and choices sheets.
  • Example instance name added to the settings sheet.
  • Dummy form title added to settings sheet.
  • Example select_one question added to survey sheet.
  • A new allow_choice_duplicates column has been added to the settings sheet. This column doesn't do anything yet, but it will become useful in a future release of Survey123. It can be disregarded for the time being.
  • All of the samples in Connect have been updated to the new Advanced template.

 

We hope you enjoy the new templates and look forward to your feedback! Please leave a comment below, or drop us a line at survey123@esri.com.

Survey123 includes powerful capabilities to help you specify how photos should be captured from your smart form. With the 3.10 release, even more powerful new features were introduced: 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. Most of what is described in this article involves the use of Survey123 Connect and requires familiarity with XLSForms. Check out the Survey123 XLSForm tutorials in YouTube or our documentation if you need to get started.

 

As with many other Tricks of the Trade articles, we will start easy, and progressively explore more sophisticated techniques one step at a time.

 

The Basics: One question, one photo.

 

If you want your users to submit a photo through your smart form, you will include a question of type image. Here is an XLForm example:

 

typenamelabel
geopointlocationIncident location
imagephotoPhoto of the incident

 

Like any other question type, you can use the required column to define if the end user must submit data for your question or not. In the next XLSForm example, an expression is used in the required column to determine if a photo must be submitted. If the severity of the incident is high, then a photo must be submitted. Otherwise, the photo question will be presented to the user as optional.

 

typenamelabelrequired
geopointlocationIncident location
select_one severityseveritySeverity
imagephotoPhoto of the incidentselected(${severity},"high")

 

Controlling the source of the photo: Camera versus browse

 

By default, the Survey123 web and field apps will let end users either take a new photo using the camera or browse for an existing photo in the device. Sometimes, you want to have control over the source of the photo. If you are designing a survey for inspectors to document code violations, for example, you may want them always to take a new photo with the camera, and not allow browsing of existing photos in the device.

 

The method parameter in the body::esri:style XLSForm column lets you specify if both methods are allowed, or just one. If the method parameter is set to camera, users will need to capture a photo using the camera. If method is set to browse, users will need to browse for an existing photo. If you want to give users a choice, leave the the body::esri:style column empty or set the method parameter to camera,browse

 

Here is a visual representation of what the user experience looks like using the different method parameter options:

And here is what an XLSForm looks like if you want to force users to submit a new photo from the camera:

 

typenamelabelbody::esri:style
geopointlocationLocation
imageimagePhotomethod=camera

 

One question, multiple photos

 

If you want users to submit more than one photo with your survey, you can either add multiple image questions or alternatively use the multiline appearance on an image question. There are good cases for both approaches. For now, lets start with the multiline appearance:

 

typenamelabelappearance
geopointlocationIncident location
imagephotoIncident photosmultiline

 

Support for the multiline appearance for image questions was added in version 3.10. When using the multiline appearance you will initially not see much of a difference in your form. However, after you take the first photo, you will see that new options appear for you to take additional photos and navigate through all the photos you have taken.

 

Counting photos submitted, and limiting how many photos can be submitted

 

The XLSForm count-selected() function can be used to get the number of photos a user has added to an image question. Two common uses for this function are calculations and constraints.

 

The following example shows how you can store as a feature attribute the total number of photos submitted through an image question. Once you have this attribute, you can use it to filter, label or simply set the symbology of features in a web map. For example, you may want to create a filter to hide features with no associated photos.

 

typenamelabelappearancecalculation
geopointlocationIncident location
imagephotoIncident photosmultiline
integerphoto_countPhotos submittedcount-selected(${photo})

 

Using count-selected(), you can also also control how many photos can be submitted with a question. For example, you can setup a constraint to limit photos submitted with your image question to less than 5:

 

typenamelabelappearanceconstraint
geopointlocationIncident location
imagephotoIncident photosmultilinecount-selected(${photo})<5

 

You can use count-selected() against an image question with and without the multiline appearance.

 

Image questions and repeats

 

Support for the multiline appearance in image questions was added with version 3.10. Before that, if you wanted users to upload more than one photo you had to either add multiple image questions to your survey or include the image question within a repeat. Adding multiple image questions in a survey is still a valid pattern, as we will describe later. Creating a repeat block simply to include a single image question is never a good idea, because the repeat will create a new related table and your attachments will link to that table. It will be extremely difficult for you to later explore the attachments in ArcGIS that way. Instead of using a repeat for that, use the multiline appearance as described above.

 

typenamelabelhint
geopointlocationLocation
begin repeatphotosPhotosDo not create a repeat just to add a single image question in it. Use the multiline appearance instead on the image question (as shown above)
imagephotoPhoto
end repeat

 

For clarity, this is not to say that you should not include image questions within a repeat. For example, If you want to have a repeat and then add an image question along with a text question for a description or something else, that is all good. It is adding a repeat containing just an image question that should be avoided.

 

Here is an example where having an image question within a repeat is justified. In this case, the repeat makes sense because we want to associate multiple attributes (Direction, Latitude, Longitude as well as a user entered description) with every photo.

 

typenamelabelcalculationbind::esri:fieldType
geopointlocationLocation
begin repeatphotosPhotos
imagephotoPhoto
textdesDescription
calculatedirDirpulldata("@exif", ${image}, "GpsImageDirection")esriFieldTypeDouble
calculatelatLatpulldata("@exif", ${image}, "GpsLatitude")esriFieldTypeDouble
calculatelonLonpulldata("@exif", ${image}, "GpsLongitude")esriFieldTypeDouble
end repeat

 

Note that photos in the repeat table have attributes to extract their direction, latitude, longitude and even a user-entered description of the photo. Storing all these attributes for every one of the photos would not be possible using the multiline appearance in the image question. This is what justifies the use of the repeat.

 

If you are not familiar with the pulldata("@exif") function check the Working with EXIF image metadata in Survey123 for ArcGIS  blog post.

 

One survey, multiple photos

 

It is possible to include multiple image questions within a single form. Note that adding multiple image questions to a form is very different from enabling multiple photos in a single question.

 

The Virginia Department of Agriculture and Consumer Services (VDACS) was notified in early 2020 that many residents in the State had received unsolicited packages containing seeds from an unknown source. To better understand the extent of the problem, a survey was put together for Virginia residents to submit reports of unsolicited seed packages. In this survey, one question was added to capture a photo of the front of the envelope, and a separate question for the back of the envelope.

 

 

Rather than asking users to take one or more photos of the envelope in a single question with multiline appearance, this survey uses two separate image questions. This gives more explicit direction to the user, which generally is going to yield better data.

 

typenamelabel
imagephotoFrontFront of package
imagephotoBackBack of package

 

An additional advantage of using multiple image questions is that each of the photos will be automatically tagged by Survey123 with the name of the corresponding image question. This later on will be an advantage when you want to put your photos into a Survey123 report. Since the front and back photos are tagged differently, you will be able to specify where exactly each of the photos should go.

 

Using multiple image questions within a form is a good practice when you want to explicitly tell users what each photo should contain. In the Virginia seeds use case above, you are telling users to take a photo of the front of the envelope first, and then a photo of the back. This is a good use case. If you want to simply want to open up the possibility of submitting multiple photos of something, then the multiline appearance is the way to go.  For example, say you want people to submit multiple photos of an issue in an asset. You do not know in advance what exactly the end user will report, but you want that user to be able to submit a few photos; that is a perfect example for multiline.

 

Since the multiline appearance was not available in the past, some of you created surveys with multiple image questions as follows:

 

typenamelabelhint
geopointlocationLocation
imagephoto1Photo
imagephoto2PhotoDon't do this. Use mutliline appearance in photo1 instead
imagephoto3PhotoDon't do this. Use mutliline appearance in photo1 instead

 

Now that the multiline appearance has been added, it is time to adjust the XLSForm design accordingly. Remember you can also use the count-selected() function to limit the number of photos that you want people to submit. Removing the extra image questions in your form will not cause data loss, however, keep in mind that the multiline appearance is only supported in Survey123 3.10 or newer, so you will want end users to be up to date with their app version or otherwise the appearance will be ignored.

 

Controlling the size of photos

 

Using Survey123 Connect, you can control the size of photos to be sent to ArcGIS. There are a number of devices out there and each of them may send photos of different sizes. You can bring consistency by properly configuring your survey from Survey123 Connect.

 

In Survey123 Connect, go to the Options tab of your survey and scroll down until you see the Images section. Use that setting to control how big you want images to be when sent to ArcGIS. The default value is 1280 pixels on the largest edge, which generally works well for most workflows, the quality is good and the size of the photo is manageable.  However, you can reduce images down to 320 pixels or leave them in their original size.

 

 

 

Photos in reports

 

Survey123 includes a powerful report service which you can use to create high quality reports in MS Word and PDF format. Check Understanding Survey123 Feature Reports for an introduction to this service.

 

Survey123 reports require you to create a template specifying the content and look and feel of your report. These templates are authored as Microsoft Word documents where you insert placeholders to fetch data from your survey records. The full syntax for report templates is described at Feature report templates—Survey123 for ArcGIS | Documentation 

 

In regards to photos, you can control the size of the photos in your report and even where to put each of the photos from your survey. This is where using mutliple image questions can really pay off.

 

For example, the following syntax in a report template will insert into your report the photo corresponding to the incident_photo question in your form. The photo will be added to the document with a width of 300 pixels and the height will grow proportionally to preserve the original aspect ratio.

${incident_photo | size:300:0}

If you used the multiline appearance in your survey, you will want to use the following syntax to arrange all photos vertically within your report:

${#incident_photos}
${$file | size:300:0}
${/}

This syntax will arrange the photos horizontally (note that I adjusted the width to 200px to have images fit within the width of the page).

${#incident_photos}${$file | size:300:0}${/}

Unfortunately, as of the time I write this, it is not possible to arrange photos in a table (each photo in its own cell). Mike Onzay figured that adding a space right before the closing tag would add a nice separation between photos. That is pretty clever! Thanks Mike for the tip! Here is the same expression with the space added:

${#incident_photos}${$file | size:300:0} ${/}


Photo Watermarks

 

Photo watermarks is a neat feature in Survey123. Since this article is about photos, I thought I would bring it up, although there is a separate blog covering this topic Survey123 Tricks of the Trade: Photo Watermarks 

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.

Starting with ArcGIS Survey123 version 3.10, you can incorporate logic in your forms using custom JavaScript (JS) functions. Custom JavaScript functions complement XLSForm expression syntax, giving you flexibility to build better calculations, data validation rules, constraints etc.

 

This blog provides some guidance to get you started with custom JavaScript functions. For completeness, check the pulldata JavaScript help topic. It assumes familiarity with Survey123 Connect, XLSForm syntax and JavaScript.

 

Getting started

 

Let's start with a simple scenario. In Survey123 Connect, create a new survey and add a couple of questions as shown below. Our goal is to create a custom JavaScript function to calculate the greeting question.

 

typenamelabelcalculation
text

myname

Your Name:

textgreetingGreeting:

 

Using regular XLSForm syntax, we could easily calculate the greeting as follows:

 

concat("Hello ", ${myname})

 

This already teaches us something: custom JavaScript functions are not always the best approach. If you can solve something easily using pure XLSForm functions, do not use a custom JavaScript function. In our case, we will use this example only because it helps us focus on the basics of setting up a custom JavaScript function.

 

To invoke a JavaScript function from XLSForm, we use the puldata() function. For example:

pulldata("@javascript","myFunctions.js","HelloMe",${myname})

 

The parameters for the pulldata() function are as follows. First we pass "@javascript" to indicate that we want to execute a JS function. Then, we pass the name of the JavaScript file that contains our function, which in this example is "myFunctions.js". The next parameter is the name of the function within the file that we want to call: "HelloMe". Lastly, we pass as many parameters as the JS function takes. In our case, we will just pass the name of the survey taker, which is contained in the ${myname} question. If the JS function takes more parameters, we would add them in our pulldata() function call as more parameters separated by commas.

 

typenamelabelcalculation
text

myname

Your Name:

textgreetingGreeting:pulldata("@javascript","myFunctions.js","HelloMe",${myname})

 

For the pulldata() function above to work, we need to create a "myFunctions.js" file with its corresponding "HelloMe" JavaScript function. In fact, as you refresh your survey preview in Connect you will get a File not found: myFunctions.js error. That is totally expected.

 

Custom JavaScript files are stored in the survey directory, within a folder called scripts. In Survey123 Connect, click on Files in the left bar. This will open the survey folder directory. Create a folder called scripts as shown below.

 

Survey123 Custom JavaScript Functions Connect

 

While custom JavaScript functions are now an official feature of Survey123, some of you have been using them already for the past couple of years. Please note that the folder name for the JavaScript functions is now called scripts. For backwards compatibility the Survey123 field app will continue working with the old folder name of extensions, but it is best to use scripts as the folder name moving forward. Now, keep in mind that Survey123 versions 3.9 and older do not know about the scripts folder!

                                      

We will now place our myFunctions.js file in the scripts folder with its corresponding HelloMe function. You can use whatever IDE you want to create the JavaScript file. You can even use Notepad if you like. For this example, we will go with something like this:

 

function HelloMe(whosthere) {

    return "Hello, " + whosthere;
}

Once the file is saved in the scripts folder, use the Update button in Survey123 Connect to reload the survey to test your calculation.

 

Survey123 Custom JavaScript Functions Connect

 

When working with custom JavaScript functions, you will want to frequently make edits in your code and test in Connect. Luckily, Survey123 Connect will automatically reload your JavaScript functions into the preview as soon as you change them from the IDE. In the animation below, note that as soon as the JavaScript file is saved, the form automatically reflects the changes.

 

Survey123 Custom JavaScript Functions Connect

 

Naturally, you will find a few bumps before you get your JavaScript functions working. Here are some of the most common errors that you will encounter:

 

ErrorDescription
File not found: myFunctions.jsYour pulldata() function is trying to load a JavaScript file that cannot be found in the scripts folder
Error in myFunctions.js : 6:16 Expected token `;'Syntax error in line 6 of your function.
@javascript error:TypeError: Property 'HelloMe' of object [object Object] is not a function in myFunctions.js:HelloMeYour pulldata() function is trying to invoke a function that cannot be found in the JS file you specified.

 

When writing your own custom JavaScript functions for execution within your Survey123 form, remember that your code will not run within the context of a web browser; you are limited to JavaScript ES6. You can't use DOM objects, or frameworks like JQuery, Ember, Angular etc. You can't access local files or make asynchronous calls either. Despite all these limitations, there is still quite a bit you can do!

 

Once you have your JavaScript function working, you can publish your survey. Custom JS functions are supported in online surveys as well as in the Survey123 field app. However, keep in mind that JS functions will not execute unless a user is signed in to the Survey123 field app or web app.

 

Custom JavaScript functions are not supported in public surveys. A user must be signed in before the JS function executes.

                                      

 

Parsing complex data structures

 

A common use for custom JavaScript functions is to parse complex structures, so you can extract key information from them to calculate questions in your form. From an XLSForm perspective, the syntax in your Survey123 form is really not much different from what you already learned in the Getting started section. The real complexity is handled inside the JavaScript function itself.

 

As an example, let's take the contents of an AAMVA PDF417 barcode. This type of barcode is used in driver licenses and encodes information such as name, birthday and many other things. Since the Survey123 field app has built-in barcode capabilities, you can scan such a barcode. The contents would look something like this:

 

AAMVA

 

This JavaScript function formats the AAMVA string from a driver's license into a JSON object, which can then easily be used within XLSForm to extract the specific information you are looking for:

 

function DL2JSON (data) {
    var m = data.match(/^@\n\u001e\r(A....)(\d{6})(\d{2})(\d{2})(\d{2})/);
    if (!m) {
        return null;
    }

 

    var obj = {
        header: {
            IIN: m[2],
            AAMVAVersion: parseInt(m[3]),
            jurisdictionVersion: parseInt(m[4]),
            numberOfEntries: parseInt(m[5])
        }
    };

 

    for (var i = 0; i < obj.header.numberOfEntries; i++) {
        var offset = 21 + i * 10;
        m = data.substring(offset, offset + 10).match(/(.{2})(\d{4})(\d{4})/);
        var subfileType = m[1];
        var offset = parseInt(m[2]);
        var length = parseInt(m[3]);
        if (i === 0) {
          obj.files = [ subfileType ];
        } else {
          obj.files.push(subfileType);
        }
        obj[subfileType] = data.substring(offset + 2, offset + length - 1).split("\n").reduce(function (p, c) {
            p[c.substring(0,3)] = c.substring(3);
            return p;
        }, { } );
    }

 

    if (obj.DL) {
        ["DBA", "DBB", "DBD", "DDB", "DDC", "DDH", "DDI", "DDJ"].forEach(function (k) {
            if (!obj.DL[k]) return;
            m = obj.DL[k].match(/(\d{2})(\d{2})(\d{4})/);
            if (!m) return;
            obj.DL[k] = (new Date(m[3] + "-" + m[1] + "-" + m[2])).getTime();
        } );
    }

 

    return JSON.stringify(obj);
}

 

This is what the actual XLSForm would look like. Note that the myjson question uses pulldata("@javascript") to first convert the output from the barcode question into a JSON string. Then the pulldata("@json") function is used to extract specific attributes from the string.

 

typenamelabelcalculation
barcodeaamvaDL
calculatemyjsonJSONpulldata("@javascript","aamva.js","DL2JSON",${aamva})
textdnameNamepulldata("@json",${myjson},"DL.DAC")
textdlastLast namepulldata("@json",${myjson},"DL.DCS")
decimaldweightWeightpulldata("@json",${myjson},"DL.DAW")

 

Tip: Set the value of bind::esri:fieldType to null in the myjson question if you do not want to store the aamva raw string in your feature layer, but still be able to process it within your form logic.

                        

 

Working with repeats

 

Custom JavaScript functions are ideal for processing data in repeats. As of version 3.10, using repeats with custom JavaScript functions is limited to the Survey123 field app. You can retrieve all values for a question within a repeat, or retrieve all records within a repeat.

As of version 3.10, support for repeats in pulldata("@javascript") is limited to the Survey123 field app.

                              

Passing a question within a repeat to pulldata("@javascript")

 

When you pass a question within a repeat to pulldata("@javascript"), the JavaScript function receives an array of values for the specified question. For example, lets say we want to display a warning message if the user has introduced duplicate values in a question within a repeat. In this case, we want to create a JavaScript function that takes an array and returns true if duplicate values are found. Something like this:

function HasDups (myArray)
{
 return new Set(myArray).size !== myArray.length;
}

 

Now all we need to do is to call the function and pass the question within the repeat to it:

 

typenamelabelconstraintcalculation
begin repeatfruitsFruits
select_onefruitFruit${dups}=false
integerquantityQuantity
end repeat
hiddendupsDupspulldata("@javascript","myFunctions.js","HasDups",${fruit})

 

When passing a question within a repeat to pulldata("@javascript"), it is important to keep the pulldata("@javascript") outside the repeat. In the example above, note that I first keep the result of the duplicates check outside the repeat, and then I use that value in the constraint expression for the fruit question.

 

Another common scenario: Using a custom JavaScript function to retrieve the last value of a repeat.

 

typenamelabelcalculation
select_one conditioncurrent_condCurrent Conditionpulldata("@javascript","myFunctions.js","getLast",${cond})
begin repeatinspectionsInspections
dateinsp_dateInspection Date
select_one conditionconditionCondition
textcommentsComments
end repeat

 

And here the JavaScript function:

function getLast(questionInRepeat){

    return conditionsArray[questionInRepeat.length-1];

}

Passing a repeat to pulldata("@javascript")

 

You can also pass an entire repeat to pulldata("@javascript"). In this case, your JavaScript function will receive all records within the repeat as an array. Each item in the array is in turn another array representing the values for that record.

 

In our fruits example above, let's pretend we want to calculate how many bananas have been entered. If we pass the entire fruits repeat, we can use a JavaScript function to loop through every record. If the fruit in the record is banana, then we get the quantity value and add it to our total.

function totalBananas (fruits)
{
 var totalBananas = 0;
 var i;
 for (i = 0; i < fruits.length; i++) {
  if (fruits[i].fruit=='banana') {
     totalBananas = totalBananas + fruits[i].quantity;
  } }
 return totalBananas;
}

Here is the XLSForm:

 

typenamelabelcalculation
begin repeatfruitsFruits
select_onefruitFruit
integerquantityQuantity
end repeat
integerTotal Bananas

pulldata("@javascript","myFunctions.js","totalBananas",${fruits})

 

Working with web services

 

Using a custom JavaScript function, you can invoke an ArcGIS or third party web service. For example, say you want to query an existing ArcGIS feature layer and retrieve some attributes for the survey location. Or say you want to call a non-ArcGIS web service to retrieve some data. All of that is possible, as long as the user is online, of course.

 

The following JavaScript function takes a geopoint object and returns the first intersecting feature found in a polygon feature layer. The specific layer targeted in the example is a US ZIP code layer, but you can change the URL to use your own. The output of this function is a JSON representation of the feature. We will see shortly how you can use pulldata("@json") to work with such output.

 

function queryPolygon(location,fields,token,debugmode){

 

    if (location===""){
        return (debugmode? "Location Object is empty":"");
    }

 

    var featureLayer = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_ZIP_Codes_2016/FeatureServer/0";

 

    var coordsArray = location.split(" ");
    var coords = coordsArray[1] + "," + coordsArray[0]

 

    var xmlhttp = new XMLHttpRequest();
    var url = featureLayer + "/query?geometry=" + coords + "&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=" + fields + "&returnGeometry=false&returnCount=1&f=json"


    if (token){
        url = url + "&token=" + token;
    }

 

    xmlhttp.open("GET",url,false);
        xmlhttp.send();

 

    if (xmlhttp.status!==200){
        return (debugmode? xmlhttp.status:"");
    } else {
        var responseJSON=JSON.parse(xmlhttp.responseText)
        if (responseJSON.error){
            return (debugmode? JSON.stringify(responseJSON.error):"");
        } else {
            if (responseJSON.features[0]){
                return JSON.stringify(responseJSON.features[0]);
            }
            else{
                return (debugmode? "No Features Found":"");
            }
        }
    }
}

 

The XLSForm looks like this:

 

typenamelabelcalculationbind::esri:fieldLength
geopointlocationLocation
hiddenmyjsonJSONpulldata("@javascript","myJSFunctions.js","queryPolygon",string(${location}),"*","",true)10000
textzipZIPpulldata("@json",${myjson},"attributes.ZIP_CODE")
textplacenamePLACEMANEpulldata("@json",${myjson},"attributes.PLACENAME")

 

Note that a hidden question is first used to get the output from the JavaScript function. In general, it is best practice to keep a call to pulldata() in its own question. It makes your XLSForm easier to read and most importantly ensures that the Survey123 web app will handle it well.

 

The pulldata("@javascript") call includes multiple parameters this time:

 

  • First comes the location, which is enclosed by the string() XLSForm function. This is needed because JavaScript does not know how to handle XLSForm geopoint objects, but we can work easily with their string representations.
  • Then comes "*", to define the fields we want to retrieve from the query to the ArcGIS feature layer. 
  • An empty string for the ArcGIS token is passed, since the feature layer we are targeting is public. Using the pulldata("@property","token") function you could get the token from Survey123 and pass it in if needed.
  • The last parameter is used to show or hide debug messages.

 

The JSON output from a query to an ArcGIS feature layer can get lengthy. To avoid the output being cut off, it is best to use the bind::esri:fieldLength column and set its value to a big number. Say 10000 for example.

 

Finally, note that the pulldata("@json") function is used to extract the ZIP_CODE and PLACENAME attributes from the output of the JavaScript function.

 

More Samples

 

Survey123 Connect includes a new XLSForm sample illustrating how to use custom JavaScript functions in multiple scenarios. As you get hands-on, this is a sample worth checking.

 

Filter Blog

By date: By tag: