arcgis.apps.survey123 module

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

Survey

get(survey_id)

returns a single Survey object from and Item ID or Item

property surveys

returns a list of existing Survey

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

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)

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 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["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")
property properties

returns the properties of the survey

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

Survey

property report_templates

Returns a list of saved report Items.

Returns

list of Items

property reports

returns a list of generated reports

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