Introduction to ArcGIS Survey123 for Developers

ZacharySutherby · ‎09-30-2021

ArcGIS Survey123 provides a number of tools for you to customize your workflow and meet the specific requirements for your projects. Tools such as custom JavaScript functions, the Survey123 web app JavaScript API, Report REST API, creating custom functionality, Python tools, and so much more are all readily available for you to make use of and extend the capabilities of ArcGIS Survey123 to meet your project goals. These tools are constantly being updated and developed to accommodate more workflows and may be tough to keep track of what’s available and what’s the best option for you. This blog is intended to help expose you to all the Survey123 tools available to developers and provide some use cases and information as to why you may want to go with one tool over another.

This blog will cover the following automation tools:

Webhooks
ArcGIS Survey123 module present in the ArcGIS API for Python
Survey123 REST API
Building a custom version of Survey123
Field app add-in’s (alpha)
Embedding a survey
Survey123 web app JavaScript API

Webhooks:

Typically, webhooks are used to connect two different applications such as Survey123 and Gmail and use web requests (HTTP requests) in order to exchange information. Webhooks allow you to automate tasks using connectors provided by the webhook provider of your choice. The two common webhook providers used with ArcGIS Survey123 are Microsoft Power Automate and Integromat, although other providers like Zapier and Tray.io can also be used. Using the connectors provided by your webhook provider workflows such as generating reports, sending emails, copying data into a relational database management system, or enriching your data using additional API services can all be achieved using webhooks.

Typically, you would use a webhook to automate your workflow when you would like that automation to occur in real time as surveys are submitted. For example, as folks submit surveys you would like to immediately generate a report and send an email to the submitter containing the report as an attachment. Conversely, if you would like data updated in real time as submissions come in with services such as Esri’s geoenrichment API using a webhook would be a good option to help you reach your end goal.

Please see these links for more information on getting started with webhooks:

Survey123 module present in the ArcGIS API for Python:

Within the ArcGIS API for Python there is a module specifically designed for Survey123 workflows. The Survey123 Python module provides methods and resources to automate common tasks with your Survey123 surveys. Using the module, you can work with your surveys, identify properties, and generate Reports. Additionally, you can work with survey results whether that be through displaying the data in a Pandas data frame using a Jupyter Notebook or downloading results as a file geodatabase.

The ArcGIS Survey123 module can be used with other modules available in the ArcGIS API for Python. This opens the door to automate end to end workflows as any method available in the ArcGIS API for Python can be used to achieve your end goal. For example, you can connect to a specific survey and work with the underlying feature service or perform a common task on a large number of surveys, such as sharing surveys to a group or cloning surveys between ArcGIS organizations.

You may want to use the ArcGIS API for Python if you don’t need your workflow completed immediately like a webhook would provide, say you want to generate reports once a week or clone a handful of surveys from your development organization to you staging organization every quarter. Conversely, you may also want to consider using the ArcGIS API for Python if want to keep everything internal to your organization instead of using third party software. Say, for example, your organization does not allow you to use Integromat, you may want to use the ArcGIS API for Python to automate your report generation keeping everything internal. We have Python guides available for a handful of Survey123 workflows present in our documentation, and can also be downloaded from our Survey123-tools GitHub repo. We are working to add more workflows to the repo and documentation, and we are open to feedback on new workflows that folks would like scripted or enhancements to the existing guides to make them more meaningful.

Please use these links for more information on getting started with the Survey123 module in the ArcGIS API for Python:

Report REST API:

The Survey123 REST API allows you to implement the power of Survey123 reports in your own applications. The Survey123 website uses the REST API when it is generating reports through the web UI, the REST API is documented publicly and can be incorporated into your own custom applications to generate reports as you like. Workflows that you would use in the Survey123 website like estimating credits, checking report template syntax, creating sample reports, and generating full reports are all accessible via the Survey123 REST API.

The general workflow when using the Survey123 REST API is to start off by sending a submitJob request to the API. This request will contain information such as the REST URL for the feature layer associated with the survey, query parameters, item ID for the template item you would like to use, and a valid access token. The response of the submitJob request will provide the ID for that specific job. Using that job ID your application will need to send periodic requests to the jobs resource passing along the ID supplied from the submit job task. When the task finishes, and the report is ready the response of the jobs request will contain the result information on the report as well as the URL to download the report.

You may want to use the Survey123 REST API if you have your survey embedded in a website or a custom application and you want to generate a report as soon as a user submits a survey and have the report available for download or view directly within your application. Another workflow would be if you wanted to create a custom Report widget for your ArcGIS Dashboard or Experience Builder application.

Please use these links for more information on getting started with the Survey123 REST API:

Build a custom app:

Using ArcGIS AppStudio with the AppStudio Developer Edition license you can modify any aspect of the ArcGIS Survey123 field app and connect to meet your needs. The source code for both applications is available in the AppStudio enterprise templates and can be modified to your liking. After you have modified the application to meet your needs you can publish the application to the app stores making it available to others.

Customizations can be cosmetic like changing the field app and connect to your company’s colors or adding your company’s logo in the app all the way to functional like modifying functionality or adding new functionality that meet your specific needs.

You may want to customize the ArcGIS Survey123 field app or connect if your workflow requires something that the out of the box ArcGIS Survey123 application doesn’t provide. Sticking with the reports theme, if you need a report generated as soon as a survey is submitted and have the generated report accessible within the Survey123 field app you can add in requests to the Survey123 REST API after the survey is submitted and generate a UI to access the report once it is generated.

Please use these links for more information on getting started with building a custom Survey123 application:

Field app add-in’s (alpha):

The custom build of Survey123 may be a more tedious task than you would like. As Survey123 releases the code for those releases is updated in the Survey123 enterprise template available in ArcGIS AppStudio. This means each time there is an ArcGIS Survey123 release if you want to update you would need to update your app using the latest template and test to doublecheck everything still works as expected with the new release. You would then need to republish your app to the app store and have your users update the app on their end. If you need specific functionality that doesn’t come standard in the out of the box Survey123 application but you don’t want to deal with maintaining an entire app plus your customizations with each version release ArcGIS Survey123 field app add-in’s may be a favorable option. The benefit of add-in’s are they sit alongside the app store release of Survey123. Your custom functionality can live independently from Survey123 and as Survey123 updates there may not be anything you would need to do on your end. Currently field app add-in’s are in their Alpha stage meaning some additional steps are needed in the Survey123 field app in order to use them.

There are four types of add-in’s available for the ArcGIS Survey123 field app, they are:

Tool
Custom question type
Scanner control
Camera control

You may want to use add-in’s if you are looking for specific functionality that is not present in the out of the box release of ArcGIS Survey123, without the hassle of maintaining an entire application.

Please use these links for more information on getting started with ArcGIS Survey123 add-in’s:

Embed a survey:

ArcGIS Survey123 web forms can be embedded in other applications either using an iframe or using the JaveScript API which will be discussed next. Surveys can be embedded in ArcGIS Dashboards, Experience builder applications, HTML pages, or other custom applications. Embedded surveys support a number of URL parameters which help you fine tune how you want your survey to behave in your application.

You may want to embed a survey in your application if you are looking to have folks take new surveys or edit existing surveys in web applications and do not require custom modifications.

Please use these links for more information on getting started with embedding ArcGIS Survey123 surveys:

Web app JavaScript API

The ArcGIS Survey123 web app JavaScript API provides resources beyond simply embedding a survey in a web application. The web app JavaScript API provides constructors and methods that allow you to implement custom functionality allowing your application to interact with your Survey123 webform. Workflows such as setting question defaults based on a value in your application, modifying the style of the form, setting the webform mode, and setting custom scripts to run when a form is submitted can all be achieved using the web app JavaScript API.

You may want to use the Survey123 web app JavaScript API if you plan on embedding your survey in a custom web application and would benefit from adding your own customization to the web form that will help make the integration seamless.

Please use these links for more information on getting started with the ArcGIS Survey123 web app JavaScript API: