[Last updated October 11, 2019]
[Last updated March 15, 2021]
Typically, when you publish a new survey with Survey123 Connect or the web designer, a new feature service is created on your behalf. Data submitted with your survey will be stored into that new feature service. We built Survey123 this way because we wanted to simplify as much as possible the process of building new surveys. We did not want people having to worry about feature classes, domains and all of that. Instead, we took an approach where the focus is on adding questions and rules to a form, and leave the creation of the data model to the software.
There are some valid cases however, where you may want to publish a survey that works on top of an existing feature service; In this blog post I will describe how this can be done.
Why would you publish a survey on top of an existing feature service?
There are multiple scenarios where building a survey on top of an existing feature service makes sense. I will describe in more detail some of them:
Pre-requisites
Survey123 can only work against feature services where the supportsApplyEditsWithGlobalID property is set to true. There is a detailed explanation of how to meet this requirement in the https://community.esri.com/groups/survey123/blog/2018/07/17/how-to-turn-supportsapplyeditswithgloabl... blog post, but in short here what you will need:
How to create a survey on top of an existing feature service?
You can build a survey on top of an existing feature service using Survey123 Connect. First. you will need to be logged-in against ArcGIS Online or your own ArcGIS Enterprise instance. Then simply click on New Survey and select the Feature Service option.
Once you select the Feature Service option, the gallery on the right will show you every feature service shared with your account. For ArcGIS Online, this will include all hosted feature services and in ArcGIS Enterprise, all hosted feature services plus all federated feature services shared with you.
If you want to use a service from an ArcGIS Server instance that is not federated with Portal for ArcGIS, then you will need to follow instructions in this KB article to register your service in your portal through a feature layer item. Otherwise, your service will not be shown in the gallery.
Ok, so next you need to select the feature service of your interest and give your survey a name. Once you click on Create Survey, Survey123 Connect will look into your feature service, checking all fields, related tables and geodatabase domains. A new XLSForm will be created for you as a starting point for your survey. I will call it the initial XLSForm design.
Understanding the initial XLSForm design
In the next few sections I will describe the rules followed by Survey123 Connect to generate the initial XLSForm design. Understanding these rules is important, because you will often want modify the initial XLSForm to tailor the user experience of field users using your survey.
One question per feature layer field:
Other than a few exotic exceptions, that I will describe later, Survey123 Connect will add a new question to your initial XLSForm design for every field in the first layer of your feature service. The questions will be added to the survey XLSForm worksheet in the same order as fields appear in your feature layer. You can reorder the questions in your survey and you can also remove any questions you may want to hide.
Reordering questions can be very handy, because the order of fields in a table may not respond to the logical order in which you want people to enter data in your form. Removing questions in the XLSForm can also be useful, because you may have fields in your feature layer that you do not want to expose to users. Think of internal fields that people in the back-office will use but that are not meant to be visible to field users for example.
XLSForm Question types:
The initial XLSForm design assigns XLSForm question types based on the corresponding feature layer field type, according to the following table:
esriFieldTypeInteger | integer |
esriFieldTypeDouble | decimal |
esriFieldTypeString | text |
esriFieldTypeDate | datetime |
esriFieldTypeGeometry (point) | geopoint |
esriFieldTypeGeometry (polyline) | geotrace |
esriFieldTypeGeometry (polygon) | geoshape |
esriFieldTypeGUID | text |
There are some notable exceptions to the rule above.
The correspondence of Esri field types to question types in XLSForm, as described above, is a best guess to ensure data consistency. That is, if you were to publish the survey, you are guaranteed to be able to submit data to all fields in the feature service. However, you may want to adjust the XLSForm types depending on your needs. For example:
One key concept to remember is that the XLSForm question type fundamentally defines the type of user input that will be presented in the form. As long as the input captures a data type that is compatible with the corresponding target feature layer field, you are fine. For example: Do not expect the calendar control exposed by a date XLSForm question to generate data that is compatible with a field of type decimal. Now, if you feel like you can accelerate data capture using a barcode question against a string field, you can replace the initial text type of question with a barcode question because barcode question types will always return an output that can be stored as a string. You can also use the appearance XLSForm column to refine the user input experience.
XLSForm bind::esri:fieldType and fieldLength:
If you look carefully at your XLSForm, you will also note that Survey123 Connect added in the bind::esri:fieldType column the exact Esri data type found for fields in your feature layer. The bind::esri:fieldLength column will also contain the length originally set to your feature layer fields.
You should never change the esri:fieldType, because they are defined by the feature layer and Connect will not be able to change your layer.
You could change the length, as long you make it shorter. Making the length shorter in XLSForm allows you to limit the user input. For example, if your field has a length in the feature layer of 200 characters but you want to limit the user input from your survey to 5, simply change the bind:esri:fieldLength value to 5. You are not allowed to specify a fieldLength in your XLSForm that exceeds the actual length of the field in your feature layer.
You will rarely have to change the bind::esri:fieldLength and bind::esri:fieldType columns. If you do, you may trigger an error when attempting to publish the survey. The reason is that Survey123 Connect has a built-in check to ensure that a published survey is compatible with the underlying schema of your feature service. If the schema are not compatible, then you will not be allowed to publish the survey. Tinkering with the bind::esri:fieldLength and in particular with bind::esri:fieldType can easily result on schema inconsistencies.
Question Names and Labels:
The XLSForm name column reflects the exact field names found in your feature layer. You cannot change the values in this column. The label column is populated using the field name alias from your feature layer. You can do whatever you want with the label column (except leaving it empty). You may want to rephrase questions, embed html formatting etc, etc
Repeats (related tables):
In the event that the first layer in your feature service is related to other layers or standalone tables, you will see the presence of repeats in the XLSForm. In Survey123 we model related geodatabase tables/layers as repeats. The name of the repeat will be defined by the table name of the related table or layer and cannot be changed. The label of the repeat can contain any text you like.
Within the XLSForm repeat block, you will find questions corresponding to the fields found in the related child table. The rules for how questions are added within a repeat are exactly the same as for questions in the main feature layer. The rules for changing question types, labels etc as well as for removing or reordering them are the same too. Just be aware you cannot take questions outside of the repeat (removing them is fair game, but not to take them out of the repeat block and into the main block of the form)
Select_ones:
I want to add a few notes on how select_one questions behave. In short, every time a field in your feature service uses a coded value domain, a new select_one type of question is created. The coded value domains are matched by a corresponding XLSForm list in the choices worksheet. You are free to reduce the number of choices in the list if that makes sense for you. You can also change the labels in the list as you see fit.
The values in the name column of the choices worksheet need to remain unchanged because otherwise, you will be adding data into your feature service outside the valid values set by your geodatabase domain.
Range domains are modeled as range questions in XLSForms.
Geodatabase subtypes and contingent values are ignored by Survey123, although you can use cascading selects to model them.
Other XLSForm columns and question types:
As far as the survey worksheet in your XLSForm, columns and question types other than the ones described above will not be used. That is, the default, calculation, constraint, relevant columns etc will be empty. Question types such as groups, notes or calculates will also never be present in the initial XLSForm design. Now: you can, and should, use those extra columns and question types as appropriate to build a great data capture experience. For example:
The initial XLSForm design is just that: a starting point. Take pride of your surveys and transform flat GIS data models into beautiful smart forms.
Once you are happy with your design, you will proceed to publish your survey. When publishing, no new feature service will be created for your form. Instead, the feature service you selected will be referenced by your survey.
Settings worksheet:
The settings worksheet of the initial XLSForm contains two key pieces of information:
While you often may not want to change the submission_url, there is one use case where changing the form_id is very handy. Think for example, that you want to create a survey on top of a related standalone table. For clarity, lets think of a feature service with parcels (polygons) and their related assessments. You may not want to build a survey to edit the parcels, but you may want to create one to create the assessments. Typically, when you get the initial XLSForm design, you will have questions in your survey for all the fields in the parcels layer and then a repeat group, with all questions in the related assessment table. This is only because in a feature service, typically the layer with geometries (parcels in our case) goes first, and then the related tables. To create your parcel assessment survey you will delete all questions corresponding to the parcels layer from your survey and then take the name of your assessments repeat and put it into the form_id setting. Finally you will delete the begin_repeat and end_repeat rows in your survey.
To ensure that assessment data is properly attached to the corresponding parcel, it is important that in your survey you preserve a question to enter the unique identifier of the parcel. You will need to know what field in the child assessment table is used for the geodatabase relationship.
Limitations when working with Repeats in your XLSForm:
Mapping the ArcGIS geodatabase model into an XLSForm is possible to some extent, but there are some limitations to bear in mind. In the case that you are working with existing feature services published from ArcGIS Desktop, there are chances that you could run into some situations where you simply cannot build a survey on top of a feature service, or at least not the exact survey that you had in mind. The truth is that you can actually build surveys pretty much on top of any feature service, except when working with related tables. Lets get into the details:
Some tips and other things to be aware of:
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.