Enable an inbox for a census survey

Publish a survey

First, you'll publish the survey for which you want to enable an inbox. In a real-world workflow, you would probably create this survey yourself. For the purposes of this tutorial, you'll use a template survey that has already been created for you.

Note:

To learn more about creating surveys, see Convert a paper census form to a digital survey.

  1. Open ArcGIS Survey123 Connect.
    Note:

    If you don't have ArcGIS Survey123 Connect, you can download it from the Survey123 product page. Under Survey123 Connect desktop app, download the installer for the appropriate operating system. Run the installer and follow its steps to install the program.

    Next, you'll sign in.

  2. On the ribbon, click the settings button.

    Settings button

  3. Click Sign in.

    Sign in button

  4. Sign in to your ArcGIS organizational account.
    Note:

    If you don't have an organizational account, see options for software access.

    Now that you're signed in, you'll create a survey using a template already configured for use in this tutorial.

  5. Click New survey.

    New survey button

    The New Survey window appears. You'll name your survey and choose the initial design of the survey's XLSForm. An XLSForm is a type of form standard that simplifies the creation of forms, such as Survey123 surveys, in Microsoft Excel.

    You have the option to choose an XLSForm design from several locations. You'll use a design from Esri.
  6. For Title, type Zambia Population Census and add your name or initials to ensure the title is unique within your organization.

    Title for the new survey

  7. For Create a new survey from, under Esri, choose Templates.

    Esri Templates option for choosing an XLSForm design

  8. In the search bar, type Zambia. If necessary, click Zambia Census of Population and Housing to select it.

    Search results for Zambia Census

    This survey design will create a survey that you can use for housing and population censuses.

  9. Click Create survey.

    The survey is created based on the XLSForm design you chose. The XLSForm opens in Microsoft Excel, but you don't need to make any changes to it right now.

    Next, you'll publish the survey. Publishing a survey adds it as an item in ArcGIS Online. It also creates a web map and a hosted feature layer for containing the survey responses. The attribute table of the hosted feature layer uses the survey's questions as its fields. To enable the inbox for a survey, you must first create this hosted feature layer.

  10. If necessary, minimize Microsoft Excel and return to Survey123 Connect.

    Survey123 Connect displays a preview of the completed survey form. The survey includes several standard questions designed to assess population and housing.

    Preview of the survey

    The first few questions involve individual buildings. Once those questions are answered, contextual questions appear to assess the number of people living in each building and other census information.

  11. Click Publish.

    Publish button

    A window appears, warning you that once a survey is published, further changes to the survey design may result in data loss. You won't collect any data right away, so you don't need to worry about this warning.

  12. Click Publish survey.

    The survey, the hosted feature layer and a web map containing the layer are published to your account on ArcGIS Online.

  13. When publishing is complete, click OK.

Add the data

To enable the inbox for a survey, you need two things. The first is the hosted feature layer of the published survey. The second is a layer of points that correspond to the locations where surveys will be taken. In this workflow, your survey is for a population and housing census that collects information from individual buildings. To enable the inbox, you'll use a point layer of building information for the area of interest. That way, you can use the inbox to assign specific buildings to enumerators.

For the purposes of this tutorial, points representing buildings in Zambia have already been created for you. You'll add this layer and the survey feature layer you created to a project in ArcGIS Pro. Then, you'll combine the layers so that the building points have fields corresponding to the survey questions.

  1. Start ArcGIS Pro. If prompted, sign in using the same account you used to publish the survey.
    Note:

    If you don't have access to ArcGIS Pro or an ArcGIS organizational account, see options for software access.

  2. For Blank Templates, click Map.

    Map template

    The Create a New Project window appears.

  3. For Name, type Zambia Census Inbox. Click OK.

    The new project is created. It includes a blank map. You'll add the two layers you need to the map from ArcGIS Online.

  4. On the ribbon, click the Map tab. In the Layer group, click the Add Data button.

    Add Data button

    The Add Data window appears. You can add data from your project, your portal (ArcGIS Online), or your computer. First, you'll add the feature layer you created when you published the survey, which is located in your content.

  5. In the Add Data window, under Portal, click My Content.

    My Content option

    A list of folders in your ArcGIS account appears.

  6. Double-click the Survey-Zambia Population Census (Your Name) folder. Click the Zambia Population Census (Your Name) hosted feature layer and click OK.

    Zambia Population Census hosted feature layer

    The layer is added to the Contents pane, as well as three stand-alone tables that represent the contextual responses for certain building types.

    Contents pane with survey feature layer

    Nothing is added to the map, because the layer and the tables are empty until surveys have been completed.

    Next, you'll add the building points layer, which is hosted on ArcGIS Online.

  7. On the ribbon, on the Map tab, click the Add Data button. In the Add Data window, under Portal, click ArcGIS Online.

    ArcGIS Online option

  8. In the search bar, type or copy and paste Zambia Building Points owner:Learn_ArcGIS and press Enter.

    The search returns a single result.

    Zambia Building Points search results

  9. Click the Zambia Building Points feature layer to select it and click OK.

    The layer is added to the map and the Contents pane. The map is zoomed out to the extent of the world, so you'll zoom to the extent of the building points layer.

  10. In the Contents pane, right-click Zambia Building Points and choose Zoom To Layer.

    Zoom To Layer option

    The map zooms to a neighborhood in Lusaka, the capital of Zambia. This neighborhood is your area of interest for this tutorial; it is where your enumerators will be collecting census surveys.

    Map showing the building points layer

    Note:

    The color of the building points is random and may differ from the example images. Differences in color will not affect the workflow.

    Each point in the layer represents a building in the neighborhood. A census can cover a much larger area than this, but for this workflow, you'll use a relatively small dataset.

    You'll learn more about the building points layer by looking at its attribute table.

  11. In the Contents pane, right-click Zambia Building Points and choose Attribute Table.

    Attribute Table option

    The attribute table appears.

    Attribute table with the first few fields shown

    Each building point corresponds to a row in the attribute table. There is additional nonspatial information associated with each building, including an ID, the building type (residential, business, and so on), and the number of dwellings (you may need to scroll to see all of the attribute fields). This information was collected in the pre-enumeration building census.

    Note:

    If you want to perform this workflow with your own data, you need a building points layer for your area of interest with similar attribute information. If you have a layer of building footprints, which are polygons instead of points, you can convert it to a point layer using the Feature To Point geoprocessing tool. To open the tool, click the Analysis tab on the ribbon. In the Geoprocessing group, click Tools. In the Geoprocessing pane, search for and open the Feature To Point tool. For Input Features, choose your building footprints layer. For Output Feature Class, specify the name and location of the output layer. Click Run to run the tool.

  12. Close the attribute table.

Publish the building points

To use the buildings points with your survey, the building points feature class must be published and editable by other users. By default, feature classes and their attributes are only editable by the person who owns them, but you want your enumerators to be able to edit them too.

The Zambia Building Points feature class you added is hosted on ArcGIS Online, but you're not the owner (the Learn ArcGIS administrator account is). First, you'll make a copy that you own. Then, you'll publish the layer to your ArcGIS account and enable editing for members of your organization.

Tip:

Even if you're using building points that you already own, it's recommended that you make a copy of the original dataset before enabling editing. That way, if your enumerators make a mistake when editing the data, you can refer to the original dataset to fix the error.

  1. In the Contents pane, right-click Zambia Building Points, point to Data, and choose Export Features.

    Export Features option

    The Export Features window appears. This tool exports one feature class to a new feature class. It's useful for copying data.

    By default, the input layer is Zambia Building Points. The default output location is the Zambia Census Inbox geodatabase that was created along with the ArcGIS Pro project. A geodatabase is a special folder for storing geographic data.

  2. For Output Name, type or copy and paste Zambia_Building_Points_Copy.

    Export Features tool parameters

    You can create an expression to export only a subset of the data, but you want to export all of the building points, so you'll leave the expression unchanged.

  3. Click OK.

    The tool runs and a layer named Zambia_Building_Points_Copy, is added to the map and the Contents pane. The added layer is identical to the original layer. You no longer need the original, so you'll remove it.

  4. In the Contents pane, right-click the original Zambia Building Points layer and choose Remove.

    Remove option

    The original layer is removed. Next, you'll publish the copy to your ArcGIS account, the same place where you published the survey.

  5. In the Contents pane, right-click Zambia_Building_Points_Copy, point to Sharing, and choose Share As Web Layer.

    Share As Web Layer option

    The Share As Web Layer pane appears. To share your layer, you need to add the necessary metadata, such as a name, summary, and search tags.

  6. In the Share As Web Layer pane, input the following:
    • For Name, type Zambia Building Points and add your name or initials to ensure the name is unique within your organization.
    • For Summary, type Building points in Lusaka, Zambia.
    • For Tags, type Enumerators and Census, pressing Enter after each tag.

    Parameters for the Share As Web Layer tool

    You'll also share the layer with your organization. That way, members of your organization will be able to access the layer.

  7. For Share with, check the box for your organization (shown in the example image as Learn ArcGIS).

    Share with parameter set to organization

    Before you publish the layer, you'll analyze it to detect any potential problems that may need to be resolved.

  8. Click Analyze.

    Analyze button

    The layer is analyzed. There are no errors or warnings found.

    Note:

    An error message might appear saying Unique numeric IDs are not assigned. If you see this, right-click the error message and choose Open Map Properties To Allow Assignment. In the Map Properties window, on the General tab, check All assignment of unique numeric IDs for sharing web layers and click OK.

  9. Click Publish.

    The layer is published to your ArcGIS account. When the publishing is complete, a confirmation message appears saying the layer was successfully published. The message includes a link to the layer on ArcGIS Online.

  10. In the confirmation message, click Manage the web layer.

    Manage the web layer link

    A new browser window or tab opens. If you are not signed in to ArcGIS Online, you are prompted to sign in.

  11. If necessary, sign in to your ArcGIS organizational account (the same one you used for Survey123 and ArcGIS Pro).

    Go to your published layer's details page. On this page, you can manage the layer's settings and make the layer editable.

  12. Click Settings.

    Settings button on the item details page

  13. Scroll down the page. In the Feature Layer (hosted) section, under Editing, check Enable editing.

    Enable editing option

    Enabling editing adds more editing options to the page. By default, users with whom the layer is shared (in this case, members of your organization) can add, delete, and update attributes and geometry. Editors can see and edit all features. These settings allow your enumerators to add or change information based on their field surveys.

  14. Scroll down and click Save.

    Editing is enabled for the layer. Next, you'll add the newly published layer to your project in ArcGIS Pro so you can use it in subsequent steps.

  15. In ArcGIS Pro, in the Contents pane, right-click Zambia_Building_Points_Copy and choose Remove.

    You can add the layer using the Add Data button, like when you added the other layers, or you can add it from the Catalog pane.

  16. Close the Share As Web Layer pane. If necessary, on the ribbon, on the View tab, in the Windows group, click Catalog Pane.

    The Catalog pane opens.

  17. In the Catalog pane, click the Portal tab.
    Note:

    If you don't see the Catalog pane, you can open it. On the ribbon, click the View tab. In the Windows group, click Catalog Pane.

    Portal tab

    The Portal tab includes options for searching and adding content from your portal, which is where your ArcGIS account is located. The My Content tab is active by default and displays a list of your content.

  18. In your list of content, right-click Zambia Building Points Your Name and choose Add To Current Map.
    Tip:

    If you have trouble finding the layer, you can search for it using the search bar.

    Add To Current Map option

    The Zambia_Building_Points_Copy layer is added to your project. It looks the same as before, but it's now published, shared, and editable.

Append the layers

Next, you'll append the shared building points to the census survey layer. Later, when you enable the inbox, enumerators will be able to see the editable building points on their device and add census information to them directly. They'll also be able to use the attribute information in the points to determine which buildings are residential.

You'll append the layers using the Append geoprocessing tool.

  1. On the ribbon, click the Analysis tab. In the Geoprocessing group, click Tools.

    Tools button

    The Geoprocessing pane appears.

  2. In the search bar, type Append. In the list of search results, click the Append tool.

    Append search results with Append tool highlighted

    You want to append the building points to the census survey layer. To do so, you'll choose the building points as the input dataset and the census survey layer as the target dataset.

  3. For Input Datasets, choose Zambia_Building_Points_Copy. For Target Dataset, choose Zambia Population Census (Your Name).

    When chosen, the census layer's name is displayed with underscores and other special character substitutions.

    Parameters for the Append tool

    Next, you'll match the fields in the building points layer to the fields in the survey. This way, when enumerators take a census survey at a building, the survey will be populated with key information.

  4. For Field Match Type, choose Use the field map to reconcile field differences.

    List of unmatched fields

    The fields in the target dataset, your Zambia_Population_Census layer, are listed under the Field Map section. You will match fields without a defined corresponding field in the input dataset, the Zambia_Building_Points_Copy layer.

    For example, the first output field, globalid, is matched by default to the GlobalID field in the building points layer. These fields were matched because they have the same name. However, some output fields were not automatically matched; these fields are identified with a caution icon.

    Note:

    The field names listed in the field map do not match the names shown in the attribute table. The field map displays the field name, which has specific conventions and character restrictions, while the attribute table displays the field's alias, which has no character restrictions. To compare a layer's field names and aliases, right-click the layer in the Contents pane, point to Data Design, and choose Fields. The Fields view appears, showing the name and alias of each field in the layer.

  5. In the Field Map section, point to the buildtype and click the Edit Field Properties button.

    Edit button for the buildtype field under the Field Map section

    The Field Properties window appears.

  6. In the Field Properties window, under Actions and Source Fields, click buildingtype and click OK.

    The buildingtype field in the Field Properties window

    The two fields, which represent an ID number for each enumeration area, are matched.

  7. In the Append tool pane, point to occupancytype and click the Edit Field Properties button. In the Field Properties window, click occupancy and click OK.

    The fields are linked.

    Fields matched in the Field Map section

  8. Click Run.

    The tool runs and the building points are added to the census survey layer, which was previously empty. The census survey layer symbol is a red point with a yellow halo; these points appear on the map at the location of each building point.

    Map with appended building points

  9. On the Quick Access Toolbar, click the Save button.

    Save button

    The project is saved.

Enable the inbox

Now that you've appended building points to your census survey layer, you'll return to Survey123 Connect and enable the inbox. Once the inbox is enabled, enumerators taking the survey will see the building points on their device and be able to select them to complete the associated survey.

  1. If necessary, reopen your Zambia Population Census survey in Survey123 Connect.
  2. Under the survey preview, under the survey, click Options.

    Options tab

  3. For Inbox, turn on Enable Inbox.

    Enable Inbox folder option turned on

    When you enable the inbox, more options related to the inbox appear. Additionally, a warning appears, represented by a red exclamation point inside a triangle.

    The warning appeared because both the inbox and the sent box are enabled at the same time (the sent box, which saves submitted surveys on the user's device, is enabled by default). When both are enabled for a survey, refreshing the inbox does not download responses currently in the sent box. Therefore, it's recommended that you do not enable both when you intend for multiple users to continually edit and update existing responses, like your enumerators will.

    Tip:

    To learn more about the warning, click the warning button.

  4. For Sent, turn off Enable Sent folder.

    Enable Sent folder option turned off

    The warning is removed.

    Lastly, you'll change the inbox settings so that only building identified as residential will appear for enumerators. This way, enumerators will not have to sort through nonresidential buildings to find buildings where they need to take census information.

  5. For Query expression (optional), type buildtype='residential'.

    Query expression set to residential

    You're almost ready to republish your survey with the inbox enabled. Before you do, you'll make one edit to the survey's XLSForm to change the display name of survey instances that appear in the enumerator's inbox. Doing so isn't mandatory for enabling the inbox, but providing key information in the title of each survey can help your enumerators perform their tasks more efficiently.

  6. If necessary, open the survey's XLSForm.
    Note:

    The XLSForm opened by default when you created the survey. If it's closed, you can reopen it by clicking the XLSForm button.

    Because you've published the survey, there are a few rules about editing the survey's XLSForm:

    • Deleting a question from the survey's XLSForm will remove it from the survey, but it will not remove the corresponding question in the feature service.
    • You cannot add new questions that do not correspond to fields in the feature service. To add a new question, you must first edit the feature service in ArcGIS Online or ArcGIS Pro to include a new field in its table. The question you add to the survey's XLSForm must use the field name as its name parameter.
    • You can change question labels and options in the choices tab of the XLSForm, but you cannot change the field type in the bind::esri:fieldType column of the survey tab. This rule primarily prevents you from changing a question with a text answer to a question with a numeric answer and vice versa.

    These rules won't affect this workflow, but they're good to know for managing your own published surveys.

  7. At the bottom of the XLSForm, click the settings tab.

    Settings tab in the XLSForm

    This tab contains key settings about the survey. The instance_name field contains the display name of each survey. By default, the survey template you used uses the building's ID as the display name. You'll modify it to also include the number of housing units in the building, so enumerators will know at a glance how many places they will need to visit.

  8. For instance_name, replace the default text with concat("Building Number: ",${buildingid}, "; Units: ", ${numunits}).

    Updated instance_name parameter

  9. Save the XLSForm. Return to Survey123 Connect.

    Notice that when you save the form, your survey window refreshes. Next, you'll republish your survey with the inbox enabled.

  10. In the survey window, click Publish.

    A message appears, telling you the survey will be updated without affecting the existing data.

  11. Click Publish survey.
  12. Once publishing is complete, click OK.

Test the inbox functionality

You've published the survey with the inbox enabled. Next, you'll test the inbox functionality by taking a sample survey using the ArcGIS Survey123 field app.

  1. Go to the Survey123 product page. Click Go to download options and under Get the ArcGIS Survey123 field app, click the download link for your computer's operating system or go to your device's app store.
  2. If installing the field app on your computer, run the downloaded installer and follow its instructions to install the field app. If installing the field app on your mobile device, install it from the device's app store.
  3. On your computer or device, open the ArcGIS Survey123 field app. Sign in using the same ArcGIS account you used to publish the survey.

    First, you'll download the survey you published.

    Note:

    Some steps and example images may differ slightly depending on the device you're using.

  4. On the ribbon, click the button representing your account. Click Download Surveys.

    Download Surveys button

    A list of surveys shared with your organization appears.

  5. For your Zambia Population Census survey, click the download button.
    Tip:

    If you have difficulty finding your survey, you can search for it.

    Download button

    The survey is downloaded.

  6. On the ribbon, click the back button.

    Back button

  7. In the gallery of downloaded surveys, click your Zambia Population Census survey.

    An information page for the survey opens, which includes metadata that was added as part of the template you used.

  8. Click Inbox.

    Inbox option

    The inbox appears. By default, the inbox is empty.

  9. Click Refresh.

    Refresh button

    The inbox populates with a list of buildings. The buildings are labeled with both the building number and the number of housing units because of the changes you made to the instance_name parameter in the XLSForm.

    Inbox populated with building information

  10. Click Map.

    Map tab

    The buildings are displayed on a map. Because of the building labels, it may be difficult to see the buildings at the default zoom level.

  11. Zoom in until you can see individual buildings. Click any building.

    The survey associated with that building appears. It is populated with the information from the building points layer that you appended to the survey, such as the building type, condition, and occupancy type.

    Survey populated with information

    Enumerators can still fill in information about their name and the number of people who are residents of the household. Additionally, they can update the populated values if those values have changed since the pre-enumeration census.

  12. Optionally, fill in the empty fields and click the check mark to submit the survey. In the Survey Completed window, click Send now.

    When you submit a completed survey, the point is removed from the inbox.

Assign a subset of buildings to survey

You're now familiar with how the inbox works. As a final part of the workflow, you'll change the inbox's settings and alter the building point data to assign a subset of buildings to a specific enumerator. When that enumerator accesses the inbox, they'll only see buildings assigned to them. This workflow is useful for managing your enumerators in the field.

  1. In Survey123 Connect, click the Options button. For Query expression, delete the original expression and type enumerator=${username}.

    Query expression changed to enumerator=${username}

    This expression will filter the inbox to only show records where the Enumerator Username field is set to the enumerator's user name. For example, an enumerator with a user name of Enumerator 1 would only see records where Enumerator 1 is the value in the Enumerator Username field.

  2. Click Publish. In the Publish Zambia Population Census window, click Publish survey.
  3. When publishing is complete, click OK.

    The survey is republished with the new query expression. However, as you saw when you looked at the building points attribute table in ArcGIS Pro, the Enumerator Username field is empty by default; enumerators would normally be expected to type their own user name when taking the census survey. You'll edit the census survey feature class in ArcGIS Pro to display an enumerator's user name.

  4. If necessary, reopen your Zambia Census Inbox project in ArcGIS Pro.

    You'll create a map in the project and add the updated census survey layer to it.

  5. On the ribbon, click the Insert tab. In the Project group, click the New Map button.

    New Map button

    A new map is created and added to the project. Next, you'll add the updated census survey layer to it.

  6. In the Catalog pane, in the Portal tab, double-click the Survey-Zambia Population Census folder. Right-click your Zambia Population Census layer and choose Add To Current Map.

    Add To Current Map option

    The layer is added to the map, although the map extent does not change.

  7. In the Contents pane, right-click Zambia Population Census (Your Name) and choose Zoom To Layer.

    The points are displayed with the same red point symbol as before, when you appended the building points to the census survey layer. Next, you'll select a subset of the building points. The points you select will be the ones you assign to your enumerator.

  8. On the ribbon, click the Map tab. In the Selection group, click the Select By Rectangle button.

    Select By Rectangle button

  9. On the map, draw a rectangle around some of the northernmost points. (For this workflow, the exact points you select don't matter, as long as you don't select all or none of the points.)

    Map with selection rectangle drawn around some of the points

    The points within your rectangle are selected and highlighted. Next, you'll calculate the Enumerator Username field so that the selected points have the username of the enumerator to which they are assigned.

  10. In the Contents pane, expand Zambia Population Census (Your Name). Right-click Zambia_Population_Census_Your_Name and choose Attribute Table.

    Open table

  11. In the attribute table, right-click Enumerator Username and choose Calculate Field.

    Calculate Field option

    The Calculate Field tool appears. This tool calculates the value for a field based on an expression you create. Like most geoprocessing tools, this tool will only run on selected features if a selection has been made, meaning only the building points you selected will have their field calculated.

    You'll calculate the field to contain your ArcGIS account user name. That way, when you access the inbox, you'll only see the building points with your user name in their attribute data. In a real-world workflow, you would use the username of your enumerator instead.

  12. In the Calculate Field tool, for Expression Type, choose Python.

    Expression Type parameter

  13. For enumerator =, type your ArcGIS organizational account user name (the same one you used to sign in) in double quotation marks.
    Note:

    The example images use a fake user name. Make sure that you're using your own user name.

    Expression with example user name

  14. Click OK.

    The field is calculated. When it's finished, selected records all have your user name as the value in the Enumerator Username field.

    Tip:

    You can verify that the field was calculated correctly by scrolling through the attribute table until you see the selected records.

    Selected records with the example user name

  15. Close the attribute table. Save the project.

    Next, you'll confirm that you can only access the selected records in the Survey123 field app. You'll refresh the survey to ensure you have all of the latest changes on your device.

  16. If necessary, open the Survey123 field app and go to your list of surveys.

    You receive a notification that there are updates available for your survey.

  17. Click Updates available: 1.

    Updates available button

    Note:

    If you don't see the Updates available notification, you can manually update your survey. On the ribbon, click your username button and click Download Surveys.

  18. For your Zambia Population Census survey, click the refresh button.

    Refresh button to update the survey

    Updates are downloaded for the survey.

  19. Return to the list of your surveys and click the Zambia Population Census survey. Click Inbox and click Refresh.

    The list of surveys in the inbox is refreshed; now, only the surveys you selected and assigned to yourself are listed.

  20. Click Map to confirm only the surveys you selected are shown.

In this tutorial, you enabled the inbox feature for a census survey. First, you published the survey. Then, you appended a layer of building points to the survey's feature class. You changed the settings for the inbox and tested the inbox functionality in the Survey123 field app. You also used the inbox to assign a subset of buildings to a specific enumerator.

The inbox is useful for managing mobile workers and streamlining the collection of data in the field. You can use it not just in a census workflow, but in any workflow that involves updating information about an existing feature layer. For instance, you can use it for the inspection of utilities or the maintenance of infrastructure. Try performing the workflow with your own survey and point data.

You can find more tutorials in the tutorial gallery.