Create and publish surveys

The create() method is useful for batch creating blank surveys for which you can reassign ownership to another colleague to complete the design and publish. If you already have an XLSForm, you can use the create() and publish() methods to automate creating and publishing surveys.

This sample notebook demonstrates how you can automate creating and publishing surveys using ArcGIS API for Python.

Create a survey

You can create surveys using ArcGIS API for Python with the create() method. The create() method creates an empty form item and hosted feature service in the folder supplied to the method or a new folder created with the survey. The output of the create() method is a single Survey object.

Surveys created by the create() method create the equivalent of a new unpublished web designer survey. After creating a survey with ArcGIS API for Python, if you don't have an XLSForm or existing survey design, you can use the Survey123 web designer to design and publish your survey.

The first step is to connect to your GIS.

import arcgis
from arcgis.gis import GIS
gis = GIS("home")

Next, a SurveyManager is defined, and a new survey is created. A survey in the Survey Manager is a single instance of a survey project that contains the item information and properties and provides access to the underlying survey dataset. For more information on Survey Manager, see the API Reference for the ArcGIS API for Python.

To create a survey, use the create() method on a SurveyManager instance.

The create() method only requires the title parameter. By default, the create() method will automatically create a folder using the Survey-{title} naming convention consistent with other Survey123 publishing apps. Alternatively, if you want to store your survey in a folder that already exists in your content, you can use the folder parameter and specify the name or folder ID.

survey_manager = arcgis.apps.survey123.SurveyManager(gis)
new_survey = survey_manager.create(
    title = "Water Quality Survey",
    folder = "Water surveys",
    tags = "Water surveys, Survey123, Python",
    summary = "City of Cilantro water quality survey.",
    description = "This survey is used by the City of Cilantro to measure and record water quality at various locations around the city.", 
    thumbnail = r"C:\thumbnail.png"
)

new_survey

The result of the create() method is a Survey object. At this stage, the survey is in a draft state and has no schema or questions. You can use the Survey123 web designer to design your survey and publish from there, use the publish() method with an existing XLSForm design, or use a third-party Python package to design your survey directly in Python and call the publish() method.

Publish a survey

To publish a survey using the publish() method, an existing Survey object is required. The Survey can be an unpublished survey created by the create() method or an existing published survey in your content. It can also be an unpublished blank survey created with the Survey123 web designer (any designs will be overwritten by the publish() method's required XLSForm.).

When publishing surveys with the publish() method, important considerations are as follows:

• Any survey is treated as a survey published with Survey123 Connect, which means you can no longer use the web designer to edit the portions of the survey that are managed by the XLSForm. For example, the survey title and survey questions cannot be edited. Themes, webhooks, and sharing options can still be edited in the web designer.
• New surveys will create and use a _form view as the submission endpoint, which means you can no longer update the feature service schema in Survey123 Connect.
• Existing surveys will maintain their submission endpoint.

A schema_changes parameter is available to modify the schema of your submission endpoint. For more information on the schema_changes parameter please see the ArcGIS API for Python documentation.

In this example, the required xlsform parameter is set to the path where the XLSForm is located and optional parameters are set:

• info is set to enable the Inbox.
• enable_delete_protection is enabled for the form item and its related content.

published_survey = new_survey.publish(
    xlsform=r"C:\water_quality_survey.xlsx", 
    info=
        {"queryInfo": {
            "mode": "manual",
            "editEnabled": True,
            "copyEnabled": False
            }
        }, 
    enable_delete_protection=True
    )

published_survey