Skip navigation
All Places > ArcGIS Survey123 > Blog
1 2 3 Previous Next

ArcGIS Survey123

173 posts

A user has just filled out a form using a survey designed with ArcGIS Survey123. When they click the Submit button, what do they see? Is it a bunch of boring lines of text and a default green check mark? Or is it a custom branded, animated page that looks like you hired a team of developers to create? Let's dive into how you can take that Survey123 submission page to the next level, with this #InAGIF!

 

A check mark with a circle loading around it

 

With the latest version of Survey123, you can upload images to the submission page in the web application by selecting Design > Settings > and clicking the image button. You'll then see the option to upload an image to your survey. And it doesn't take specialized software to create the image above! It was actually created in PowerPoint, as outlined in the video below:

 

 

A video outlining how to create an animated .gif in PowerPoint using animations.

Using just PowerPoint animations and a basic screen capture software, you can create .gifs to add to Survey123

 

In this basic example, a circle and check mark were created in Microsoft PowerPoint. Then, animations were applied. Finally, the animation was played in slideshow mode, while a screen recording software captured the animation. If you have more advanced tools for .gif creation, you could use those, too!

 

This is a basic example. To really make things look great, make sure the animation matches your organization's theme colors and the colors of the survey. Additionally, set the .gif to only loop once, like in the example below (refresh this article--you may have missed it!). This ensures the animation doesn't repeat over-and-over again. 

Not moving? Refresh this article--you may have missed it!

 

You can pair this styling with some added functionality. For example, adding the ?autoRefresh=4 parameter to Survey123 will allow users to fill out the form, submit, see your image for 4 seconds, then the survey will refresh for the next submission.

Esri’s User Conference is the world’s largest GIS event – and this year it’s going virtual! With so many opportunities to connect and learn with industry experts and peers, why not take the time to learn?

 

Registration

 

Check the Registration Details | 2020 Esri User Conference page for more info. Registration is quick and open to everyone. Once registered, you will be given access to the UC Live website. In UC Live, you will be able to watch the plenary, sessions, visit the Expo and connect with peers and Esri staff.  Just like in San Diego, but from your home!

 

 

Here is a brief Survey123 guide to UC Live.

 

Sessions

 

 

Join sessions to learn about Survey123 product features and how to take advantage of them. Sessions are classified into Live Sessions and On Demand Sessions.  Live Sessions are scheduled. You may want to add them to your agenda so you do not miss them. Live Sessions always include a Q&A section with the presenters at the end.  On Demand sessions are made available for you to watch at any time during the conference.  I suggest you add them to your agenda as well, because there are quite a few. If you have questions after watching the recordings, bring them to the team at the Virtual Esri Showcase.

 

Live Sessions (Watch only at scheduled times):

 

 

On Demand Sessions (Watch anytime during the conference):

 

 

 

As you may know, Esri always publishes a selection of sessions for public access after the User Conference. However, do not count on that as not every session will be available beyond the conference.  I suggest you make room in your calendar during the week to make sure you do not miss sessions. Schedule them at the beginning of the week, so you can take your questions to the team at the Esri Showcase.

Tip: Watch on demand sessions early so you can take your questions to the team at the Showcase.

                    

 

 

Networking

 

 

The UC Live wesbite includes a Networking tab. Use it to connect with other attendees and Esri staff. You can connect with the Survey123 team and schedule private chats to resolve your questions. Here is the list of Survey123 team members that will be available during the week. Generally speaking, all of us can take questions on any aspect of Survey123, but the table highlights areas of focus. The table also includes a link to the profile of each member in UC Live so you can find us more easily in UC Live. In case of doubt: simply email survey123@esri.com.

 

Brett StokesSurvey123 Website Installer for ArcGIS EnterpriseEnglish
Calvin JungSurvey123 JS API, WebhooksEnglish, Chinese (Mandarin)
Ismael ChiviteSurvey123 Website, Reports, WebhooksEnglish, Spanish
James TedrickSurvey123 and ArcGIS Enterprise, XLSFormsEnglish
Jim MooreSurvey123 Documentation, Field App, ConnectEnglish
Jody Zheng LiuSurvey123 Reports and Web AppChinese (Mandarin), English
Marika VertzonisSurvey123 Documentation, Learning Paths, GNSSEnglish, Greek
Philip WilsonSurvey123 Field App, Connect, XLSFormsEnglish
Ruth Jiateng XuSurvey123 Web Accessibility, Website and Web AppChinese (Mandarin), English
Shwu-jing JengSurvey123 Internationalization, LocalizationChinese (Mandarin), English
Zhifang WangSurvey123 Website, Web App, ReportsChinese (Mandarin), English

 

The Survey123 Esri Showcase is a great place to network with other attendees and the Survey123 team. During the Esri Showcase hours, a chat room on Survey123 will be live. Join the conversation:

 

Monday, July 13, 2020 | 12:15 pm – 4:00 pm PDT

Tuesday, July 14, 2020 | 7:30 am – 9:40 am & 11:10 am – 3:50 pm PDT

Wednesday, July, 15, 2020 | 7:30 am – 9:40 am & 11:10 am – 3:50 pm PDT

 

Tip: Join the conversation at the Survey123 Esri Showcase and schedule private meetings to ask questions.

                    

 

 

Exhibitor Expo

 

 

Last but not least, you can also virtually visit many of our UC Exhibitors. Visit the Expo to connect with Esri partners with expertise on implementing, customizing, integrating Survey123, plus hardware vendors to run or complement Survey123 capabilities.

 

 

We are looking forward to see you this week!

We are happy to announce a new update to Survey123. This update only touches on the web components of Survey123 (Survey123 website, report services and the web app) and it is available in anticipation to our official 3.10 release, which will be available later in July, including updates to Survey123 Connect, the field app and the documentation.

 

The main driver for this early update is to bring to you a number of important fixes into the Survey123 web app, but since sometimes it is hard to decouple fixes from new features, you will find in this release some extra juice. One important note to make is that new features in this update are not officially documented. The documentation will come in just three weeks in late July, along with updates to other components of Survey123 like Connect and the field app.

 

Enough preamble, here are the highlights:

 

Survey123 Reports (Price reduction and increased capabilities)

 

Survey123 includes out of the box functionality to help you generate high quality documents from records submitted from the Survey123 web or field apps. This is extremely useful when you need to present your Survey123 data following strict formatting guidelines, for example when mimicking legacy paper forms or to comply with legal documents. If you are not familiar with Survey123 reports, check the Understanding Survey123 Feature Reports blog post and our Feature report templates—Survey123 for ArcGIS | Documentation help topic.

 

With this update, the price of this ArcGIS Online premium service drops from 2.5 credits to 0.5 credits per report. We are aware that this was an important aspect for many of you and we want to thank to all of you that took the time to discuss with Esri staff your use cases and reasoning behind your request. We also want to thank all your comments and community discussion at the Reduce Excessive Credit Cost of Survey123 Feature Reports ArcGIS idea thread.

 

Additionally, you can now try new expanded report template syntax, allowing you to include in your reports summary and statistics sections. This is a significant shift for the report capabilities and here is why: So far, the Survey123 report syntax allowed you to create 'feature reports', that is, a report representing a single survey record. Say for example you use Survey123 to perform routine asset inspections. When using feature reports, your reports include information about a single inspection: The date, status, comments, photos, a map of the location of the inspection and potentially data from related records such as all the incidents found. In feature reports, one report represents a single survey record.

 

Using the new summary section syntax in report templates, you can now create reports that include many survey records. For example, you could create a single report that includes all inspections ever performed, or all inspections in the last week. In a summary report, one report can include many survey records. Summary sections are generally shown as tables. In the following animation you can see a typical workflow where a summary section is used in a report to present a collection of survey records. The report is done against all water hydrants inspected in the past 18 days and it breaks down inspections in color coded tables (summary sections), one for each condition assessed.

 

Survey123 Summary Reports

 

Below is a still screenshot of the report. In it you will be able to appreciate that a small section is included at the beginning with some statistics: Number of hydrants inspected and hydrants that need maintenance. That is, of course, a statistics section, which is also part of the new report template syntax that this update includes.

 

Water Hydrant Summary Table

The new statistics and summary sections bring quite a bit of flexibility to your reports. Best of all, you can combine them all in a single report with a feature report section too. 

 

Back to the early discussion about the price, it will be worth clarifying how summary and statistics account for the price of your reports. Essentially, a report in Survey123, regardless of how many summary and statistic sections are included in it, will always cost 0.5 credits. In the event that you include additional feature report sections, the cost will increase at a rate of 0.5 credits per survey record included. For example:

 

Report includingArcGIS Online credits
1 feature report (one survey record)0.5 credits
1 summary section (as many survey records as you want)0.5 credits
4 summary sections (as shown above in the example)0.5 credits
1 feature report + n summary sections + n statistics sections0.5 credits
5 feature reports (5 survey records)0.5 * 5 = 2.5 credits

 

Photos and maps, can only be included within a feature report section.

      

To help you get started with the new report template syntax, we have added the capability to auto-generate sample report templates with summary and statistics sections as shown below. We will also be releasing a dedicated blog with details on this new syntax in the next few days.

 

 

Enhancements to Survey123 designer

 

Survey123 designer lets you visually create your own smart forms. With this update we are introducing the new Ranking question type. The Ranking question allows users to compare items within a list and sort them in order of preference. Based on the order selected, each item gets a numeric score.

 

Ranking Survey123

 

The main use cases for this type of functionality originate in online surveys. For this reason, this question type will not be initially supported in the Survey123 field app.

 

To avoid bias in responses, the ranking question can be configured to arrange the choices in the list randomly. This can easily be done right from within Survey123 designer.

 

Management view for ArcGIS administrators

 

If your account has administrative privileges in your ArcGIS organization, you will find a new 'Organization' tab in the Survey123 website. This new view, will let you easily find and manage any survey published in your organization. You will be able to update the surveys, change their sharing, etc.

 

 

 

Other fixes and enhancements

 

Last but not least comes a list of various fixes and other enhancements included in this update. It is a long list, and it includes work in very critical areas. As I described earlier in this blog, this is really the main driver for this update, to bring to you as quickly as possible the many fixes and enhancements listed here:

 

  • Web Accessibility: Support keyboard navigation in the Survey123 web app (except for ranking question type).
  • BUG-000131124 A user within a Portal for ArcGIS Organization with a username of 20 or more characters long of only numbers for example,12345678901234567890, is prompted with the following error message, "Unable to publish Details: For input string: "12345678901234567890" when publishing a survey in the Survey123 Web Designer".

  • BUG-000126461 Unable to generate a stakeholder view layer when the source of the survey is a hosted feature layer view.

  • BUG-000126792 Attributes in a field created in Survey123 Connect for ArcGIS 3.6.1.137 using the select_one question type that reference a list_name with True and False choices do not populate in Feature Reports exported from Survey123 for ArcGIS.

  • BUG-000127161 The Basemap Gallery does not honor the custom sorting settings configured in the Basemap Gallery settings of the organization when a survey is accessed from the Survey123 for ArcGIS website. ([Design, web app] Refine the map list for geo questions to respect org settings)

  • BUG-000129766 Public-facing survey's service URL exposes the survey's data, even if the survey's sharing settings are set to private. (Restrict permissions on public surveys)

  • BUG-000131590 Pasting an image in the note's description of Survey123 Web Designer fails to publish the survey, returns the error message, "Invalid protocol: data"

  • BUG-000130588 Survey123 for ArcGIS website fails to show the note in preview mode when a note includes '%' and returns the following error message, "Error Initializing Form - URIError URI malformed." (Percentage sign % in group description or note question which is inside group and page cannot be Previewed)

  • ENH-000123861 Create options for summary of data in report for survey123 ([Report] Support summary report or summary section inside a report)

  • BUG-000127719 [Data]Edit in Individual Response with calculation may change original value after loading

  • BUG-000122381 Unable to view the hosted feature layer of a survey in ArcMap, published to ArcGIS Enterprise from Survey123 website.

  • BUG-000130716 The owner is unable to view any data and receives the message, "An error occurred while loading the page. Some features may not work" in the Data tab in the Survey123 for ArcGIS website when choosing 'Only add new records' in the 'What can submitters do' section. ([Data] Error message "An error occurred while loading the page. Some features may not work." raised during loading the page due to lack of Query capability in the survey layer)

  • BUG-000130065 Individual response: map cannot display correctly when the survey has a geopoint question has a default map which the spatial reference is neither geographic (4326) nor web mercator (3857)

  • BUG-000108603 When adding a geopoint question to a survey using the Survey123 for ArcGIS web designer, it is possible to select a non-web mercator basemap for the question, even if the basemap is not compatible with the survey.
  • BUG-000105581 A Survey123 for ArcGIS survey created on survey123.arcgis.com web hub which includes geopoint question with a user defined home location does not zoom to the correct location in the Survey123 field app; instead it zooms to the 0,0 origin point. (On publish, write Survey123 App - compatible survey settings)

  • BUG-000109078 BUG-000110137 Default map of Geo Point question from website will not work on Survey123 app

  • BUG-000130365 Select_One question records the first choice clicked in a repeat, instead of the final choice selected (select_one in a repeat cannot reflect the selected status in UI as expected)

  • BUG-000130473 If a page does not have a label, any Single Choice question in it cannot work

  • BUG-000127417 With Integrated Windows Authentication (IWA) portals, the geopoint question in Survey123 for ArcGIS gets stuck in Loading state on Google Chrome, Mozilla Firefox and Internet Explorer browsers.

  • BUG-000125138 Signature attachments submitted via webform are not visible in AGOL

  • BUG-000131123 A user within a Portal for ArcGIS Organization with a username that is 20 or more characters long of only numbers (ex. 12345678901234567890) is prompted with the error message, "You cannot submit records to the survey since you are not Submitter or the Owner" when accessing a Survey123 form in the web.

  • BUG-000130565 When taking a survey in the web browser created in Survey123 Connect for ArcGIS and a question has the 'minimal' appearance chosen and 'readonly' set to yes, the user is still able to select an answer for the survey (Read only minimal questions can still take value)

  • BUG-000130090 Geopoint question with the 'read-only' parameter enabled does not capture the latitude or longitude when filling the survey through the Survey123 for ArcGIS web app. (Read-only behavior of locate in Geopoint question)

  • BUG-000127924 When a 'View' URL is configured from a Survey123 web form which has pages, it does not show the questions.

  • BUG-000126498 In Operations Dashboard for ArcGIS, an embedded web form fails to reflect edits performed on a geopoint structured using the relevant fields and calculations in an Excel form.

  • BUG-000125101 The error message, "Error Initializing form.... Failed to load data from" is returned when opening a survey in the Survey123 for ArcGIS website that has been configured with a JavaScript extension in Survey123 Connect to pull data from an existing feature service.

  • BUG-000124744 HTML markup codes appear at the start of the published survey in Survey123 for ArcGIS.

  • BUG-000128852 Survey123 feature reports fail to generate when feature layer name contains accented character (example: é)

  • BUG-000125498 The bit.ly link that is generated by Survey123 will generate a 404 error response when navigating through the browser intermittently.

  • BUG-000131376 Adding a new signature to a survey via web using the edit URL does not save the changes if using a mobile device.

  • BUG-000130958 In the Survey123 for ArcGIS web app, the today() function in the calculation column of an XLSX survey file does not return a value if it is a hidden field with an 'esri:field:type' set to DATE.

  • ENH-000123510 Send related record information to webhook providers.

 

Next steps

 

Officially, our 3.10 update is scheduled for July 23, 2020. On this date we will update Survey123 Connect, the field app and also include further work in the Survey123 website, web app and report services. We are furiously working towards having everything ready for you on that date. If you want to know what is coming, I encourage you to join our Survey123 Early Adopter Community. You will be able to download the Beta version of the software and provide feedback to the team. Additionally, we will share more information about the 3.10 release at the Esri User Conference.

Muscat Electricity Distribution Co. (MEDC) is implementing the Survey123 for ArcGIS as a transformation from paper-based to digital/smart-based in different activities such as Maintenance inspection for the Distribution Substation (DSS), Patrolling for the OHL, and Operation where the peak load for the DSS to be collected.

 

GIS Department designed the smart forms in housing and published them using ArcGIS Enterprise. After that, multiple users were created and divided into three groups. Each group was assigned Distribution substations of a separate zone. Then we designed web maps for each Zone with its feature class containing the DSS for each inspector and shared them to be used in Explorer for ArcGIS where the inspectors navigates to the substations and start collecting data by clicking on the URL scheme to pre-populate the main information of the assets inside the DSS based on GIS data.

 

 

 

The inspectors asked GIS department to find a way for changing the symbology of the DSS once it is done directly in Explorer for ArcGIS to avoid dual visiting. So, we added the feature layer of the Smart Form to the web maps for each Zone and changed the symbology of the geopoints to company's logo to differentiate between the visited substations and others then we set the layer to be refreshed intervally.

 

Here is the steps that we did:

 

* Xlsform:

1- Add "Geopoint" question type and set it as readonly to avoid any change of survey point.

 

*URL scheme:

1- Set the center of geopoint by pre-populated the coordinate of substation from URL scheme to ensure that the survey point will be not shifted due to accuracy from the substation point.

Understanding Survey123's custom URL Scheme 

&center={latitude},{longitude}

 

*Web Maps:

1- Add the feature layer of the form to a web map where the substations distributed to each inspectors.

2- Change the symbology of the layer to MEDC logo to illustrate the visited substation.

3- Set the Refresh Interval to 0.1 minutes to update the web map in Explorer for ArcGIS with the new records.

 

 

 

 

 

 

 

So, now the inspectors can see the substations that inspected in the Explorer for ArcGIS with the company's logo as you can see in the bellow video:

 

 

 

I hope that you will inspired with this BLOG.

Ismael Chivite James Tedrick

Thanks,

Hussam Al Jabri

The Survey123 Early Adopter Community (EAC) helps you access the latest Beta builds of the software. You can sign in with your existing Esri account and gain access to software downloads, documentation on upcoming features and discussion forums.

 

We have just updated EAC with new Beta versions of Survey123. You can test the Survey123 website, web app, field app and Survey123 Connect across all supported platforms. Below is a list of some of the Beta features available for testing:

 

As a general rule, we prefer feedback regarding our Beta releases through the Early Adopter Community Forums. We like to keep discussions in GeoNet for the released version of the software. Keeping things separate avoids potential confusion.

 

One question, many photos

 

Configure image questions in your Survey123 forms to allow end users to associate multiple photos with it. Below is a screenshot of Survey123 designer, showing the new options we added to give you more control.

 

 

If using Survey123 Connect, you can now apply the multiline appearance to your image questions to support capturing multiple photos. You can also use XLSForm functions such as count-selected() against image questions in your calculations, constraint and relevant columns. This allows you to do things like: store the photo count as a GIS attribute along with the record, force users to take a minimum and a maximum of photos, etc.

 

We want to make this feature available in our July update. Waiting for your last word! More info for Connect users here, and for designer here.

 

Map enhancements in Survey123 Connect

 

Survey123 Connect now lets you easily configure maps in your survey so you can use your own web maps, mobile map packages, offline map areas, etc. You can also use extended XLSForm syntax to control exactly what each of the maps in your survey will show. A new Linked Content section allows you to browser for existing maps in your organization, so end users of your survey can easily access them from the app.

 

 

All of this may already be somewhat familiar to you because the released software has this feature flagged as Beta.

 Your feedback is important now more than ever as this is ready to be shipping in July. Learn about this feature and more mapping enhancements here.

 

Survey123 organizational settings

 

A collection of Survey123 organizational settings can now be controlled by ArcGIS administrators. Use them to help users and Survey123 authors be more effective and bring consistency to your organization. You can access these settings from the Survey123 website when you are logged with a user with administration privileges.  As shown in the screenshot below, there are a number of settings available.

 


Summary reports

 

Do you wish to create a report template including a table for all records, or a selection set in your survey layer? Do you also want to add statistics for these records? Then it will be worth learning about the extended report template syntax.  Find all the details here.

 

Custom JavaScript functions and pulldata()

 

This is for advanced XLSForm ninjas only. Invoke a custom JavaScript function using the pulldata() XLSForm function. This allows you to model complex logic in JavaScript syntax that would be difficult to express in XLSForms (or not even possible). You can check for duplicate values in repeats, lookup values from web services, perform point in polygon queries and much more. 

 

While this capability has been available in the Early Adopter Program for quite some time, we are now aiming to release it in July 2020.  We made quite a few enhancements in Survey123 Connect to help you test your JavaScript functions and also enabled execution of your own code in the Survey123 web app too.  More info here.

 

Survey123 website installer

 

The Windows installer for the Survey123 website is virtually ready to go. This is for those of you who want to install the Survey123 website locally rather than having survey123.arcgis.com configured to work against your ArcGIS Enterprise. You can now test our release candidate before we officially make it available! Info here.

 

And much more...

 

There are many hidden gems available through the Early Adopter Program to test. You can find a more complete list of features for the Survey123 website here, and a list of other features for Connect and the field app here.  You will find that the Beta builds also address many bug fixes and other minor, yet important, enhancements you have requested via Esri Technical Support and GeoNet.

 

I am writing this blog post because I wanted to document a useful workflow that I developed for using Integromat to automate the creation of Feature Reports for Survey123 after editing the survey data.  As someone who had never used Integromat before, I spent a great deal of time researching the different intricacies of the Integromat modules and how to make them work for what I needed, as I couldn't find any examples that were quite the same as mine.  A lot of this workflow was accomplished by trial and error, so I'm posting this here in the event that someone else may find this example useful.  My particular difficulty in this project came when I attempted to process the automation differently when the survey was initially submitted (addData event type) vs. when it was edited (editData event type.)

 

My scenario is this:

 

I work in local government (city level) and we have continually been making services and applications available online as a convenience to our citizens.  As such, one item on our agenda was to make our Application for New Sewer Service available on the internet.  I created a survey in Survey123 for the purpose of allowing citizens to apply to our Sanitary Board for new sewer service (when you move to a new house and need to put the service in your name, or when you build a new house and need brand new service).  I also needed an easy way for our Sanitary Board staff to process these requests.  Creating an automated workflow with Integromat seemed like it would provide the perfect solution for automation, and paired with the power of Dashboards for ArcGIS, I think it did!

 

The Simple Workflow:

 

1) Citizen submits an application for new sewer service.

2) Sanitary Board staff receives the request.

3) Sanitary Board staff processes the request (they need to add some information to the form, such as new account number, deposit cost, date paid, etc.)

4) Microsoft Word application form is filled out with applicant’s information and filed in archive.

 

The Solution:

 

Workflow Item # 1 – Submitting the Application

 

To allow citizens to submit an application, I created a new survey in Survey123 Connect with all pertinent information included and published to our ArcGIS Online Organization.  This was the easy part.

 

Workflow Item # 2 – Receiving the Application

 

In order for the staff to access the information, I was going to train them on how to use the Survey123 online interface.  The problem with doing this is that they also need to have the ability to edit the data, which at the present time is only available to the survey owner or the individual survey submitter.  This was not going to work.  This is where I found out about embedding surveys in a dashboard Survey123 Tricks of the Trade: Embedding a survey in an ArcGIS Dashboard.  Even more importantly, embedding that survey into a dashboard in edit mode using URL parameters Survey123 Tricks of the Trade: Web form URL parameters (both great blog posts by Ismael Chivite).   This gave our staff the ability to go into the survey record and add data to the “office use only” fields (or change any other field that may have been entered incorrectly in the initial survey), including account number, deposit cost, date paid, etc.  Below is a screenshot of the dashboard with the editable survey form included:

 

 

I also wanted the staff to receive an email when a new record was submitted to avoid missing one or prevent a delay in processing, and this is the first use case for Integromat (I could have used Microsoft Power Automate (MS Flow), but I needed to run a feature report later, which at this time was not available in MS Power Automate).  I’ll post a screenshot of the Integromat Scenario a litte farther down.  I will also attach the blueprint exported from Integromat for those who might want to take a look. That takes care of workflow item #2 – the actual receipt of the application.  Moving on to processing.

 

Workflow Item #3 – Processing the Application

 

Using the dashboard with the editable survey form embedded, staff can now select the survey record (newest submissions come in on top of the list), review all the submitted information, add the new account number and other “office use only” information, then re-submit the now-complete survey form.  Now we need to get all this information onto the Microsoft Word Template that is the actual application form.  This is done using the “Create Feature Report” module in Integromat.  There was a little problem with this step, which I’ll explain a little further down when you can see the Integromat Scenario screenshot.

 

Workflow Item # 4 – Getting the Information onto the “paper” application

 

This item is accomplished using the Integromat “Create Feature Report” for Survey123 module https://support.integromat.com/hc/en-us/articles/360020842234-Survey123I then used the "Microsoft Office 365" module to send the Sanitary Board staff an email with the completed Feature Report attached. 

 

Integromat Scenario

 

Here is a screenshot of the Integromat Scenario:

 

 

Here’s an explanation of the scenario, step-by-step:

  1. Watch the survey for a submission using the “Survey 123 – Watch Survey” module
  2. The first router will send the workflow one way when a new record is submitted (using the addData condition) and the other way when a record is updated (using the editData condition). The top branch is the new submission and the bottom branch is the update (when the staff makes their edits).
    1. When a new survey record is submitted (again, top branch), the first module sends a confirmation email to the person who submitted the survey based upon the email they provided in the survey.
    2. Then the next router looks at the survey record and sends the workflow to one of four paths, depending on how many images were attached to the survey. This part was a bit tricky at first.  I initially had the “add photo” option set as a repeat in the survey, but it seems that repeats are difficult to handle in every aspect (and not supported by many ESRI tools and applications at this time, based on my research), so I simply removed the image repeat and modified the survey to only allow up to 3 images (3 separate “image” fields in the survey).  This router looks at the three image fields to determine if an image either exists for each field.  Based on what it finds, it continues along the appropriate path.  In my setup, the very top path is for surveys with no images, the second one down is for those with only 1 image, the third one down is for 2 images, and the fourth one down is for 3 images. 
    3. The images are retrieved using the “HTTP/Get a File” module. In the event that there is more than one file to retrieve, you can string multiple “Get a File” modules in line to accomplish this task, as you can see that I’ve done for those situations where more than 1 file is submitted with the survey.
    4. Last in this branch, I’ve attached the image(s) to an email that is sent to the Sanitary Board staff. This email serves 2 purposes – First, this is the initial notification that a citizen has submitted an application, and second, it provides the staff with the image attachments they will need to process the application.  This completes the initial submission of the application and concludes the automation of the first branch.  Now the staff processes the application.
  3. With all the information provided with the survey submission, the staff process the application (most of which is done is another computer system, which is where the account number is generated). Once they get all the information needed to complete the application, they open the dashboard I discussed previously and add the “office use only” information into the survey form.  When they hit “Submit”, the bottom branch of the scenario is triggered by the first router in the scenario (again, using the “editData” event type, which is accessed by clicking on the connector AFTER the router and applying the filter to look for “editData”.)
    1. (*Edit - read the comments below from Ismael Chivite - there is an easier way to set up for the Feature Report.  This is how I did it, but he describes a better way that I had not discovered at the time of writing this post.)  The first module on the bottom branch is the “HTTP/Make a Request” module. Theoretically, the next step would be the “Create Feature Report” module, but presently you cannot run the “Create Feature Report” module directly from the “editData” condition.  This has not been built into the tools yet, and it will not work.  I encountered most of my problems in this phase. Based on the research I conducted, only the edited attribute information will be included in the payload after the editData condition (not ALL of the attribute information for the feature; i.e. – only the field that was edited is available in the payload). In order to make the feature report work after an edit, you must first use the “HTTP/Make a Request” module to look up the hosted feature layer in AGOL, queried for the globalid of the current survey record (I also grabbed a few other fields that I used later in the process to assign a document name to my feature report).  Here is a screenshot of my HTTP request module:
    2. Then I used the “Parse JSON” tool. This effectively separates the data returned from the HTTP Request module into separate field names.   This tutorial helped me a lot:  https://youtu.be/QEUSzMadHdE
    3. Next is the “Create Feature Report” module (finally!!). This uses the globalId field that was parsed out from the JSON in the previous step. Basically, this provides the module the globalID for the feature it will use to generate the Feature Report. 
    4. Next is the “HTTP/Get a file” module to grab the completed Feature Report URL.
    5. Finally, I sent the email to the Sanitary Board staff email with the finalized Feature Report attached.

 

Now, here is the logical explanation:  When a new survey is submitted, a confirmation email is sent to the submitter, then an email is sent to the office staff to notify them of the new submission, including any image attachments submitted with the survey.  The office staff then processes the application and uses the custom Dashboard to edit the survey record to include additional information.  When they submit their edits, a Feature Report is created from the survey record and it attaches to an email and sends to the office staff.  

 I’m sure there are other ways to go about doing what I have done, but this is the way worked for me.  I could not find a good resource that explained how to run the “Create Feature Report” module after an “editData” condition, so if nothing else, I hope this helps to explain that process. I’m no programming master (by a long shot!).  Shoot, I’m not really even a novice.  But I do have to say that this Integromat integration is pretty easy to use.  Good stuff ESRI!

 

I've exported the blueprint for the scenario from Integromat and attached it to this post for reference.

 

You should also check out Getting Started with Survey123 and Integromat and Survey123 Tricks of the Trade: Integromat.  There is great information in both of these links.  Thanks!

By definition, a public survey is accessible to anyone who wants to submit data to it, but that does not mean that anyone should be able to look at the data itself. If your public Survey123 form contains sensitive information, you should configure your survey to prevent users in the public domain from downloading, querying or changing already submitted data. Unfortunately, it is not uncommon to find public surveys where the security configuration of the survey is not set  appropriately, allowing unauthorized access to the survey’s data. This article describes best practice for securing the data of surveys published in the Survey123 web designer. If you are interested in securing data for a public survey published with Survey123 Connect, refer to Securing data in public surveys (Survey123 Connect) .

 

If you are not familiar with the basics of public surveys, refer to Getting Started with Public Surveys.

                        

 

Sharing your survey publicly while keeping your data private

 

Technically speaking, you can control the sharing of your survey from the Survey123 website as well as from ArcGIS.com. The easiest and safest way to share your surveys is through the Survey123 website. Using the ArcGIS.com website is more error prone and can lead you to inadvertently share, and expose your data.

 

To share your survey publicly:

 

  • Sign in to the Survey123 website at survey123.arcgis.com.
  • From the survey gallery, open the Collaborate tab of your survey

  • The Submitter panel controls who can submit data to your survey. While in the Submitter panel, look for the section named 'Who can submit to this survey?' and check the Everyone (Public) option to share your survey publicly. 

 

If the option to share your survey publicly is missing, contact your ArcGIS administrator.

                        

  • Scroll down the page and look for the 'What can submitters do?' section. Check the 'Only add new records' option.
  • Click on Save at the bottom to persist all changes.

At this moment, your survey is shared publicly, allowing anyone to submit data through both the Survey123 web and field apps. You can get the link to your survey from the top of the Collaborate tab and distribute the link with your users. Since you have restricted access to 'Only add new records' in the Collaborate tab, it will not be possible to query, update, delete or download your survey data through the Survey123 web or field apps. Your survey's feature layer will also be secure, preventing any type of access (other than adding new records), from other Esri, third party apps or programmatic access.

 

Sharing your survey results privately for use within the Survey123 website

 

Your survey data is useful for people to make decisions, so at some point you will need to share that data with people who need it. Through the Collaborate tab, you can privately share this data with members of your ArcGIS organization so they can view, analyze and even download the data from the Survey123 website.

 

  • From the Collaborate tab of your survey, switch to the Viewer panel.
  • Look for the "Who can view results of this survey?" and check the groups within your organization that should have access to your survey's data.
  • Click on Save to persist changes.

Now that you have shared the results of your survey, users with access to the survey results will be able to look at the data from the Survey123 website using the Overview, Data and Analyze tabs of the Survey123 website. You can get the survey results link from the top of the Collaborate tab and distribute it within your organization or alternatively ask users to login into the survey123.arcgis.com website to see the survey results.

 

A deeper view into how all of this works

 

The Collaborate tab in the Survey123 website is meant to make the process for sharing and securing your data easy and error-free. Under the covers, sharing and access control to your survey data is managed through the use of ArcGIS feature layers and hosted feature layer views. These layers are saved in folder created in the ArcGIS account of the survey owner.  Next, we are going to look at these feature layer views in detail.

 

  • Log into the arcgis.com website and click on the My Content tab.
  • Look for your survey's folder in the Content tab. Note that Survey123 folders carry a Survey prefix followed by the name of your survey. It will look something like this:

Here is a brief explanation of the items in your survey directory:

 

  • A Form item: This ArcGIS item contains the definition of your survey with its questions, rules, look and feel and other properties. This item allows end-users to use your form from the Survey123 web or field apps.
  • A Hosted Feature Layer View with a "_fieldworker" suffix in its name. This item is created by the Survey123 web designer when the survey is first published. This item is used by the Survey123 web and field apps to submit data into ArcGIS. Permissions and sharing for this item are controlled via the Submitter panel in the Collaborate tab of the Survey123 website.
  • A Hosted Feature Layer View with a "_stakeholder" suffix in its name. This item is created by the Survey123 website when the survey results are shared through the Collaborate tab. This item is used to control access to the survey results through the Survey123 website.  If the Viewer panel of the Collaborate tab has not been used to share the survey results, this item will be missing.
  • A Hosted Feature Layer. This is where the actual data of your survey is stored. This item is created by the Survey123 web designer when the survey is published. You should never share this item.

 

The Survey123 website, through the Collaborate tab, manages the sharing and permissions set in each of these items. The website guarantees that the sharing across the items is consistent so the Survey123 website and apps work while keeping your data secure. Manually controlling the sharing of these items through the ArcGIS.com website can lead to inconsistencies and inadvertently expose your data.

 

  • The Form item is shared with all groups in the Submitter and Viewer panels of the Collaborate tab. Since the Form item simply describes questions and rules in your survey, it does not provide access to your data. If your survey is shared publicly for submits, this item will be shared publicly. If your survey is shared with specific groups in your organization for viewing results, this item will be shared with these groups as well.
  • The _fieldworker feature layer view is shared with users who need to submit data (submitter panel in the Collaborate tab). If your survey is shared publicly, this item will also be shared publicly. Access privileges in this item control how your data is accessed according to your choices in the Submitter panel of the Collaborate tab.
  • The _stakeholder view is shared with users who need to view survey results. Access privileges are controlled through the Viewer panel of the Collaborate tab.
  • The Hosted Feature Layer is kept private so only the owner of the survey has access to it. As long as there are _fieldworker and _stakeholder views, the Survey123 website and apps do not require direct access to this item. This item should always remain private to the owner of the survey.

 

Never share your survey feature layer. Keep your survey feature layer private and let the views do the sharing.

                        

 

For a more in-depth exploration of the specific security settings present in the _fieldworker and _stakeholder views, you can follow these steps:

 

  • From the ArcGIS.com Content panel, while looking at your survey's folder, click on the _fieldworker feature layer view.
  • Switch to the Settings tab and scroll down to explore all the permissions.

 

The most restrictive permissions in the _fieldworker view that enable submissions from a public survey while preventing access to your data are as follows:

 

SettingComments
EditingEnabled. Editing is required for the Survey123 web and field apps to submit data.
Enable SyncDisabled.
What kind of editing is allowed?Add enabled. Delete and Update disabled.
What features can editors see?Select this option: Editors can't see any features, even those they add
What access do anonymous editors (not signed in) have?Any option is fine since editors cannot see any features.
Export dataDisabled.

 

Sharing your survey results in web applications and dashboards

 

It is very common to build web mapping applications and dashboards on top of survey data. Enabling access to your survey data from these applications must be done with care, carefully controlling what data is shared and with whom.

 

The best way to enable access to your survey data by third party applications is by creating a new feature layer view on top of your survey's feature layer. By creating a new view, you can better control what data from your survey is shared and with whom, tailoring this to the needs of your third party application.

 

Using your survey's feature layer, fieldworker or stakeholder views to support third party applications is not recommended because in the future you may need to make adjustments to the sharing or permissions of these items to satisfy the needs of your third party application, and these changes can affect the normal behavior of your survey and compromising the security of your survey data.

 

Please read the previous paragraph again. Read it carefully so it sticks! 

 

This is how you can create a new view, for example, to support a web mapping application:

 

  • From your survey's folder in My Content, click on your survey's feature layer to open it's item details page.

 

  • Next click on Create View Layer.

Once your new view layer is created, you can control through the Settings dialog the permissions set on that layer. For example, you can disable editing and make it read-only. Through the Visualization tab, you can also use the feature layer view definition to choose which fields in your feature layer you want to expose.  It is also possible to apply filters to your view to hide certain rows, such as non-vetted submitted survey entries, etc. Finally, you can also share this new view layer according to the needs of your web application, which will likely be different from those of your survey.

 

For more information about working with feature layer views:

 

 

Do's and Don'ts

 

For surveys authored from the Survey123 web designer, the easiest and safest way to control the sharing of your survey and access to your survey results is through the Collaborate tab in the Survey123 website. It is recommended that you use the Collaborate tab for this purpose.

 

Altering the sharing and privileges on your survey items directly through the ArcGIS.com website is more error prone and can lead to a broken survey (for example, a survey that cannot access the _fieldworker view to submit data), or to a survey that exposes your data (through a misconfiguration of the sharing for the feature layer or its feature layer views).

 

It is not recommended that you alter the sharing or security properties of the survey form item or its corresponding feature layer and views. Let the Survey123 website do that for you.

 

Note: You should not need to read this last paragraph, because you read it twice already. In the event that you need to enable access to your survey data for third party applications, it is highly recommended that you create a new feature layer view on top of your survey's feature layer. It is not good practice to use the _fieldworker or _stakeholder views to support third party applications, because the sharing and access needed by your survey and the third party apps are likely very different.

By definition, a public survey is accessible to anyone who wants to submit data to it, but that does not mean that anyone should also be able to look at the data itself. If your public Survey123 form contains sensitive information, you should configure your survey to prevent users in the public domain from downloading, querying or changing already submitted data. Unfortunately, it is not uncommon to find public surveys where the security configuration of the survey is not set appropriately, allowing unauthorized access to the survey’s data. 

 

This article describes best practice for securing the data of public surveys published from Survey123 Connect. If you are interested in securing data for a public survey published with the Survey123 web designer, refer to Securing data in public surveys (Survey123 web designer) 

 

If you are not familiar with the basics of public surveys, refer to Getting Started with Public Surveys.

                      

A bit of context before we start

 

To properly secure your survey results it is important to understand first some basic concepts.  When you publish a survey using Survey123 Connect, a new folder is created in your ArcGIS account. This folder includes the name of your survey so you can easily find it.  Inside this folder, you will find a Form item and a Feature layer item:

 

  • Form item: The Form item contains the definition of the questionnaire presented to users: The labels of your questions, the calculations, media files and other resources needed to render your form.
  • Feature layer: The feature layer is the item where responses to your survey are stored.

 

In short, the survey folder contains one item (the form item) for the survey questions and one item (the feature layer) for the survey responses.

 

If you are working with sensitive data, you never want to share your surveys source feature layer. Instead, you will want to keep your survey feature layer private, and build feature layer views on top where you can better control the sharing and privilege properties. At the very least, you will want to create two feature layer views:

 

  • A view for the Survey123 web and field apps to use.  This view will allow the apps to add, and if appropriate to edit records in your feature layer.
  • A view for the Survey123 website to use. This view will control who can access the survey results through the Survey123 website, and with what privileges: just view, or also view and edit.

 

Additionally, you may want to create extra views to support other applications, such as ArcGIS Dashboards, Web AppBuilder apps, etc.

 

This article describes in detail how to build these feature layer views and associate them with your survey. If you are not familiar with the concept of feature layer views, I suggest read the Create hosted feature layer views—ArcGIS Online Help | Documentation help topic.

 

Do not create the views too early.

 

Let me put this upfront: as of version 3.9, Survey123 Connect does not like views: Connect does not create views, and does not handle them well when you delete or modify the survey. This is something that is going to change, rendering this whole article unnecessary, but for now bear with me.

 

As stated above, my recommendation is that you always use feature layer views when your survey is shared with people, but from a practical perspective you do not want to create the views too early. Survey design is an iterative process where you will be adding, changing and removing questions from your survey frequently. Some of these changes necessarily affect the schema of the surveys feature layer. If your survey is configured with views, Connect may not be able to change the schema of the source layer. If the schema of the layer is changed, your views will break.

 

For this reason, keep your survey without views for as long as you are working on it and configure the views when you are ready to put your survey in production, right before you share your survey with users.

 

Create a view for the Survey123 website first

 

I said before you will want to create at least two views: One for users who will look at your survey results through the Survey123 website, and another one for users to submit data through the Survey123 web and/or field apps. It is best to start with the view to control access to the survey results.

 

To build the view:

 

  • Login into the Survey123 website
  • Navigate to the Collaborate tab of your survey
  • Switch to the Viewer panel and hit Save.

 

 

 

If you return now to the Survey123 folder under Content in ArcGIS.com, you will notice that a new view has been created for your survey. This view has a 'stakeholder' suffix.

 

 

This new view will control who can use the Survey123 website to look at your survey results.  You will want to use the Viewer panel in the Survey123 website to control this. For example, say that users in a group called 'City of Cilantro' need to be able to look at the results of your survey, create reports and download data. Then you will go into the Collaborate tab, switch to the Viewer panel and share your survey results with that group. At that point, 'City of Cilantro' users can log into the Survey123 website and use the Overview, Data and Analyze tabs to do what they need. 

 

I would not recommend that you modify the sharing of this view through ArcGIS.com. For the Survey123 website to properly work, the sharing of the Form and stakeholder view items must be in sync.  The Collaborate tab in the Survey123 website takes care of that.

 

Create a view for the Survey123 web and field apps next

 

Configuring the view for the Survey123 web and field apps is a bit more involved. We need to create this view manually, then associate the view with the Survey123 Connect survey.

 

  • Log into the arcgis.com website and click on the My Content tab.
  • Click on the Form item to open its item details page, then click on Create View Layer. You can choose any title for your feature layer view.

To make your survey work against your own  feature layer view, you need to configure the submission_url and form_id XLSForm settings in your survey. This can be an error prone process at first. Once you are familiar with this I am sure you will do this with your eyes closed, but here I am going to follow a long but safe route:

 

  • In Survey123 Connect, from the survey gallery, click on New Survey and then choose the Feature Service option.
  • Look for the feature layer view you just created and give your new survey a throw-away name, such as temp or delete_me.

 

  • Open the XLSForm of your temporary new survey and switch to the settings worksheet. Then copy the values in the form_Id and submission_url cells into a text editor or a safe place, so we can paste them later into the original survey.

The submission_url value defines the feature layer (or feature layer view) that the survey is targeting. If empty, Survey123 Connect will create a new feature layer when you publish the survey. If a value is provided, the survey is published targeting the specified layer by the submission_url . The form_id value defines the sub-layer in your feature layer that drives the questions in your survey.

 

  • Back in Survey123 Connect go back to survey gallery, and open the survey that you want to make public.
  • Open the XLSForm, paste the submission_url and form_id values.
  • Save your XLSForm and publish your survey again.

 

The Publish dialog will indicate that your existing survey will be updated to use a custom feature service as specified by the submission URL, as shown in the next screenshot.

 

Now that your survey has been updated to target your own feature layer view, you can share your survey publicly with confidence. We will do that from the Survey123 website.

 

Sharing your survey publicly

 

  • Log into the Survey123 website at survey123.arcgis.com.
  • From the survey gallery, open the Collaborate tab of your survey

  • The Submitter panel controls who can submit data to your survey. While in the Submitter panel, look for the section named 'Who can submit to this survey?' and check the Everyone (Public) option to share your survey publicly. 

If the option to share your survey publicly is missing, contact your ArcGIS administrator.

                      

  • Scroll down the page and look for the 'What can submitters do?' section. Check if not already the 'Only add new records' option and click on Save at the bottom to persist all changes.

At this moment, your survey is shared publicly, allowing anyone to submit data through both the Survey123 web and field apps. You can get the link to your survey from the top of the Collaborate tab and distribute the link with your users. Since you have restricted access to 'Only add new records' in the Collaborate tab, it will not be possible to query, update, delete or download your survey data through the Survey123 web or field apps. Your survey's feature layer will also be secure, preventing any type of access (other than adding new records) from other Esri apps, third party apps or programmatic access.

 

If you go back to My Content in arcgis.com and check your survey folder, you will find that your feature layer view and the Form item are now shared publicly, while the feature layer remains shared only with you, the owner. This is the way you want it. Do not share the source feature layer if you want to keep your data safe.

 

Sharing your survey results in web applications and dashboards

 

The same technique we used to create a feature layer view for the Survey123 web and field apps can be replicated to support other apps and uses. It is not good practice to reuse the feature layer view we just created or to share the source feature layer. Build new views, restrict access to data as appropriate to the needs of the web app and share accordingly.

 

Here are a few links to learn more about feature layer views:

 

The coronavirus pandemic is front of mind for all of us. This crisis has changed the way we work and many in our community are having to adapt to new challenges and requirements in response to the COVID-19 disease. A key example is the increased demand for the collection and analysis of coronavirus-related data.


With that in mind, we have published a set of COVID-related templates in Survey123 Connect. These templates alone do not pretend to be an end-to-end solution for your COVID-19 needs. Like other community templates, the purpose is to provide practical examples of what you can do with Survey123 and demonstrate best practices for building smart forms with XLSForms.

Esri is offering a host of GIS resources and solutions to help you monitor and respond to the pandemic. This includes maps, applications and data. I encourage you to check out Esri's COVID-19 home page and COVID-19 GIS Hub.

It's also important to note that some of these samples are designed to collect personal information and health-related information. If your survey is to be shared publicly, you will need to secure your data and ensure that your data collection is compliant with the regulations in your region.

 

Let's start by taking a look at the samples. Below you will find a brief description of each template and the specific XLSForm techniques it highlights.

 

Community Support

Preview this sample in the Survey123 web app

 

Community Support survey thumbnailA survey form to help people connect with their community. Respondents can use this form to request support from their neighbours or offer help to others. This survey is designed as a single form that gathers both requests for help and offers of help. If required, you could split it into two separate surveys for requests and offers. The respective rows in the XLSForm have been highlighted in blue and orange. Delete the blue rows for one, and the orange rows for the other. You'll also need to remove the yellow row and the selected() function from the relevant column in each case.

 

This XLSForm sample demonstrates a technique to split out the responses to a select_multiple question into separate fields. A select_multiple question stores its answers as a comma-separated string. Using the selected() function you can record the choices individually in separate hidden fields. For more, see Understanding Multiple-Choice Questions in Survey123 for ArcGIS. This form also uses a regular expression to validate that an email address is formatted correctly. This expression is described in The art of hiding.

 

Testing Request

Preview this sample in the Survey123 web app

 

Testing Request survey thumbnailThis survey is intended to be completed by a health worker requesting a laboratory test for COVID-19. The clinician can collect information about the patient and the specimen type being submitted for analysis.

 

The XLSForm demonstrates how to validate that a date of birth matches an age (in years), and apply this check as a constraint. It also shows how to use the relevant column to control the visibility of questions on the form based on responses to other questions and how to apply the table-list appearance (or Single Choice Grid as it's called in the web app) to present a group of select_one questions in an easy-to-read table layout. For more information, see Survey123 Tricks of the Trade: Groups, Grids and Pages.

 

Inpatient Screening

Preview this sample in the Survey123 web app

 

Inpatient Screening survey thumbnailThis survey is an example of a form that could be completed by a health worker when a patient is admitted to a health facility. Collect personal information about the patient and details about any symptoms the patient is presenting with.

 

The example also uses table-list to display a block of select_one questions that each have the same choices. It also demonstrates how to use the string-length() function in the relevant column to check if an answer has been provided to a question, as well as a signature question to record a digital signature of the referring clinician. See the Signatures! blog for more.

 

Symptoms Check

Preview this sample in the Survey123 web app

 

Symptoms Check survey thumbnailThis survey provides a self-assessment of COVID-19 symptoms and is intended for use by the general public. The form could be useful for counties or cities in their efforts to measure the general impact of coronavirus infection. One of the key features of this survey is that it's in multiple languages! The XLSForm shows how to set out labels, hints and choices in English and Spanish. For more on this see Introducing Multiple Language Surveys. This sample was provided courtesy of Routt County, Colorado, as featured on the County's COVID-19 Information page.

 

If any of these templates is of interest, you can use them as a starting point for your own project. To download the templates, head to the Community samples section in Connect.

 

In Survey123 Connect, select New Survey. Select the Community option (1), enter a search for "COVID-19" or "coronavirus" (2) and then select a sample survey from the list (3).

 

Community samples in Survey123 Connect

 

Feel free to share with our Survey123 community your own COVID-19 XLSForms in a comment, below. I also encourage you to submit your coronavirus-related maps and apps with the greater GIS community here: Submit COVID-19 Maps & Apps | Support Response to Coronavirus Pandemic.

 

Banner image credit: NIAID.

Thumbnail images credit: PHIL and NIAID.

In this post you will find step by step instructions to help you embed a survey within an ArcGIS Dashboard. This is a commonly used used to support QA/QC and review workflows. The animation below illustrates what this could look like. In this dashboard, a list of mosquito spray exclusion requests is shown in the left panel. These requests are added through a separate online survey open to the public. A request review survey has been embedded in the right panel. As requests from the list are selected, the survey is automatically populated so the request can be reviewed and updated.

 

Embedded survey in a dashboard

 

The above example provides a compact user experience for browsing and updating existing data. This same idea can be applied to many workflows, where one survey is used to submit jobs or requests of some sort, and a dashboard with an embedded survey is used to review the incoming information.

 

If you would like to give the above sample application a go, you can try it live:

 

 

In this scenario, you need two surveys targeting the same feature layer. One survey is used to submit requests, and the other to review them. The surveys share a common set of questions, but they are not exactly the same: the request review survey, for example, has an extra section to approve or deny the request. Generally, the surveys are also shared differently: the one to submit requests is shared with a group of people, even with the public, whereas the survey to review requests is shared with a smaller group.

 

Assuming that you already have the survey you want to embed into your dashboard ready to go, and that you are somewhat familiar with ArcGIS Dashboards, here is a step by step guide to get you going:

 

  • Before we start, make sure your dashboard has a Map element and that the web map in it has a refresh rate set.
  • In your ArcGIS dashboard, add a List element and configure it to target your survey layer. You can apply a filter to this list in case there are survey records you do not want to show. In our example above, a filter could help us hide any request that has been already been approved and closed. You can also use the sorting options in the List element to present the most relevant records at top of the list.
  • Next, add an Embedded Content element.
    • In the Data Options panel, first set the Type to Features and target your survey feature layer.
    • Paste the URL of your survey web form into the URL property.
    • Set the Maximum Features Displayed property to 1.

Configuring embedded content element in the dashboard (1)

At this moment, a preview of your survey should be shown in the right panel. Next, we are going to modify the URL with some extra parameters to load content and adjust the look and feel. If you are not familiar with the Survey123 web app parameters, check out Survey123 Tricks of the Trade: Web form URL parameters and Survey123 Tricks of the Trade: Editing records in a web form 

 

  • Right at the end of the URL you just pasted, add the following:
    • ?mode=edit&globalId= If using a survey from ArcGIS Online
    • &mode=edit&globalId= If using a survey from ArcGIS Enterprise.
  • Use the fields collection to add the GlobalID variable into your URL.
  • Optionally, add the following parameters to hide the navigation bar and footer: &hide=footer,navbar

 

The following animation shows the last three steps.

 

Configuring embedded content element in the dashboard (2)

 

 

  • Save your changes and go back into the dashboard design.

 

At this moment you have the List, Map and Embedded Content elements in your dashboard, but they do not talk to each other. We are going to configure actions to make them work together.

 

  • Open the List element configuration dialog and add a new filter action targeting the Embedded Content element

 

 

  • Optionally, you can also configure actions in the List element to zoom to and flash the selected record.
  • From the design preview, select an element from your list and wait for the embedded survey to load the corresponding record. Now you can make changes to the record and submit!

 

Limitations

 

The filter action in the Embedded Content element can also be triggered from a selection in the map. However, it is not possible to configure your dashboard to trigger the filter from both the Map and List elements. That is, you need to choose either to load a survey from a selection in the list or from a selection in the map, but you cannot do both.

 

The Survey123 web app does not support editing surveys with repeats. You will get an error when attempting to initialize the form if it includes a repeat.

You can think of XLSForm repeats like sub-forms: A form within a form that can also be completed multiple times. Repeats are a very powerful feature in Survey123 because they can be configured in many different ways to support different business workflows. This article covers everything from the basics to the more advanced features of repeats. 

 

Some use cases

 

Let's first review some common scenarios that scream for a repeat:

 

  • In a door-to-door population survey, you will want to capture the location of the household and address, but also information about every member of the family. A repeat will help you model the form to be completed for each of the members of the household, including information about their name, age, gender, etc. The household survey will have a household member repeat in it, which will be completed for each person in the household.
  • In an asset inspection form you may want to capture information about each defect found. The defects repeat (or sub-form) will include questions to let you document each defect with its own photo, a description of what needs to be repaired and estimated cost of repair.
  • Repeats are also a great way to handle routine inspections. An asset form can include a repeat for the inspections: one form for the asset with its ID, location, etc and a sub-form (repeat) for every inspection ever made, with its date, issues found, etc. Since repeats can be nested, the inspection repeat form can also include its own repeat or sub-form for every defect found.

 

The basics

 

Repeats are supported through XLSForms via Survey123 Connect. If you are familiar with XLSForm groups, you have a lot of ground covered, because a repeat is really a type of group that lets you cycle through the questions in the group again and again.

 

To add a repeat to an XLSForm you need to enclose a set of questions within a begin repeat and end repeat set, as shown in this example:

 

typenamelabel
texthh_idHousehold ID
texthh_addressAddress
begin repeathh_membersHousehold Members
textmbr_nameName and last name
integermbr_ageAge
select_one gendermbr_genderGender
end repeat
select_one yes_noall_members_presentAll household members present?

 

In the survey above, the main body of the form is really about the household itself and is used to collect the household ID and address. The repeat block is all about household member information. We expect the enumerator to complete the Household Members repeat, or sub-form, once for each person in the household. The All household members present? question is outside the repeat, so it also belongs to the main form, but it will be presented right after the Household Members repeat.

 

Below is what the survey above would look like in the Connect preview. Note that the repeat appears as a common question group, except that at the bottom there are multiple options to navigate records within the repeat: a plus button to add a new record as well as next and back buttons (once you have more than one household member).

 

 

The user experience for repeats within the Survey123 web app is slightly different, presenting all the repeat records at once. You can navigate through them by scrolling up and down, as shown in the next animation.

 

Repeat records in the Survey123 web app are shown all at once

 

You can add one or more repeats to your survey. For example, in a school survey, you could include a repeat to document all classes in the school, and a separate repeat to gather information about teachers, etc. 

 

Understanding repeat data in your feature layer

 

Survey123 repeats are modeled in ArcGIS as related tables (or related layers if your repeat includes a geopoint, geoshape or geotrace question). In the example household survey above, the information about the household (id, address...) is kept in the main layer of a feature service, and the data from the household member repeat (name, age, gender) is modeled as a separate, but related table. The relationship between the tables/layers is kept through internally created global IDs.

 

If you would like to preview what your geodatabase schema looks like you can use the Schema Preview option in Connect, as shown in the animation below. Note that the name of the repeat in XLSForm becomes the name of the related table.

 

Survey123 Connect lets you preview the geodatabase schema of your survey

 

Using the Survey123 website, you can quickly explore data from repeats using the Data tab. The table will show records from the main layer of your survey as usual, and also extra tabs for every repeat in your form. You can propagate selections across the tabs for easier exploration of your data.

 

Use the Survey123 website to explore related records (repeats)

 

Repeat appearances (minimal and compact)

 

Through the appearance column in the XLSForm you can control how the repeat initially loads and appears in your form. By default, a repeat with no appearance value set is shown expanded, with one initial record showing. This can be good or bad. The good is that all questions within the repeat are ready for end-users to enter data right away. The bad is that if no data is entered, a new empty record will be added to your related table. I generally avoid using repeats with no appearance unless questions within the repeat are flagged as required.

 

If you want to avoid the repeat from having an initial record preloaded, use the minimal appearance. This will show your repeat group expanded, but with no records. To initialize data entry in the repeat, the end user will need to explicitly add a new record to the repeat by clicking the plus button.

 

The compact appearance simply collapses your repeat when the form initially loads. Of course, you can combine the minimal and compact appearances.

 

 

XLSForm expressions and repeats

 

XLSForm expressions allow you to bring sophisticated logic into your forms. Generally, XLSForm expressions are used to auto-calculate values (Calculations), define skip logic (Relevant), and to build data validation rules (Constraints). The XLSForm expression syntax for calculations in repeats is basically the same as with any other question in the form (more details at Formulas—Survey123 for ArcGIS | Documentation), but here are some important things to highlight.

 

When writing XLSForm expressions for a question within a repeat, you can reference other questions inside the repeat, but also questions outside! A common use is that where you want to bring data into your related table from the parent record. For example, in the example household survey you may want to store, along with every household member, their corresponding household ID. It would look something like this:

 

typenamelabelcalculation
texthh_idHousehold ID
texthh_addressAddress
begin repeathh_membersHousehold Members
hiddenparent_hh_idParent Household ID${hh_id}
textmbr_nameName and last name
integermbr_ageAge
select_one gendermbr_genderGender
end repeat
select_one yes_noall_members_presentAll household members present?

 

Note how the parent_hh_id question within the repeat is calculated to automatically fetch the value of the Household ID for that person. The Household ID is outside the repeat, but the calculation brings that value into the repeat record. This is a common use of calculations within repeats because it helps bringing more information into the repeat table that would otherwise require a join.

 

Styling

 

There are a few techniques you can use to style your repeat with custom colors and labels. This can be help users navigate your form more efficiently.

 

One technique is to dynamically set the label of your repeat to provide some context as to what information should be entered into the repeat. For example, in our household survey, you can include the address of the household in the header of the repeat. Instead of just reading 'Household Members', you can make it read 'Household Members at: <Address of the household comes here>. This is what is known as a dynamic label and it is described in more detail in the Understanding Dynamic Labels in Survey123 for ArcGIS blog post.  This is quite handy when working with long surveys, because it brings additional context for the person filling out the form. Here is what this would look like. Note how the label for the repeat is dynamically generated using a value from a question outside the repeat.

 

typenamelabel
...
texthh_addressAddress
begin repeathh_membersHousehold Members at ${hh_address}
...

 

You can also use colors to make your repeats stand out better within the form, like in the following screenshot. The repeat block uses a darker background color than the rest of the form, clearly separating questions within the repeat, from those outside.

 

The background and border colors of your repeat can be controlled through the body::esri:style column. In the example above, the vale in this column for the begin_repeat question is: backgroundColor='#cbcddb' borderColor='#494a4f'.  The color is expressed in hexadecimal format or HTML color name.  You will generally not want to use bright colors for you repeat backgrounds. Try to be subtle using slight variations of the background color of your form.

The body::esri:style color parameters are only honored by the Survey field app.

 

Aggregation functions (max,min, count and sum)

 

XLSForms support a handful of functions specially built to work with repeats. Specifically: count, sum, min, and max. They are all pretty self-explanatory. The design below shows the max and count functions in action.

 

typenamelabelcalculationbind::esri:fieldType
texthh_idHousehold ID
texthh_addressAddress
begin repeathh_membersHousehold Members
textmbr_nameName and last name
integermbr_ageAge
end repeat
hiddenmax_ageAge of oldest personmax(${mbr_age})esriFieldTypeInteger
hiddentotal_countTotal persons in housecount(${mbr_name})esriFieldTypeInteger

 

The count function can get a bit tricky as it will only consider in the count records with a value in the question it references. For this reason, it is best to use the count function against a question within the repeat that is flagged as required.

 

The sum question is also an interesting one in that it can sum not only numbers, but also text and even geopoint questions as well. If you sum text, it will concatenate all responses to your question within the repeat. If you sum on a geopoint question within the repeat, it will generate a geotrace object.

Check the Repeat Aggregation Survey123 Connect survey sample for an example using aggregation functions.

                            

 

Aggregation functions (join)

 

There is one more aggregate function that may be of interest: join. The join function is used to create a single list including all responses to a particular question within the repeat. Its syntax looks as follows:

join (",",${questioname})

The first parameter defines a separator. You can use a comma ",", a hyphen "-", or other character. The second parameter is the question within your repeat from which you want to create the list.

 

In our household survey example, we could use join to display a list of all people interviewed so far.

 

typenamelabelcalculation
texthh_idHousehold ID
texthh_addressAddress
begin repeathh_membersHousehold Members: ${interviews}
textmbr_nameName and last name
integermbr_ageAge
end repeat
hiddeninterviewsEvery person interviewedjoin(",",${mbr_name})

 

Note that the hidden question at the end uses the join function in the calculation column. Then the label in the begin repeat takes that value and displays it dynamically. You can see the effect in the next animation:

 

 

We can take join a bit further. Let's pretend we need to design a manhole inspection form. We want all six parts of the manhole to be inspected: the cover, chimney, cone, wall, bench and channel. We will use a repeat to document the inspection results of every component, and the join function to help us make sure all components have been inspected. Let's first have a look at what the form's behavior looks like:

 

 

Note that a checklist at the bottom of the form keeps track of the components inspected so far. When a new component is selected for inspection within the repeat, the value of the checklist is recalculated accordingly. This checklist at the bottom is set as read-only, so the user cannot manipulate it. A constraint in the checklist is also in place to avoid users from submitting the form unless all components are checked.

 

A simplified version of the XLSForm, highlighting the use of the join function is shown below:

 

typenamelabelcalculation
textmanhole_idManhole ID
begin repeatcomponents_groupComponents
select_one componentscomponentComponent
select_one conditionsconditionCondition
end repeat
select_multiple components
comps_inspectedComponents Inspected
join(",",${component})

 

To complete the XLSForm to mimic the behavior shown in the animation, you would also need to:

  • Set the comps_inspected question as read-only, to avoid users from manipulating the checklist manually.
  • Set the constraint of the comps_inspected question to count-selected(${components_tested})=6.

 

Repeat Count

 

If you want to control how many records must exist within a repeat, use the repeat_count XLSForm column. If you set the value to 2, then your repeat will be initialized with 2 empty records. If you set it to 5, it will contain 5, etc. You can also set the repeat_count dynamically as shown in the example below.

 

typenamelabelrequiredrepeat_count
texthh_idHousehold ID
texthh_addressAddress
integerhh_totalHow many people live in this house?
begin repeathh_membersHousehold Members${hh_total}
textmbr_nameName and last nameyes
integermbr_ageAgeyes
end repeat

 

The repeat_count column simply defines how many records are shown in the repeat. All records will be empty until the end user goes through every record to add data. Unless you have required questions within the repeat, Survey123 will allow you to submit records from the repeat with no data, and they will show as what they are: empty records. Generally speaking, you do not want to use repeat_count, unless you want to force people to submit a specific number of records in the repeat. If that is the case, you will want to add required fields within the repeat group. In the household example above, we first ask, "How many people live in this house?" We use that number to define the exact number of records in the household roster that must be completed. By making the questions within the repeat required, we guarantee that data is entered for every person in the house.

 

In cases where you want users to submit a number of records within a range, you will not want to use repeat_count. Instead, you will want to use constraints and the count function. For example, in an electric panel survey, you include a repeat to document all circuit breakers. Say that the number of circuit breakers is always between 5 and 20. This is what you would want to do:

 

typenamelabelconstraintcalculation
textcc_idCircuit Panel ID
begin repeatbreakersCircuit Breakers
select_one typebreaker_typeType
select_one statusbreaker_statusStatus
end repeat
integertotalTotal Breakers${total}> 4 and ${total}<21count(${breaker_type})

 

As described above, for the count function to work effectively, you will want to make the breaker_type question required.

 

Nested repeats

 

A nested repeat is a repeat within a repeat. For example, say you are doing a survey of a campground in a National Park. You want a survey for the campground itself (the name, the location of the entrance, etc). Within each campground you have campsites, so that gives you one repeat (location of the campsite, photo, size, etc). Then for each campsite you have equipment, which gives the second repeat (equipment type, condition, etc).

 

You can nest as many repeats as you want. That is, you can nest 3, 4 even 5 repeats if you like. Technically you could nest even more but for the sanity of your users avoid it whenever possible. 

 

Nested repeats are only supported in the Survey123 field app.

The Survey123 web app does not support nested repeats.

                          

Repeats in the Inbox

 

The Inbox is a powerful feature in the Survey123 field app, allowing you to edit existing GIS records in a feature layer. If you are not familiar with the Inbox, I strongly suggest you watch this short video tutorial.

 

 

By default, when GIS features are loaded into the Inbox, the repeat records will be empty. That is, the Survey123 field app does not fetch data from related records unless told otherwise. When updating an existing record from the Inbox in this way, you will be able to add new repeat records, but not view or update existing ones from the feature layer.

 

If you want to look at or update existing related records, you need to specify in your XLSForm what you want to download into the app, and for what purpose. This is all done through the bind::esri:parameters XLSForm column.

 

For example, let's pretend you are creating an asset inspection form and you want the complete history of inspections to be available in read-only mode. Then you would go with something like this:

 

typenamelabelbind::esri:parameterscalculation
textpanel_idElectric Panel ID
geopointlocationLocation
begin repeatcircuitsCircuit Breakersquery
datetimeinsp_dateInspection date
select_one statusstatusStatus
end repeat
integertotalTotal Breakers${total}> 4 and ${total}<21count(${breaker_type}

 

The query value in bind::esri:parameters will force the Survey123 app to download every related record, so all your inspections will show in the repeat of the asset form. The values supported in this column include:

 

  • query: Used to fetch related records and populate repeats. If query is not used, surveys from the Inbox will not display any repeat information from the existing feature. You can also control which records should be fetched, by defining a where statement for your query. For example: query="status='needs_repair'" will populate the repeat with all related records where the status is set to needs_repair. If no where statement is passed, the query parameter will fetch all related records.
  • allowUpdates: This parameter controls if the existing data in the repeat can be updated by the end user of the Survey123 field app or not. This is extremely useful because often you want end users to have read-only access to historical data (for example previous inspections of an asset) in the repeat, while allowing entering a new inspection to the repeat. allowUpdates by default is always false, but you can turn it on: allowUpdates=true.
  • allowAdds: By default this parameter is always true, allowing the end user to enter new records in the repeat. You can turn it off by passing allowAdds=false.

 

In the example below, our electric panel survey will display all existing circuit breakers ever recorded for that asset. It will also allow the end user to modify information from those previously recorded breakers because allowUpdates is set to true. The only exception will be the installation_date, which will be shown in the repeat as read-only.

 

typenamelabelbind::esri:parameterscalculationreadonly
textpanel_idElectric Panel ID
geopointlocationLocation
begin repeatbreakers Breakersquery allowUpdates=true
datetimeins_dateInstallation dateyes
datetimeinsp_dateInspection date
select_one statusstatusStatus
end repeat

Spatial analysis is a key component in GIS work, it allows us to understand the spatial relationship between our data and the world around us. ArcGIS Survey123 is a great resource to efficiently capture data either using the Web App as well as the Field App to take surveys. The Survey123 platform also provides tools to easily extract that data using Feature Reports. Survey123 Feature Reports which came out of beta in the 3.5 release of Survey123 is a great service to quickly consume data in a format that is defined and customized by the user. Survey123 Feature Reports are effective in understanding your data and responses obtained, but what about performing spatial analysis on your Survey123 results?

 

In this blog post, I will describe how to analyze your Survey123 results using the Business Analyst Online Reporting and Infographic Services to further understand your data and extract additional information that may not easily be apparent in your survey results. The Infographics or Reports obtained from Business Analyst Online can then be exported and used in larger applications. Infographics can be exported as PDF, an image, or Dynamic HTML that can be embedded into another website. Reports can be exported as PDF’s, Excel documents, or both. The example below shows the default Tapestry Segmentation report for an Area of Interest, although both Infographics and Reports are highly customizable to look how you like and can include a wide variety of available data that can be viewed from this data browser.

 

SampleInfographic

 

This blog will follow an example for city park inspections with the goal of utilizing ArcGIS Survey123 to provide a temporal system of record for the city’s parks that will update every so often tracking historical changes. Using the GIS data collected from the survey the example will further identify community factors around the parks. 

With the brainstorming help from James Tedrick and our conversation on the workflow, it seemed appropriate to create a little blog outlining the ideas discussed. I would also like to thank Ismael for his suggestions and feedback on the article I appreciate his time reviewing it and passing along his thoughts. 

 

Below is a workflow for using Survey123 results to run Business Analyst Online Reports and Infographics:

 

Once the park data was collected in the hosted feature layer since the GeoShape question type was used to outline the park boundaries, the service was pulled into a Web Map to define areas of interest surrounding the data. Unfortunately, Rings can only be added to center points in Business Analyst Online so the areas of interest needed to be specified using the Create Buffers tool in the Web Map’s Analysis tools.

 

WebMap with Buffers

 

A new Business Analyst Online project was created and the Web Map was imported into the project.

 

 

After pulling the Web Map into Business Analyst Online areas can be set up to be used in Reports or Infographics.

 

 

Once the areas are configured any Reports or Infographics that were created or shared with me can be run with my survey results.

 

Final Infographic

 

Getting started:

 

Just like Survey123, Business Analyst Online also has great resources to get started with creating a project and creating your first Reports and Infographics. As mentioned previously Infographics and Reports are highly customizable to meet your organization’s needs. Infographics and Reports can highlight different variables than configured in the default templates and really be customized to show the exact information your organization is looking for.

 

In more current events using the workflow above with the Esri demographics data can also help identify socioeconomic trends with the spread of COVID-19. Many organizations are making use of ArcGIS Survey123 to monitor resources and supplies, people, and assets. Esri has many great resources to leverage like the Coronavirus Response Website tutorial and Operations Dashboard to implement these surveys and make them widely available.

 

The geographic results of these projects can be further assessed using the tools present in Business Analyst Online. For example, the John Hopkins Coronavirus dashboard has recently implemented a U.S. Map section that utilizes the COVID-19 Status Reporting Infographic present in Business Analyst Online. 

  JohnHopkinsDashboard

 

John Hopkins University is using County polygons to run these reports, but the workflow outlined in this article can be used to make connections between your Survey123 results and the socio-economic factors around your data. Dashboards and Web Apps are great options to highlight those connections and shared across organizations.

 

Please follow the Survey123 Twitter feed to stay updated with examples from the community.

 

Supplemental information and potential use cases: 

 

https://www.esri.com/about/newsroom/blog/covid-19-pennsylvania-counties-assess-economic-fallout/?adumkts=product&aduc=social&adum=external&aduSF=twitter&utm_Source=social&aduca=dg_survey123_awareness&aduco=c19&adulb=multiple&adusn=multiple&aduat=webpage&adupt=lead_gen&sf_id=701f2000000iLMHAA2

 

https://www.esri.com/content/dam/esrisites/en-us/media/whitepaper/locating-covid19-testing-treatment-resource-distribution-sites.pdf?_lrsc=2555e919-e8d9-4906-8bbc-cacf124385fe&adumkts=social&aduc=social&adum=external&aduSF=twitter&adut=ea

 

https://htorpey.maps.arcgis.com/apps/opsdashboard/index.html#/1544144ccd6e4d4a8db71a8c74cc18b1 

Survey123 website links are a not so widely known. Through this article, I want to bring some visibility to this cool feature. You may already be familiar with the Survey123 field and web app linking capabilities. Links allow you to launch and pre-configure the apps with a single click. Survey123 website links are not much different, allowing you to create links to share with those who need to look at and analyze survey results, or pre-configuring the Survey123 website to target your own instance of ArcGIS Enterprise.

 

Analyze and Data Tab page links

 

The Analyze and Data tabs in the Survey123 website are a great way to explore and understand data submitted to your surveys. The Data tab lets you drill down into specific survey records while the Analyze tab lets you explore trends. Both tabs have plenty of options to help you tweak all sort of options. For example, in the Data tab you can control which basemap to use in the map, which features should be selected in the table view or what filters to apply. In the Analyze tab you can control which questions should be shown or hidden, what type of charts to use to summarize each question, etc.

 

Survey123 website links are a great way to take a snapshot of all these preferences you set and reuse them later. For your own use, or for someone else's!

 

If you look carefully, you will notice that as you work on your Data and Analyze tabs, the URL in your browser reflects your choices. In the screenshot below, for example, observe that the URL in the browser has a bunch of parameters specifying the currently selected basemap, map extent, filter and other properties in the Data tab.

 

 

What this essentially means is that you can now easily copy the URL, bookmark it for later use or even share it with other people that have viewer access to your survey. That is, in short, a Survey123 website link!

 

For your convenience, you can also grab the link to your survey123 page as shown below.

 

 

Survey123 website links are particularly useful with the Analyze tab. Your preferences to use one type of chart or another, hide or show specific questions or even your own filters will all be encapsulated in the page link. In this way, you can save bookmarks to easily return to your preferred survey results view.

 

Target your own ArcGIS Enterprise with the portalUrl query parameter

 

If you work with ArcGIS Enterprise, this is a must-have. Through the portalUrl query parameter you can define the target ArcGIS Enterprise instance that will be hit from the Survey123 website. For example:

https://survey123.arcgis.com/?portalUrl=https://host.domain.com/webadaptor/

In the URL Above, the host, domain, and webadaptor are replaced by information about your portal, allowing you to use the Survey123 website against your own ArcGIS Enterprise instance. 

 

While you can obviously bookmark the URL above to reuse it, it is much better to modify your ArcGIS Enterprise app launcher to include a shortcut to the Survey123 website. That way, anyone in your organization can easily access the Survey123 website without having to remember the syntax of the URL.

 

 

You will find step by step instructions to create your own Survey123 website shortcut in the app launcher of ArcGIS Enterprise in this Technical Support Article.

Hans Christian Andersen was born in Odense, near Copenhagen, Denmark, on April 2, 1805. He is famous for his fairy tales, such as "The Little Mermaid", "The Emperor's New Clothes", "The Princess and the Pea" and many others. Fairy tales are short fictional stories for children's entertainment. They generally involve animals, plants, forces of nature or folkloric characters such as elves, witches, fairies... fairy tales often have happy endings, but Andersen never took that very literally.

 

Coinciding with Andersen's birthday and International Children's Book Day, today we release Survey123 version 3.9. This update also has a touch of magic in it...

 

Survey update notifications in the Survey123 field app

 

Many of you have contributed with your comments and voted up ArcGIS Ideas from Mike Bruening and James Botterill on survey update notifications. So far, these are among the most popular of all! 

 

With this update, the Survey123 field app will let you know if a new version of a survey on the device is available for download. This check happens automatically when the application starts, or when a new user signs in to the app. You can also manually trigger the check by simply dragging down on the survey gallery.

 

Survey update notifications will appear after you re-publish a survey. For example, if you add additional choices to a list, fix a typo on a label, add new questions or adjust calculations, etc.

 

As of this release, it is up to the end user of the app to decide if and when a survey update should be downloaded. We are aware that many of you would like to force survey updates in some cases and this is something we are working on implementing in a future release.

 

We trust this new feature will streamline much of your field work out there!

 

 

New Map question in the Survey123 web designer (line/polygon support added)

 

With this release, we have replaced the geopoint question type in the Survey123 web designer with a new Map question type. The Map question is useful when you want end users to provide the location of an event, just like you did with the geopoint question, but it also supports line and area modes.

 

Survey123 designer now includes a new map question type

 

In the screenshot above, for example, the Map question in the form is configured to let end users draw an area (polygon), instead of a single location (point). The new Map question type works well in the Survey123 web and field apps and features vertex-by-vertex and freehand drawing tools.

 

Since the ArcGIS data model is limited to one geometry field per layer, it is only possible to add a single Map question to a form. Additionally, once a survey is published, it is no longer possible to switch the type of geometry in the Map question. That is, you cannot for example switch from line to area. It is possible to change the drawing tool mode from freehand to vertex-by-vertex, but not the geometry type. If you ever need to make such a change, you can save a new copy of your survey and change the geometry type before publishing your new survey.

 

We want to thank all of you who provided feedback through the Early Adopter Program and our Holistic Testing sessions during the development of this new question type. In particular to Charlie FitzpatrickJoseph Kerski and Education colleagues.

 

Custom Survey123 feature report filenames

 

Many of you have requested more control over the name of the output files created by the Survey123 feature report service. You can now include a question placeholder in the output report file name that you pass into the service. This placeholder value will be dynamically replaced when the report is generated.

 

In the screenshot below for example, you can see that the name of the output report file generated includes the household id value from the survey record.

 

Custom report file names (Survey123 report service)

You can use question placeholders when defining the report output filename in the Survey123 website, or from the Integromat module. The placeholder looks as follows: ${question_name}. For example, below I set the placeholder to use the value from the field hhid (Household ID). You can combine if you wish multiple placeholders.

 

 

New Survey123 web app JavaScript API

 

The Survey123 web app JavaScript API is designed to help web developers more easily embed, style and interact with live Survey123 smart forms within their applications. It is a simple, yet powerful way to integrate Survey123 within larger business workflows. Through this API, you can choose at runtime what survey you want to display and how it will fit within your web application. You can bidirectionally send messages between your form and the web application. To learn more about this API check the Introducing the Survey123 Web App JavaScript API blog post.

 

Survey123 web app Draft mode

 

In the Survey123 website, if you visit the Collaborate tab, you will find a new Draft mode section. If you choose to use the draft mode, data entered through the Survey123 web app (from a web browser) will be stored locally until your survey is sent or cleared. This is useful for long surveys where people may choose to work on your form for a while, and then come back to it later after having closed the browser. Data will not be lost even if the end user navigates away from the survey or closes the browser; when they go back to your survey URL, all the entered data will be there until submitted.

You will want to turn on this option selectively, as this could compromise the privacy of entered data if used from a shared computer. For example, if someone is working on a form with sensitive information and draft mode is enabled, it is possible that data could be compromised if that person forgets to submit or does not reset the data in the form. Anyone loading the survey URL at a later time from that shared computer will see the data.

 

Draft mode is only available in surveys published with version 3.9 or above.

 

When draft mode is on, a link to reset the draft will be shown at the top, as illustrated in the screenshot below.

Other fixes and enhancements

 

Whilst the new features above are important, many of the fixes and enhancements that follow are just as relevant. I will highlight here a few that could easily get lost amongst the list below:

 

  • As anticipated in our earlier Upcoming changes to Survey123 web form's query parameters announcement, the mode query URL parameter in the Survey123 web app now supports the use of globalIds.  To facilitate migration of your existing work, we have extended the life of the objectId parameter in 3.9.

 

VersionobjectIdglobalIdComments
3.8 and earlier versionsSupportedNot supported
3.9SupportedSupportedUse this version to migrate!
3.10 and beyondNot supportedSupported

 

  • We very strongly recommend that you transition away from objectIds as the days for them are counted!  With 3.10 we will completely drop to support and exclusively use globalds.
  • In the Survey123 field app, you will notice that the sign in workflow has been revised. It features a cleaner, more informative and easier to use UX. This was part of a larger effort to accommodate random sign out issues and to incorporate multiple enhancement requests to facilitate login/logout workflows. The UX for connecting the app to your own ArcGIS Enterprise portal has also been revised.
  • In the Survey123 website, the Analyze tab now includes a much improved user experience for navigating long forms.
  • If you work with XLSForms, you should also note that starting with this release, select_multiple questions now support calculations.
  • If PKI authentication is of interest, on top of SAML PKI support, the Survey123 field app now also supports PKI authentication from your ArcGIS Enterprise web adaptor.
  • For Windows users: You can also now download the Survey123 app and Connect directly from the Windows Store.

 

Survey123 field app and Connect

 

  • Never get randomly signed-out again: Multiple fixes have been applied to accommodate scenarios where the Survey123 field app would randomly sign users out: BUG-000128933
  • Enhanced PKI authentication support: While support for PKI through SAML has been available in Survey123 for a while, this update brings new enhancements to support PKI authentication at the ArcGIS Enterprise Web Adaptor level. This provides additional flexibility to deploy Survey123 in environments that adhere to this standard. For more information regarding PKI support in Survey123, check this help topic.
  • Windows Store: The Windows 64-bit and 32-bit setup files of the Survey123 field app and Connect can be found from our Survey123 download page. Additionally, starting with this release you can also download Survey123 Connect and the Survey123 app directly from the Windows Store.
  • Addressed multiple issues related to double tap sensitivity: BUG-000124309BUG-000125208BUG-000127278BUG-000109661.
  • Split View on Apple devices: You can now arrange the Survey123 field app in iOS split view.
  • BUG-000125609 ArcGIS Online allows the organization short name to include uppercase characters leading to case sensitive related errors when using the organizations URL.
  • BUG-000127518 Creating a form in Survey123 for ArcGIS with a geopoint question type and esriFieldTypePointZ field type does not allow the feature geometry to update in ArcGIS Online Map Viewer.
  • BUG-000127816 The surveys displayed is changed when multiple languages are set up in the survey.
  • ENH-000125365 Have Survey123 honor the "Remember Me" functionality when using a IWA login from Portal.
  • ENH-000105906 Add functionality for Survey 123 Connect to have a "remember me" option for usernames.
  • ENH-000121154 Support Trimble Rx GPS receivers in Survey123 on iOS devices.
  • BUG-000122130 One page will be automatically added when collecting the survey in the survey123 app created from survey123 web designer with more than one page.


Survey123 website, web app and report services

 

  • DE-000003535,BUG-000126960 An error is returned when trying to generate a feature report in the Survey123 for ArcGIS website for a survey published using the 'Feature Service' option.
  • BUG-000128390 Surveys created and accessed through the Survey123 for ArcGIS website returns the error message, "Survey does not exist or is not accessible" when special characters exist in question or choice labels.
  • BUG-000128110 GeoPoint question's map for the surveys created using Survey123 web designer (after the recent update) does not appear in Survey123 field app (on both desktop and mobile devices).
  • BUG-000126008 After removing a single choice grid from a group, republishing the survey, and adding it back into the group, any changes made to the single choice grid questions are given identical, generic schema names preventing the user from republishing the survey
  • BUG-000127630 In Survey123 for ArcGIS, when a survey has a geotrace or geoshape question type, the map scale setting is not honored when including a map in the feature report
  • BUG-000126425 Boolean expressions do not work in the Survey123 for ArcGIS web app
  • BUG-000128085 In the Survey123 for ArcGIS website, images in a Note element cause the survey to fail to publish if they are on the same row separated by a space
  • BUG-000128548 The background set for a survey is displayed as distorted in the web form if the “style settings” is set to “pages” and “appearance” for groups is set to “field list”
  • BUG-000124744 HTML markup codes appear at the start of the published survey in Survey123 for ArcGIS
  • BUG-000116598 Survey123 for ArcGIS error 'Privileges of stakeholder role are required to access this page. You're currently in field worker role.' when accessing the survey..
  • BUG-000117843 When using the em dash 'ー' (UTF-8 Enconded \xE3\x83\xBC) in a single line text question, the words are broken up into separate responses in the wordcloud section of the Analyze tab
  • BUG-000125151 The Survey123 for ArcGIS Website does not retain the Layout Element settings (Header and Footer Settings) for a survey if the Survey has been published through Survey123 Connect
  • BUG-000111740 The Survey123 website returns the 404 error message in network traffic when loading a survey in a web browser
  • BUG-000126848 Viewer and Editor roles with the 'feature report' privilege enabled by default are unable to generate a feature report in Survey123 for ArcGIS as the 'create, update, delete content' privilege is also required.
  • BUG-000122896 Surver123 for ArcGIS does not provide a character count on text questions with repeats. 
  • BUG-000129358 Some organizations are unable to publish any surveys in the Survey123 for ArcGIS web app
  • BUG-000125046 A geopoint location is rendered as an empty map image in the exported report from the Survey123 for ArcGIS website when the survey is created from an existing feature service.

 

Documentation and templates

 

  • BUG-000128228 Unlisted built-in (reserved) geodatabase field names cause the publishing error with Survey123 for ArcGIS that is returned when using a reserved keyword for a field name, "Error: Dataset not found. Code: 500. Publishing failed."
  • ENH-000127952 Displaying the 'name' field instead of the 'label' field for select_one type questions in Survey123 reports
  • ENH-000128878 Survey123 - Documentation - orderBy Parameter - is missing of examples, case application and a more detailed description for the function
  • ENH-000128477 Improve documentation for Repeats in Survey123 to contain information on the abilities and limitations of nested repeats
  • ENH-000126920 Currently the text for when Configuring Survey123 with a feature service published to ArcGIS...
  • ENH-000127608 Please update Product Life Cycle page for Survey123 to indicate Classic was 2.9 and below and is now retired as of a certain date

 

Next steps

 

Survey123 3.10 is already in the making. You can access the latest builds from the Early Adopter Community. Our focus is aimed towards a few critical aspects:

 

Survey123 field app fix-only update for iOS (for release before end of April 2020):

 

  • Specifically for iOS, and for specific surveys, you have observed consistent crashes in the Survey123 app. These issues are currently being worked on and we are aiming at releasing an update for iOS to address these issues as soon as possible. BUG-000111086,DE-000003544, BUG-000108085,BUG-000128201,DE-000003543, BUG-000125015,DE-000003368, BUG-000126685. Beta builds with fixes to these issues will be shared through the Early Adopter Community as soon as they are ready.

 

Survey123 3.10:

 

  • Mapping enhancements in the Survey123 field app: for quite some time now we have been shipping the Survey123 field app with a Beta feature that lets you bring your own web maps, vector and mobile map packages into the map. We are now finalizing this work, which should be fully supported in the 3.10 release.
  • The Survey123 feature report service is getting ready to see its first major feature update since release. We are working on supporting summary reports where you can bring all or a subset of features in your survey into a single report. As part of this effort, we are also adding new syntax to support statistics within reports.
  • Ranking question: we are working on a new ranking type of question to help you define sortable lists within a form. With the ranking question, end users will be able to express preferences over a predefined list of choices: drag and drop choices to set their order!
  • Finalizing the on-premises setup of the Survey123 website and API.
  • Improving web accessibility in the Survey123 web app.
  • Support for ArcGIS Enterprise in the Microsoft Automate connector.

 

A complete list of Beta features is available in the Early Adopter Community, as well as user forums and documentation. If you are interested, have a look!

The Survey123 web app JavaScript API is designed to help you embed, style and interact with Survey123 smart forms within your own web applications. At a glance, here is what you can do with this API and a little bit of JavaScript magic:

 

  • Programmatically embed a Survey123 web form within a web page at run-time.
  • Apply a custom css to the embedded web form to make it look fit within your own web app.
  • Programmatically read and write values into the embedded web form from your own web application.
  • Subscribe to web form events such as onFormLoaded, onFormSubmitted or onValueChanged.

 

There are many applications for this new API. In the animation below, for example, a form is embedded within a web page used to report the speed of your internet connection. When the page is initially loaded, a big button is shown to help users initiate a quick internet speed test. One the connection speed is estimated, a Survey123 web form is loaded and the output of the speed test is automatically added into the form. At that point, the end user can complete the remaining questions and submit. The whole idea with this is that the logic to measure the internet speed of your connection sits in your web application, but when the time comes to submit data like your location, email contact and internet speed a Survey123 form is used for that. Through the Survey123 web app JavaScript API you can make your web app talk to the form and load the measured internet speed right away to make the process simpler.

 

Thanks to the Applications Prototype Lab for sharing the above example and making its source code available in GitHub!

                          

You may also want to leverage the Web App JavaScript API to bring Survey123 forms into existing websites. Of course, you can always embed your survey by copying and pasting an embed link, but using the Web App API has the advantage that you can make your form interact with the website and vice-versa. For example, say you want to embed in the website of your city a form to capture incidents or issues that need attention. You can pre-populate certain questions in the form using information gathered from your own website. Similarly, you can feed your website with information entered by the user in the Survey123 while the form is being completed, or when the data is finally sent.

 

 

Getting Started (Hello World)

 

The following is about the simplest code snippet showing the basics of the Survey123 Web App JavaScript API. This sample loads a custom web form into a web page and pre-populates a couple of questions in it.

 

 

Lets have a closer look at the code:

 

  • Line 2: In this line we import the Survey123 web app JavaScript API. The address of the latest version of the API is http://survey123.arcgis.com/api/jsapi 
  • Line 5: Your web form needs a container in your web page. Typically, you will want to use a DIV HTML element. You can control the exact size of the the container in your page, although keep in mind that you cannot make it too small or otherwise your web form will not have room to display.
  • Lines 7-14: This is where we create a Survey123WebForm JavaScript object. The constructor requires at least the following attributes:
    • clientId: The client ID is a string that proves that you have explicitly authorized the use of Survey123 web app API from your web page. You need to create the Client ID through the https://developers.arcgis.com/ website. Check the Generating a Client ID section later in this article for details.
    • container: This is the HTML element in which you want your web form to be displayed. Typically a DIV.
    • itemID: This is the ArcGIS itemID of your web form. Check the Getting the ItemID of a web form section later in this article for details.
    • token: This attribute is only needed if you are targeting a private survey.

There are a number of optional attributes you can also set. In the example above, we added the defaultQuestionValue attribute to set the default value of a couple of questions.  Check the Web Form attributes section later in this document for a complete list.

 

Generating a Client ID

 

To authorize the use of the Survey123 web app JavaScript API within your web application, you must provide a valid Client ID. You can create a Client ID through ArcGIS for Developers  as follows:

 

  1. Login into ArcGIS for Developers and open the Dashboard.
  2. Create a New Application and switch to the Authentication tab
  3. Add your web application URL and/or domain to the list of Redirect URIs.
  4. Copy the Client ID.

 

 

Getting the ItemID of a Web Form

 

ItemIDs uniquely identify ArcGIS items within your organization. You can find more information about itemIDs in the Where can I find the item ID for an ArcGIS Online item? article. To get the ItemID of your web form:

 

  1. Login to Survey123.arcgis.com.
  2. Open the Overview or Design tab of your survey
  3. The portion in the URL highlighted in the screenshot below is the itemID.

 

 

 

More details (Web Form attributes)

 

Here is the list of all attributes supported by the Web Form object.

 

PropertyDescription
containerThe HTML element that will contain the web form, typically a DIV.
clientIdA valid Client ID for your domain registered in ArcGIS for Developers
itemIdThe ItemId of the web form you want to load.
portalUrl(Optional) The URL of your ArcGIS portal. If left empty, defaults to https://www.arcgis.com
tokenRequired if you work with private surveys.
hideElements

(Optional) Elements can be set to be hidden, including navbar, theme, header, subHeader.

    For example: ["navbar","header","subheader"]

You can also hide questions within your survey. For example:

    For example: ['field:yourQuestionName']

autoRefresh(Optional) Enable auto refresh the survey after submit successfully. You can set autoRefresh=3 which will refresh the survey after 3 second
defaultQuestionValue(Optional) Lets you populate questions in the form. For example: {field_0: 'value1', field_1: 'value2'}
isDisabledSubmitToFeatureService(Optional) Set this property to true and the web form will not send data to your feature service.
onFormLoaded(Optional) Invokes a callback function when loaded. For example: function({form:Form, contentHeight: number })   
onFormResized(Optional)
onFormSubmitted(Optional) Invokes a callback function when the form is submitted. For example: function({surveyFeatureSet: SurveyFeatureSet})
onQuestionValueChanged(Optional) Invokes a callback function when values in your form change. For example: function({field: string; value: any; path: string; repeatIndex: number; formId: string})
width(Optional) Takes a number in pixels. Controls the width of the survey although anything smaller than 660 will be ignored.


 

More details (Web Form methods)

 

Web Form methods allow you to set the value of questions within your form from a JavaScript function.  You can also use them to programmatically change the style of your form.

 

MethodDescription
.setQuestionValue

Used to set the value of a question, or questions, at run-time. For example:

 

webform.setQuestionValue({
  'field_1': 'test1',
  'field_2': 'test2'
});

.setGeopoint

Used to center the map and set the geopoint value to a given location. For example:

 

webform.setGeopoint({

   x=-117.34,

   y=43.78

});

 

It is commonly used in combination with the Geolocation API.

.setStyle

Used to apply CSS styling to your web form. For example:

 

webform.setStyle({
  '& .question-label': {
     'color': '#ff0000 !important',
     'font-size': '30px !important'
  },
  '& .form-header': {
     'color': '#ff0000 !important'
  }
});

 

Samples

 

  • Hello World: A bare bones sample showing how to embed a web form within a web page.
  • Speed Test: A more elaborate sample written by the Esri Geo Experience Center’s Applications Prototype Lab. It integrates a simple routine to estimate internet speed connection and then uses that estimation to pre-populate a question in a web form.

Filter Blog

By date: By tag: