SurveyManager
- class arcgis.apps.survey123.SurveyManager(gis, baseurl=None)
Bases:
object
Survey Manager allows users and administrators of ArcGIS Survey123 to analyze, report on, and access the data for surveys.
- create(title, folder=None, tags=None, summary=None, description=None, thumbnail=None)
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:
- get(survey_id)
returns a single
Survey
object from and Item ID or Item
Survey
- class arcgis.apps.survey123.Survey(item, sm, baseurl=None)
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, payload_url, trigger_events=['addData'], portal_info=False, submitted_record=False, user_info=False, server_response=False, survey_info=False, active=True)
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=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='individual', template_name=None, save_folder=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, where='1=1', utc_offset='+00:00', report_title=None, merge_files=None, survey_item=None, webmap_item=None, map_scale=None, locale='en', save_folder=None)
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
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)
Deletes a webhook from a survey
Parameter
Description
webhook_id
Required string. The ID for the webhook to delete.
- Returns:
String
- download(export_format, save_folder=None)
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, where='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, where='1=1', utc_offset='+00:00', report_title=None, package_name=None, output_format='docx', folder_id=None, merge_files=None, survey_item=None, webmap_item=None, map_scale=None, locale='en', save_folder=None)
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 thegenerate_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["title"] == "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")
- publish(xlsform=None, info=None, media=None, scripts=None, create_web_form=True, enable_delete_protection=False, table_only=False, create_coded_value_domains=True, enable_sync=False, use_non_globalid_relationships=None, create_web_map=True, thumbnail=None, summary=None, description=None, tags=None, schema_changes=False)
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:
- update_report_template(template_file=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, name=None, payload_url=None, trigger_events=None, portal_info=None, submitted_record=None, user_info=None, server_response=None, survey_info=None, active=None)
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=None, template_name=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
Returns a list of existing
Survey
webhooks