Use Survey123 with existing feature layers

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.

Note:

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.

Repeats cannot reference related layers or tables unless the child layer or table uses a GUID field for the relationship. Although not a requirement in versions of ArcGIS Server supported by Survey123, best practice is to use a GUID field for the relationship in the child layer.

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 two 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.

Note:

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. 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 the Author a survey that matches a feature layer-section below.

Note:

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.

Submission URL in the Survey123 form
Tip:

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:

https://<host>:<port>/arcgis/sharing/rest/content/items/21a6c530b31a4523bdff7gg94c9c5d9a

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.