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 your survey. Alternatively, you can choose to associate your survey to an existing feature layer.

Prepare a feature layer

To use a feature layer with Survey123, it should be a hosted layer from ArcGIS Enterprise or ArcGIS Online, or a service from ArcGIS Server (10.4 or later) that is federated with Portal for ArcGIS.

Note:

To work with nonfederated feature services, some additional configuration is required, as you will need to manually create a feature layer item in your ArcGIS organization that represents the service. For details, see this 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 parent layer.

If you plan to edit your surveys, ensure that either your feature layer allows null values or your 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.

There are two additional capabilities that must be set to true for the feature layer:

  • supportsAttachmentsByUploadId—This capability should be automatically turned on if attachments are enabled on the feature layer. It allows the app to upload all attachments associated with a survey before attempting to submit the survey. If any of the attachments fail, the entire survey submission will roll 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 forcing 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 easiest way to do this is to enable sync when publishing your feature layer.
  • The data cannot be versioned.
  • Global IDs must exist in a feature layer or table before enabling attachments on either.
  • If your feature layer contains m-enabled layers, editing without m-values must be enabled.

For more information on how to support editing in your feature layer, see supportsApplyEditsWithGlobalIds in Layer (Feature Service) of 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.

Generate a survey from a feature layer

The quickest way to create a survey that is linked to an existing feature layer is to generate the survey from the feature layer in ArcGIS Survey123 Connect.

In Survey123 Connect, choose New survey, sign in to your ArcGIS organization, and select the Feature service category. Browse to and select the desired feature layer and click Create survey. An XLSForm will be generated from your 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 group them into sections.

Surveys cannot be generated from public layers. In the event that the feature layer you've created your survey from has more than one layer, the survey will be generated based on the first layer. To base a survey on another layer of a feature layer, you must create the survey manually and use the form_id and submission_url properties on the settings tab of your spreadsheet. The process to do this is described in the section below.

Note:

If the survey you're creating requires image, audio, or file questions, these will need to be added to your survey manually. After generating the survey, open the spreadsheet and add the questions. For more information, see Media. The feature layer must also have attachments enabled.

Author a survey that matches a feature layer

It is also possible, but not recommended, to author a new survey that matches an existing feature layer. If you require a survey that does not include all the fields of an existing feature layer, it is recommended to generate a survey from the feature layer (as described above) and delete any of the questions that are not needed before publishing the survey. You will also need to use the submission_url property on the settings tab of your spreadsheet to define a link between your survey and the feature layer's item in your portal or ArcGIS Online.

Submission URL in the Survey123 form
Tip:

You need to 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.

You also need to fill in the form_id property, a value that explicitly defines which layer is used by the survey. For details, see this knowledge base article on how to author a survey that matches a feature service.