arcgis.apps.survey123 module

Bases: object

Survey Manager allows users and administrators of ArcGIS Survey123 to analyze, report on, and access the data for surveys.

create(title: str, folder: str = None, tags: str = None, summary: str = None, description: str = None, thumbnail: str = None) → Survey

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.

Inputs	Description
title	Required string. Title for the form item.
folder	Optional string. The name of the folder to store the survey form item in your ArcGIS content.
tags	Optional string. Comma-separated tags for the form item.
summary	Optional string. Summary of the survey purpose (limit to a maximum of 250 characters).
description	Optional string. Description of the form item.
thumbnail	Optional string. Path for the thumbnail image file.

Returns:

Survey

get(survey_id: Item | str)

returns a single Survey object from and Item ID or Item

property surveys: list

returns a list of existing Survey

Bases: object

A Survey is a single instance of a survey project. This class contains the Item information and properties to access the underlying dataset that was generated by the Survey form.

Data can be exported to Pandas DataFrames, shapefiles, CSV, and File Geodatabases.

In addition to exporting data to various formats, a Survey’s data can be exported as reports.

add_webhook(name: str, payload_url: str, trigger_events: list | None = ['addData'], portal_info: bool | None = False, submitted_record: bool | None = False, user_info: bool | None = False, server_response: bool | None = False, survey_info: bool | None = False, active: bool | None = True) → dict

Add a webhook to your survey.

Parameter	Description
name	Required string. The name for your webhook.
payload_url	Required string. The payload URL is where the survey information will be sent. This needs to be provided by an external webhook service.
trigger_events	Optional list. The trigger events describe the specific actions that will call the webhook. Options are “addData” and “editData”. Set to “addData” by default.
portal_info	Optional boolean. Information about the ArcGIS organization where the survey is hosted. It contains the following properties: url token
submitted_record	Optional boolean. The survey record that was submitted. It contains the following properties: attributes geometry layerInfo result repeats Note Each object within the repeats array is a feature that has attributes, geometry, layerInfo, result, repeats, and attachments. attachments + id + globalId + name + contentType + size + keywords + url + parentObjectId
user_info	Optional boolean. Information about the ArcGIS organizational account for the user who submitted the survey. It contains the following properties: username firstName lastName fullName email
server_response	Optional boolean. The response from the applyEdits operation. It includes the global IDs for the features created by the operation and whether the operation was successful.
survey_info	Optional boolean. Information about the survey that generated the webhook. It contains the following properties: formItemId formTitle serviceItemId serviceUrl
active	Optional boolean. Determines whether the webhook will be active when saved. Set to True by default.

Returns:

Dictionary {success, webhookId}

check_template_syntax(template_file: str | None = None)

A sync operation to check any syntax which will lead to a failure when generating reports in the given feature.

Parameter	Description
template_file	Required string. The report template file for which syntax is to be checked.

Returns:

dictionary {Success or Failure}

create_report_template(template_type: str | None = 'individual', template_name: str | None = None, save_folder: str | None = None)

The create_report_template creates a simple default template that can be downloaded locally, edited and uploaded back up as a report template.

Parameter	Description
template_type	Optional string. Specify which sections to include in the template. Acceptable types are individual, summary, and summaryIndividual. Default is individual.
template_name	Optional string. Specify the name of the output template file without file extension.
save_folder	Optional string. Specify the folder location where the output file should be stored.

Returns:

String

create_sample_report(report_template: Item, where: str = '1=1', utc_offset: str = '+00:00', report_title: str | None = None, merge_files: str | None = None, survey_item: Item | None = None, webmap_item: Item | None = None, map_scale: float | None = None, locale: str = 'en', save_folder: str | None = None) → str

Task for creating a test sample report (similar to generate_report) and refining a report template before generating any formal report.

Parameter	Description
report_template	Required Item. The report template Item.
where	Optional string. This is the select statement used to export part or whole of the dataset. If the record count is > 1, then the item must be saved to your organization.
utc_offset	Optional string. This is the time offset from UTC to match the users timezone. Example: EST - “+04:00”
report_title	Optional string. An Item with this argument as the title if no save_folder argument. If save_folder argument is provided, this argument will be the name of the output file, or the base name for files in the output zipped package if the server-side component chose to zip up the output (depends upon the size and number of files that would result). Note If merge_files is either nextPage or continuous, report_title is the output file name.
merge_files	Optional string. Specify if output is a single file containing individual records on multiple pages (nextPage or continuous) or multiple files (none). none - Print multiple records in split mode. Each record is a separate file. This is the default value. nextPage - Print multiple records in a single document. Each record starts on a new page. continuous - Print multiple records in a single document. EAch records starts on the same page of the previous record. Note A merged file larger than 500 MB will be split into multiple files.
save_folder	Optional string. Specify the folder location where the output file should be stored.
survey_item	Optional survey Item to provide additional information on the survey structure.
webmap_item	Optional Item . Specify the basemap for printing task when printing a point/polyline/polygon. This takes precedence over the map set for each question inside a survey.
map_scale	Optional float. Specify the map scale when printing, the map will center on the feature geometry.
locale	Optional string. Specify the locale setting to format number and date values.

Returns:

String

delete_webhook(webhook_id: str) → bool

Deletes a webhook from a survey

Parameter	Description
webhook_id	Required string. The ID for the webhook to delete.

Returns:

String

download(export_format: str, save_folder: str | None = None) → str | pd.Dataframe

Exports the Survey’s data to other format

Parameter	Description
export_format	Required string. This is the acceptable export format that a user can export the survey data to. The following formats are acceptable: File Geodatabase, Shapefile, CSV, and DF.
save_folder	Optional string. Specify the folder location where the output file should be stored.

Returns:

String or DataFrame

estimate(report_template: Item, where: str = '1=1')

An operation to estimate how many credits are required for a task with the given parameters.

Parameter	Description
report_template	Required Item. The report template item.
where	Optional string. This is the select statement used to export part or whole of the dataset. If the filtered result has more than one feature/record, the request will be considered as a batch printing. Currently, one individual report will be generated for each feature/record.

Returns:

dictionary {totalRecords, cost(in credits)}

generate_report(report_template: Item, where: str = '1=1', utc_offset: str = '+00:00', report_title: str | None = None, package_name: str | None = None, output_format: str = 'docx', folder_id: str | None = None, merge_files: str | None = None, survey_item: Item | None = None, webmap_item: Item | None = None, map_scale: float | None = None, locale: str = 'en', save_folder: str | None = None) → str

The generate_report method allows users to create Microsoft Word and PDF reports for survey results based on a reporting template. Reports are saved as an Item in an ArcGIS content folder or saved locally on disk. For additional information on parameters, see Create Report <https://developers.arcgis.com/survey123/api-reference/rest/report/#create-report>.

Note

The Survey123 report service may output one or more .docx or .pdf files, or a zipped package of these files. Whether the output is contained in a .zip file depends on the number of files generated and their size. For more information, see the packageFiles parameter in the Create Report documentation.

Note

To save to disk, do not specify a folder_id argument.

See Get Started with Survey123 Reports for further information.

Parameter	Description
report_template	Required Item. The report template.
where	Optional string. The select statement issued on survey FeatureLayer to report on all survey records or a subset. Query the parent_fl_url property of the Survey object to get the feature layer URL and retrieve a list of fields. >>> gis = GIS(profile="your_profile") >>> smgr = SurveyManager(gis) >>> survey_item = gis.content.get("<survey form id>") >>> survey_obj = smgr.get(survey_item.id) >>> survey_fl = FeatureLayer(survey_obj.parent_fl_url, gis) >>> print([f["name"] for f in survey_fl.properties.fields])
utc_offset	Optional string. Time offset from UTC. This offset is applied to all date, time, and dateTime questions that appear in the report output. Example: EST - “+04:00”
report_title	Optional string. If folder_id is provided, the result is an Item with this argument as the title. If save_folder argument is provided, this argument will be the name of the output file, or the base name for files in the output zipped package if the server-side component chose to zip up the output (depends upon the size and number of files that would result). Note If merge_files is either nextPage or continuous, report_title is the output file name.
package_name	Optional string. Specify the file name (without extension) of the packaged .zip file. If multiple files are packaged, the report_title argument will be used to name individual files in the package. Note The Survey123 report service automatically decides whether to package generated reports as a .zip file, depending on the output file count. See the packageFiles parameter description in the Create Report Request parameters documentation for details.
save_folder	Optional string. Specify the folder location where the output file or zipped file should be stored. If folder_id argument is provided, this argument is ignored.
output_format	Optional string. Accepts docx or pdf.
folder_id	Optional string. If a file Item is the desired output, specify the id value of the ArcGIS content folder.
merge_files	Optional string. Specify if output is a single file containing individual records on multiple pages (nextPage or continuous) or multiple files (none). none - Print multiple records in split mode. Each record is a separate file. This is the default value. nextPage - Print multiple records in a single document. Each record starts on a new page. continuous - Print multiple records in a single document. EAch records starts on the same page of the previous record. Note A merged file larger than 500 MB will be split into multiple files.
survey_item	Optional survey Item to provide additional information on survey structure.
webmap_item	Optional web map Item. Specify the basemap for all map questions in the report. This takes precedence over the map set for each question in the report template.
map_scale	Optional float. Specify the map scale for all map questions in the report. The map will center on the feature geometry. This takes precedence over the scale set for each question in the report template.
locale	Optional string. Specify the locale to format number and date values.

Returns:

An Item or string upon completion of the reporting job. For details on the returned value, see Response Parameters for the generate_report() job.

 # Usage example #1: output a PDF file item:
 >>> from arcgis.gis import GIS
 >>> from arcgis.apps.survey123 import SurveyManager

 >>> gis = GIS(profile="your_profile_name")

 >>> # Get report template and survey items
 >>> report_templ = gis.content.get("<template item id>")
 >>> svy_item = gis.content.get("<survey item id>")

 >>> svy_mgr = SurveyManager(gis)
 >>> svy_obj = svy_mgr.get(svy_item.id)

 >>> user_folder_id = [f["id"]
                      for f in gis.users.me.folders
                      if f.name == "folder_title"][0]

 >>> report_item = svy_obj.generate_report(report_template=report_templ,
                                           report_title="Title of Report item",
                                           output_format="pdf",
                                           folder_id=user_folder_id,
                                           merge_files="continuous")

# Usage example #2: output a Microsoft Word document named `LessThan20_Report.docx`

>>> report_file = svy_obj.generate_report(report_template=report_templ,
                                          where="objectid < 20",
                                          report_title="LessThan20_Report",
                                          output_format="docx",
                                          save_folder="file\system\directory\",
                                          merge_files="nextPage")

# Usage example #3: output a zip file named `api_gen_report_pkg.zip` of individual
#                   pdf files with a base name of `SpecimensOver30`

>>> report_file = svy_obj.generate_report(report_template=report_templ,
                                          where="number_specimens>30",
                                          report_title="SpecimensOver30",
                                          output_format="pdf",
                                          save_folder="file\system\directory",
                                          package_name="api_gen_report_pkg")

property properties

returns the properties of the survey

publish(xlsform: str | None = None, info: dict | None = None, media: str | None = None, scripts: str | None = None, create_web_form: bool | None = True, enable_delete_protection: bool | None = False, table_only: bool | None = False, create_coded_value_domains: bool | None = True, enable_sync: bool | None = False, use_non_globalid_relationships: bool | None = None, create_web_map: bool | None = True, thumbnail: str | None = None, summary: str | None = None, description: str | None = None, tags: str | None = None, schema_changes: bool | None = False) → Survey

Publishes surveys created by the create() method or an existing survey published to your ArcGIS organization. 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.).

If schema_changes is set to False, any differences between the schema of the XLSForm and the submission endpoint will generate an error that lets you know what the differences are. If schema_changes is set to True, the following logic is applied:

• When using a submission_url that references an ArcGIS Server feature service, schema changes are not applied. The publish() method returns an error about any differences found between the design and schema.

• When the survey has an associated hosted feature service and view service, with or without a submission_url set, schema changes are applied to the parent service and propagated to the view.

• When the survey has an associated hosted feature service but no view service, with or without a submission_url set, schema changes are applied to the submission endpoint.

Argument	Description
xlsform	Optional string. Path for the XLSForm file.
info	Optional dictionary. Represents the contents of the .info file (settings); See the table below for the keys and values. Keys are case sensitive. # Example: Enable the Inbox: info={ "queryInfo": { "mode": "manual", "editEnabled": True, "copyEnabled": True } }
media	Optional string. Path for the media folder or the ZIP file that contains it.
scripts	Optional string. Path for the scripts folder or the ZIP file that contains it.
create_web_form	Optional boolean. Enabled by default. When this parameter is off, publishing a survey does not create a matching web form that allows users to complete the survey in the web app, so the survey only works in the field app.
enable_delete_protection	Optional boolean. Disabled by default. Enables delete protection on the form item and all related content (feature service, web maps, report templates).
table_only	Optional boolean. Disabled by default. Creates a hosted table instead of a feature service if no geometry is present in the parent layer.
create_coded_value_domains	Optional boolean. Enabled by default. Choice lists in the choices worksheet will be used to create coded value domains in the feature layer. For more information, see Multiple choice questions.
enable_sync	Optional boolean. Disabled by default. When this parameter is on, the sync capability is enabled on the feature layer when the survey is published. The sync capability is a requirement if a survey uses offline map areas that have been configured for a web map. Alternatively, you can enable sync after publishing by using the Settings tab on the feature layer’s item page in your ArcGIS organization.
use_non_globalid_relationships	Optional boolean. Enabled by default when publishing to ArcGIS Online and disabled by default when publishing to ArcGIS Enterprise. If your work involves copying survey data between databases, it is recommended that you do not use global ID parent keys in repeat relationships.
create_web_map	Optional boolean. Enabled by default. Creates a web map that includes the survey’s feature layer with default symbology and uses your organization’s default basemap. This web map is automatically added to the Linked Content tab in Survey123 Connect and is available in the Survey123 field app.
thumbnail	Optional string. Path for the thumbnail image file.
summary	Optional string. Short summary about the survey (limit to a maximum of 250 characters).
description	Optional string. Description of the form item.
tags	Optional string. Tags listed as comma-separated values or a list of strings. Used for searches on items.
schema_changes	Optional boolean. Disabled by default. Specifies if schema changes should be made to the feature service or not.

Key:Value options for the `info` argument

Key	Value
collectInfo	Optional dictionary. Displays the distance and direction from the device’s location for each response in the list view in the Inbox, Drafts, Outbox, Sent, and Overview folders in the Survey123 field app and also enables the map view in each of these folders. Setting showMap to True enables location indicators, and False disables location indicators. # Syntax: { "foldersInfo":{ "showMap": True|False } }
displayInfo	Optional dictionary. Defines the appearance of the survey with style options and specifies its map and coordinate information. map—Optional dictionary. Provides access to a number of default settings for maps used in a survey, including the coordinate format, zoom level, and home location. You can also set a default basemap for all map questions in a survey by clicking the Basemap button on the lower map. coordinateFormat—Optional string. Displays a location value in the specified format, including the following coordinate types: Degrees Minutes, Degrees Decimal Minutes, Decimal Degrees, MGRS, USNG, and UTM/UPS. This setting doesn’t affect manually entered values (which only accepts decimal minutes) nor the value recorded in a survey (which is recorded in decimal degrees). defaultType—Optional dictionary. Control the name of the default basemap by setting the name in the defaultType dictionary. home—Optional dictionary. The home location provided for a survey is returned if the device’s location cannot be found. In the home dictionary, set latitude, longitude, and zoomLevel to define the home location. The Survey123 website uses the home zoom level as a default when viewing or printing individual survey results. preview—Optional dictionary. Control the preview map by using the preview dictionary. Setting coordinateFormat controls the display format of the coordinates. Setting zoomLevel controls the tile level of detail to display. mapTypes—Optional dictionary. Use the mapTypes dictionary to manually associate a map to a survey. This workflow won’t link the map to the survey. You can add the default basemap list to any mapSources by setting append to True. By setting includeLibrary to True, all maps associated with the survey will be added to the ArcGIS/My Surveys/Maps folder to make them available to any survey. mapSources—Optional list. List of dictionaries for which each contains a map to include. Parameters in the dictionary include: url for the the map’s item page URL, name sets the display name of the map, description sets the description of the map, and storeInLibrary is a boolean that controls if the map gets added to the ArcGIS/My Surveys/Maps folder making it available to any survey. style—Optional dictionary. Controls the colors of various elements in the survey. You can customize toolbarTextColor and toolbarBackgroundColor colors for the survey header, body (textColor/backgroundColor/backgroundImage), input fields (inputTextColor/inputBackgroundColor), and footer (footerTextColor/footerBackgroundColor). Provide the hexadecimal color code or HTML color name for the respective parameter. For readability, the contrast ratio between text and background colors should not be below 4.5. # Syntax: { "displayInfo": { "map": { "coordinateFormat" : "<dm | ddm | d | mgrs | usng | utmups>", "defaultType": { "name": "Basemap name" }, "home": { "latitude": 34.0568, "longitude": -117.1961, "zoomLevel": 20 }, "preview": { "coordinateFormat": "<dm | ddm | d | mgrs | usng | utmups>", "zoomLevel": 0 }, "mapTypes": { "append": True|False, "includeLibrary": True|False, "mapSources": [{ "url": "https://www.arcgis.com/home/item.html?id=ABC1234...", "name": "Redlands Basemap", "description": "Basemap for the City of Redlands, CA", "storyInLibrary": True|False }] }, }, "style": { "backgroundColor": "#00338D", "backgroundImage": "media/backgroundImage.jpeg", "inputBackgroundColor": "#C60C30", "inputTextColor": "#00338D", "textColor": "#C60C30", "toolbarBackgroundColor": "#00338D", "toolbarTextColor": "#C60C30", "footerTextColor": "#00338D", "footerBackgroundColor": "#C60C30" } } }
foldersInfo	Optional dictionary. Displays the distance and direction from the device’s location for each response in the list view in the Inbox, Drafts, Outbox, Sent, and Overview folders in the Survey123 field app and also enables the map view in each of these folders. Setting showMap to True enables location indicators, and False disables location indicators. # Syntax: { "foldersInfo":{ "showMap": True|False } }
imagesInfo	Optional dictionary. Controls the maximum dimensions for images submitted to the survey. A photo taken in Survey123 is saved as a .jpg file, with a quality level dependent on the device’s camera. The image size, measured by pixels on the longest edge, can be set using the captureResolution property. This size is applied to all image questions in the survey. The default size is 1280. To allow any size photo, set a value of 0. # Syntax: { "imagesInfo": { "captureResolution": <320 | 640 | 1280 | 1920 | 0> } }
locationSharingInfo	Optional dictionary. Ignored if location sharing is not enabled in the organization; a survey setting cannot override the organization setting. To require location sharing for an individual survey, set both enabled and required to True. To allow users to enable location sharing, set enabled to True and required to False. # Syntax: { "locationSharingInfo": { "enabled": True|False, "required": True|False } }
overviewInfo	Optional dictionary. Setting enabled to True provides access to the Overview folder in the Survey123 field app. This folder contains every survey record currently stored on the device, color-coded by the folder in which they are located. # Syntax: { "overviewInfo": { "enabled": True|False } }
queryInfo	Optional dictionary. Setting mode to “manual” provides access to the inbox, which allows viewing (viewEnabled: True), editing (editEnabled: True), and copying (copyEnabled: True) existing survey responses stored in the feature layer. The query expression specified by the where parameter determines which surveys in the Survey123 field app are available for editing in the inbox. In the inbox, selecting Refresh updates the list of surveys shown on the List tab. The refresh action generally returns all surveys that satisfy the query expression in the where parameter (if set) and that are not already stored in other folders on the device. If you set applySpatialFilter to True, selecting Refresh on the Map tab applies a spatial filter that updates the list to show only surveys that are within the current map extent. # Syntax: { "queryInfo": { "mode": ""|"manual", "where": "status='for_review'", "applySpatialFilter": True|False, "editEnabled": True|False, "viewEnabled": True|False, "copyEnabled": True|False } }
sentInfo	Optional dictionary. Controls access to the sent folder, which allows access to surveys that were previously sent from the device. Setting enabled to True provides access to the sent folder, which allows editing (editEnabled: True) and copying (copyEnabled: True) existing survey responses that were previously submitted from the device. # Syntax: { "sentInfo": { "enabled": True|False, "editEnabled": True|False, "copyEnabled": True|False } }

Returns:

Survey

property report_templates: list

Returns a list of saved report Items.

Returns:

list of Items

property reports: list

returns a list of generated reports

update_report_template(template_file: str | None = None)

Check report template syntax to identify any syntax which will lead to a failure when generating reports in the given feature and updates existing report template organizational item.

Parameter	Description
template_file	Required string. The report template file which syntax to be checked, and uploaded. The updated template name must match the name of the existing template item.

Returns:

Item {Success) or string (Failure}

update_webhook(webhook_id: str, name: str | None = None, payload_url: str | None = None, trigger_events: list | None = None, portal_info: bool | None = None, submitted_record: bool | None = None, user_info: bool | None = None, server_response: bool | None = None, survey_info: bool | None = None, active: bool | None = None) → dict

Update a webhook with your survey.

Parameter	Description
webhook_id	Required string. The ID for the webhook to update.
name	Optional string. The name for your webhook.
payload_url	Optional string. The payload URL is where the survey information will be sent. This needs to be provided by an external webhook service.
trigger_events	Optional list. The trigger events describe the specific actions that will call the webhook. Options are “addData” and “editData”.
portal_info	Optional boolean. Information about the ArcGIS organization where the survey is hosted. It contains the following properties: url token
submitted_record	Optional boolean. The survey record that was submitted. It contains the following properties: attributes geometry layerInfo result repeats Note Each object within the repeats array is a feature that has attributes, geometry, layerInfo, result, repeats, and attachments. attachments + id + globalId + name + contentType + size + keywords + url + parentObjectId
user_info	Optional boolean. Information about the ArcGIS organizational account for the user who submitted the survey. It contains the following properties: username firstName lastName fullName email
server_response	Optional boolean. The response from the applyEdits operation. It includes the global IDs for the features created by the operation and whether the operation was successful.
survey_info	Optional boolean. Information about the survey that generated the webhook. It contains the following properties: formItemId formTitle serviceItemId serviceUrl
active	Optional boolean. Determines whether the webhook will be active when saved.

Returns:

Dictionary {success, webhookId}

upload_report_template(template_file: str | None = None, template_name: str | None = None)

Check report template syntax to identify any syntax which will lead to a failure when generating reports in the given feature. Uploads the report to the organization and associates it with the survey.

Parameter	Description
template_file	Required string. The report template file which syntax to be checked, and uploaded.
template_name	Optional string. If provided the resulting item will use the provided name, otherwise the name of the docx file will be used.

Returns:

Item {Success) or string (Failure}

property webhooks: list

Returns a list of existing Survey webhooks