MobileMap: Download Parameters
- Kerry Halligan
- Nathan Meade
- Finn Halligan (Unlicensed)
Differences Between MobileMap 4.x and MobileMap 5.x for Download Parameters
Download parameters can be set at any point in time in MobileMap 4.x and they will be applied on the next data download. In MobileMap 5.x, these parameters must be set before geodatabase generation and cannot be changed after this step. For the lifespan of a generated geodatabase, it will only be able to download features with the parameters that were set originally when the geodatabase was generated. If a change is needed to the download parameters, a new database must be generated. See section MobileMap 5.x for more details.
Overview
Download parameters are a useful way to limit the feature service data that are downloaded to MobileMap. This can be helpful on large projects where downloading all data (spatial and tabular features) in all layers may cause a performance problem, produce a cluttered map, or simply result in the download of unnecessary or irrelevant data downloads.
The maximum number of features that can be successfully downloaded and used within MobileMap varies widely by device performance, Wi-Fi speed and the size and complexity of the data being downloaded. For example, polygons can have generalized geometries with a dozen or less vertices or may be very dense with hundreds (or more) vertices. The number of features and vertices (for lines and polygons) will impact both the download time and the performance when loading and displaying features on a map. For non-spatial features (e.g., Trees, Logs), users have generally found that downloading 5,000 to 10,000 features is a good upper limit. When more features are downloaded at one time, especially over slow Wi-Fi connections, the download can timeout and result in an incomplete download. Download parameters, combined with carefully constructed data models and inherited fields settings can help to ensure that appropriately sized data subsets.
Use of download parameters can also be helpful when you want to restrict data download to only the data that is relevant to specific users. An example of this is when an auditor needs to download all the data that was collected by a particular cruiser, but does not want to download any data from other cruisers. Another example is where a team wants to download all of the data for a particular project (or client, region, cover type, etc.) rather than all of the data in the feature service.
MobileMap 4.x
(For MobileMap 5.x: MobileMap: Download Parameters | MobileMap 5.x)
Setting Download Parameters
To specify download parameters, open the Edit Download Parameters tool (Actions>Edit Download Parameters). You will see a table with a row for each of the layers in the service(s) that have been selected and initialized. The checkbox indicates that data should be downloaded for that layer. If data should be filtered or limited when downloading, specify the ‘Where Clause’. The Where Clause is the logic that will be used by MobileMap when it requests data for download. It follows the syntax used by the ArcGIS REST API’s where clause (https://developers.arcgis.com/rest/services-reference/query-feature-service-layer-.htm#GUID-62EE7495-8688-4BD0-B433-89F7E4476673).
In the screenshot below, the user has decided to NOT download data for any of the generic feature layers because they do not wish to clutter their map with ad hoc data collected by other users. They have also decided on ONLY download data within the ‘NW’ Region. This assumes that there is a field named ‘Region’ and that ‘NW’ is a valid value.
The where clause operates on the database field names (not aliases) and the stored values (not descriptions in the case of Coded Value Domains). For example if a field is named ‘Region', but the Alias is ‘Inventory Region’, use ‘Region’. Similarly, if the Region field uses a Coded Value Domain with the codes ‘NW’, ‘SW’, etc. and descriptions of ‘Northwest’, ‘Southwest’, use the code 'NW’.
Computers have a hard time comparing two decimal numbers for equality due to the well known round-off error problem (Round-off error ). For this reason, avoid where clauses that use the equals sign and a specified value. Instead, use > and < to find matches. Example: Acres > 39.99 AND Acres < 40.01 will find Stands that are 40 acres.
Text values need to be surrounded in single quotes. Note that on many android devices there are two single quote characters on the software keyboard. One that is vertical and another that is rotated. Use the vertical one, not the rotated one.
Download Parameters Logic
When a download parameters are set, they replace the default where clause of 1=1 (always true, thus all relevant records are downloaded). To avoid redundant data downloads, however, MobileMap also applies a filter on the last modified date for each record. This ensures that MobileMap only downloads those records that have been created or updated since the last MobileMap download from this device. For example, if MobileMap downloaded data at noon yesterday and there is a download parameter of Region='NW', MobileMap will query the server using the following logic: select all features that were created or edited after noon yesterday and where the value of the Region field is 'NW'.
Changing Download Parameters
If you decide to change download parameters AFTER data have been downloaded to your device, it is important to understand how MobileMap will request data from the service. If a download parameter of Region='NW' is used to download data yesterday at noon, then is changed to Region='SW', MobileMap will query the server using the following logic: select all features that were created or edited after noon yesterday and where the value of the Region field is 'SW'. This will NOT download data prior to noon yesterday where the value of the Region field is 'SW'. If you want to get ALL data where where the value of the Region field is 'SW', it is necessary to reset the last download date. To do this, press the RESET button on the Edit Download Parameters tool. While this approach will work, a user will now have some data where the value of the Region field is 'NW' and some data where the value of the Region field is 'SW'. Subsequent downloads will only download data where the value of the Region field is 'SW'. This can create confusion, because some data are up-to-date (SW) while others are not (NW). Therefore, the typical and recommended approach to changing download parameters is to complete the following steps:
Upload all data from your device to ensure that no data are lost in step 3 below
Change your download parameters to the new desired parameters
Re-initialize your database
Download data
Verify that you recieved the data you expect based on your download parameters. If you need to adjust, repeat steps 2-4 above
Common Where Clauses
Where Clause | Description | Example |
|---|---|---|
field_name='text_value' | Downloads data where the text value matches the value in single quotes within the specified field | Region='NW' |
field_name=numeric_value | Downloads data where the numeric value matches the specified value within the specified field | Site_Index=2 |
field_name='text_value' AND field_name=numeric_value | Combination of the two examples above using the ‘AND’ operator. This will only download data where both conditions are met for a single feature | Region='NW' AND Cruiser_ID='ABC' |
field_name='text_value' OR field_name=numeric_value | Similar to above but using ‘OR’. This will download any feature that meets either criteria | Cruiser_ID='ABC' OR Contractor_ID='XYZ' |
field_name IN ('text_value1','text_value2') | Allows for selection of multiple values within a list. Similar to using the OR operator on a single field. | Status IN ('Cruised','Checked')
|
MobileMap 5.x
Download parameters for MobileMap 5.x are defined when creating the offline geodatabase. These parameters cannot be changed after creating the geodatabase. Therefore, if you need to change your download parameters, you will need to generate a new geodatabase.
Setting Download Parameters
To specify download parameters, a Feature Service needs to be selected for downloading (Actions menu → Configure Offline Geodatabase). Once a Feature Service has been selected, tap the download button to display the “Configure Offline Geodatabase Parameters” screen. This will display a table with a row for each of the layers in the service. The checkbox indicates that data should be downloaded for that layer. If data should be filtered or limited when downloading, specify the ‘Where Clause’. The Where Clause is the logic that will be used by MobileMap when it requests data for download. It follows the syntax used by the ArcGIS REST API’s where clause (Query (Feature Service/Layer) | ArcGIS REST APIs | ArcGIS Developers ).
In the screenshot below, the user has decided to NOT download data for any of the generic feature layers because they do not wish to clutter their map with ad hoc data collected by other users. They have also decided to ONLY download data within the ‘NW’ Region. This assumes that there is a field named ‘Region’ and that ‘NW’ is a valid value.
The where clause operates on the database field names (not aliases) and the stored values (not descriptions in the case of Coded Value Domains). For example if a field is named ‘Region', but the Alias is ‘Inventory Region’, use ‘Region’. Similarly, if the Region field uses a Coded Value Domain with the codes ‘NW’, ‘SW’, etc. and descriptions of ‘Northwest’, ‘Southwest’, use the code 'NW’.
Computers have a hard time comparing two decimal numbers for equality due to the well known round-off error problem (Round-off error ). For this reason, avoid where clauses for decimal fields that use the equals sign and a specified value. Instead, use > and < to find matches. Example: Acres > 39.99 AND Acres < 40.01 will find Stands that are 40 acres.
Text values need to be surrounded in single quotes. Note that on many android devices there are two single quote characters on the software keyboard. One that is vertical and another that is rotated. Use the vertical one, not the rotated one.
Common Where Clauses
Where Clause | Description | Example |
|---|---|---|
field_name='text_value' | Downloads data where the text value matches the value in single quotes within the specified field | Region='NW' |
field_name=numeric_value | Downloads data where the numeric value matches the specified value within the specified field | Site_Index=2 |
field_name='text_value' AND field_name=numeric_value | Combination of the two examples above using the ‘AND’ operator. This will only download data where both conditions are met for a single feature | Region='NW' AND Cruiser_ID='ABC' |
field_name='text_value' OR field_name=numeric_value | Similar to above but using ‘OR’. This will download any feature that meets either criteria | Cruiser_ID='ABC' OR Contractor_ID='XYZ' |
field_name IN ('text_value1','text_value2') | Allows for selection of multiple values within a list. Similar to using the OR operator on a single field. | Status IN ('Cruised','Checked')
|
Completing the Process
To complete the process tap the ‘download’ button:
This will initiate the generation of the offline geodatabase. MobileMap will create a new offline geodatabase using the download parameters that have been set. When this process completes, a popup message will display the results.
If the download parameters need to be changed in the future, the user will have to repeat the full process (generate offline geodatabase) above by doing the following:
Sync data to make sure all necessary data have been saved to ArcGIS
Generate offline geodatabase
Select the feature service
Optionally apply download parameters
Generate offline geodatabase