By default, when you publish a survey in ArcGIS Survey123 Connect, a feature layer is created using the schema from the survey. Alternatively, you can choose to associate your survey with an existing feature layer.
Prepare a feature layer
To use a feature layer with Survey123, it must be an item in ArcGIS Enterprise or ArcGIS Online. This includes hosted feature layers and feature layers published to federated and nonfederated servers.
To work with nonfederated feature services, additional configuration is required, as you must manually create a feature layer item in your ArcGIS organization that represents the service. For details, see the Knowledge Base article on how to connect to nonfederated ArcGIS Server services.
The owner and users of the survey must have access to the feature layer, and it must be editable. Also consider the following:
- If users are collecting new surveys, the Create capability is required.
- If users are editing existing surveys, the Update capability on the layer is required.
- If users are capturing images, audio, or files, hasAttachments must be set to true.
When enabling attachments on a feature layer the KEYWORD and EXIFINFO columns are not added to the schema by default. This column is needed to be able to associate attachments with the correct record. After enabling attachments, run the Upgrade Attachments Geoprocessing tool to enable keywords.
Note:It's recommended that the KEYWORD and EXIFINFO columns are added before collecting records with Survey123 so that all attachments that are submitted have keywords. If the KEYWORD and EXIFINFO columns do not exist before attachments are submitted, the Update Attachment Keywords Python notebook can be used to update attachments.
Repeats cannot reference related layers or tables unless the child layer or table uses a GUID field for the relationship.
If you plan to edit your surveys, ensure that either the feature layer allows null values or the survey uses required fields. Survey123 uses null values in editing when an answer is deleted and is not replaced; consequently, Survey123 will not submit a survey from a feature layer that doesn't permit null values.
The following additional capabilities must be set to true for the feature layer:
- supportsAttachmentsByUploadId—This capability is automatically turned on when attachments are enabled on the feature layer. It allows the app to upload all attachments associated with a survey before submitting the survey. If any of the attachments fail, the entire survey submission rolls back, preventing data loss.
- supportsApplyEditsWithGlobalIds—The feature layer must support applying edits with global IDs. This allows the app to create and manage the global IDs in created features (as opposed to the server creating a new global ID for created features).
For a feature layer to support applying edits with global IDs, the following requirements must be met:
- The layers in the feature layer must have a GlobalId column with a unique index. The best way to do this is to enable sync when publishing the feature layer.
- If using a multiuser geodatabase, layers can use branch versioning but not traditional versioning. Survey123 will target the default version when using a branch versioned geodatabase. For more information, see Versioning types.
- Global IDs must exist in a feature layer or table before enabling attachments on either.
- If the feature layer contains m-enabled layers, editing without m-values must be enabled.
For more information on supporting editing in a feature layer, see supportsApplyEditsWithGlobalIds in Layer (Feature Service) in the ArcGIS REST API documentation.
Survey123 only supports one-to-many GUID relationships when working with existing feature layers and related tables. One-to-one relationships are not supported.
Create a survey from a feature layer
You can create a survey from an existing feature layer in Survey123 Connect. The feature layer must be prepared for use with Survey123. Sign in to your ArcGIS organization, and click New survey. Choose the Feature service category. Browse to and select a feature layer and click Create survey. An XLSForm is generated from the feature layer. You can then publish this survey immediately or further customize it. For example, you can add more descriptive labels to the questions or arrange them in groups.
If the feature layer you chose has more than one layer, the survey is generated based on the first layer. To base a survey on another layer of the feature layer, you must author the survey manually and update the form_id and submission_url properties on the settings tab of the spreadsheet. For more information, see Author a survey that matches a feature layer.
If the feature layer you chose has attachments, a single image question will be created in the survey with the name <layer_name>_image. This name will not match a keyword in the attachments table and must be updated. If the existing attachments represent more than one question, you must add image questions to the survey to match each of the keywords in the attachments table.
If the survey you're creating requires audio or file questions, you must add these to the survey manually. After generating the survey, open the spreadsheet and add the questions. For more information, see Media questions. The feature layer must also have attachments enabled.
Author a survey that matches a feature layer
You can manually author a new survey that matches an existing feature layer, but you must update the form_id and submission_url properties on the settings tab of the spreadsheet to define a link between the survey and the feature layer's item in your portal or ArcGIS Online.
The form_id property explicitly defines the name of the layer in the feature layer that is used by the survey. For more information, see the Knowledge Base article on how to author a survey that matches a feature service.
The submission_url property is the URL of the feature layer item.
You must provide the URL of the feature layer item, as shown above. A common mistake is to use the feature layer URL instead, which is not supported.
To create this URL, you must concatenate the Item ID with the portal Content Root. The example in the image above shows a link to an ArcGIS Online item; the link to the same item in a portal looks like the following:
If you need a survey that requires some but not all fields of an existing feature layer, it is recommended that you generate a survey from the feature layer (as described in the section above) and delete the questions that are not needed before publishing the survey. In this way, the form_id and submission_url properties are created automatically.
Once a survey has been created from an existing feature layer, new questions and choice list values can be added to the survey only after the corresponding field or domain is added to the feature layer. When a survey is created from a feature layer view, new questions and choice list values can be added to the survey only after the corresponding field or domain is added to the underlying feature layer and has been propagated to the feature layer view.