The on-demand workflow allows your field workers to define an area of a map and control the map content to be taken offline. Your app can specify parameters and overrides to control the map's area of interest, max and min scale, filter features, include attachments, determine editing characteristics, and many other aspects of the map content. The aim of these parameters is to ensure that only essential map content is taken offline. Here are the steps for this on-demand workflow:
- Create an offline map task
- Examine the map's offline capabilities
- Create parameters to specify the map content
- Create a job to generate an offline map
- Run the job
To take a map offline on-demand, use ArcGIS Online or ArcGIS Enterprise 10.3 or later. You must ensure that all services used in the web map are enabled for offline use.
Create an offline map task
Create an AGSOfflineMapTask from either an online map or its portal item.
Examine the map's offline capabilities
We recommend that you check that all the layers and tables in the map can be taken offline by examining the map's offline capabilities. It helps to determine which layers or tables are missing, because the map may not be as complete as when originally designed.
Obtain the AGSOfflineMapCapabilities object by calling the getOfflineMapCapabilities method on the offline map task . The hasErrors boolean value will indicate whether at least one layer or table cannot be taken offline. Examine the layerCapabilities and tableCapabilities to determine which layer or table cannot be taken offline, and why.
Although this step is optional, we recommend that you examine these capabilities to ensure that the map contains the appropriate layers and tables.
Create parameters to specify map content
When you take a map offline, you want the map to contain all the content that is relevant to the field worker. Be aware, however, that the size of the map will directly impact the time it takes to generate the offline map and download it to your device. You can control this size by specifying the map's area of interest to cover just the geographical area that the field worker needs.
- Create the AGSGenerateOfflineMapParameters by passing an area of interest to the defaultGenerateOfflineMapParameters method on the AGSOfflineMapTask.
- Obtain and examine the returned parameters. These default parameters represent the advanced offline settings configured by the web map author.
- To override any of these default parameters see Advanced parameters. For example you can, set the max and min scale, use a local basemap, or set a definition expression on features.
Instead of obtaining the default set of AGSGenerateOfflineMapParameters you could construct them manually. The author of the web map can recommend how data is downloaded to offline devices, and subsequently updated, by adjusting the map's advanced offline settings. See Take web maps offline. You can access these advanced settings from the map's OfflineSettings. They provide options for:
- working with feature attachments
- synchronizing edits
- downloading a basemap or using one which is already on the device
Create a job to generate an offline map
To generate and download the offline map, you must create a AGSGenerateOfflineMapJob by providing the AGSGenerateOfflineMapParameters to the generateOfflineMapJobWithParameters:downloadDirectory:() method on AGSOfflineMapTask. You must provide a directory on the device to store the offline map. If this download directory already exists, it must be empty. If the directory doesn't exist, it will be created by the job.
If you want to control the individual layer and table content, you also need to provide the AGSGenerateOfflineMapParameterOverrides as well as the AGSGenerateOfflineMapParameters to the generateOfflineMapJobWithParameters:parameterOverrides:downloadDirectory:() method on AGSOfflineMapTask. For more details see Create offline map parameter overrides.
Note:Note that the job will behave the same whether it was created using just the AGSGenerateOfflineMapParameters or using both the AGSGenerateOfflineMapParameterOverrides along with the AGSGenerateOfflineMapParameters.
See the Tasks and jobs topic for more details on how to work with jobs in general.
Run the job
To generate the offline map and download it to your device, start the AGSGenerateOfflineMapJob. At completion, the job will return an instance of the AGSGenerateOfflineMapResult. If at least one table or layer failed to be taken offline, the hasErrors property will be true. In this case you should examine the layerErrors and tableErrors dictionaries to identify the problem.
If the ContinueOnErrors property of the AGSGenerateOfflineMapParameters has been set to false, the job will terminate if any layer or table fails to be taken offline.
If you want to display the map immediately, pass the AGSGenerateOfflineMapResult.offlineMap to the map view.
Offline maps created by the on-demand workflow are stored in an unpacked mobile map package. When your app goes into the field, you will need to open the map directly from this mobile map package downloadDirectory stored on your device. See Open an offline map for more information.
After you have obtained the AGSGenerateOfflineMapParameters, you can set any of their properties to control the offline map content. For example:
- The map's max and min scale
- Whether basemaps are included in the map
- Whether online services are retained in the map
- Whether to allow synchronization of the map's geodatabases
- Whether to apply definition expression filters
- Whether to return all rows from a related table
- Whether to continue downloading the map if a single layer fails to be taken offline
- Including feature attachments
- Whether only the schema is provided for editable layers
- Update or replace the map's metadata
If your use-case requires you to have more control over how individual layers and tables are downloaded, you can use the AGSGenerateOfflineMapParameterOverrides to make those specific adjustments. Follow the steps outlined in Create offline map parameter overrides.
Tiled layers are composed of many tiles at different levels of detail. For a particular area of interest, the amount of space, generation time, and download time will increase significantly with every increased level of detail. It's strongly recommended that you only download the levels of detail that are relevant for your app. You can control this by setting the minimum and maximum scale parameters (minScale and maxScale). If possible, choose a maximum scale that is not too “zoomed in”, as this will generate a large number of unnecessary tiles. Each service has a limit to the number of tiles that can be taken offline. It's recommended that you always set a scale range to avoid hitting this limit.
On-demand workflow will honor the scale range of a tiled layer as specified by the web map. This behavior helps to ensure that only tile data required by the offline map will be downloaded.
For example, if the web map contains a tiled layer that is set to a min scale of 1:1,000,000 and a max scale of 1:10,000, these values will be applied to the scale range requested by the user. If a user requests the data with a scale range of 1:900,000 to 1:5,000, the minimum range of 1:900,000 (min scale defined in the user's parameters) to 1:10,000 (max scale defined on the web map) will be downloaded. If the user's parameters request the default scale values of 1:0, then the range from the web map will be applied.
Include a map's basemap
The author of the web map can define whether the map:
- The basemap defined by the web map
This is the default situation and ensures that a tile package is downloaded as part of the mobile map package.
- A tile package that is already on the device
The tile package must be downloaded or copied onto the device and can be located using an actual file path on the device or a path that is relative to the mobile map package. You must ensure that the tile package covers the areas required by your map area. The benefits of this option are that the mobile map package file will be smaller, the download time may be faster, and you can use the tile package in many different maps and apps.
To use the tile package on your device, you must set the referenceBasemapDirectory to the directory that contains the tile package. We recommend that you confirm that the tile package file, referenceBasemapFilename, exists on the device before running the AGSGenerateOfflineMapJob. This job will add the tile package, as a basemap, to the offline map.
If this tile package has a different spatial reference to your online map then the offline map will use the spatial of the tile package.
- No basemap
If only want to take the operational layers offline you can programmatically exclude the basemap. To do this set the includeBasemap property to false. In this case the AGSGenerateOfflineMapJob will not download any layers included as part of the map's basemap. This task will not use the local tile package, even if you have specified one.
Retain online services
Live, online services are supported in offline maps. You can now take a map offline that has a mix of local on-device content as well as live, online service content (such as weather or traffic information). When network connectivity is available, your app users can utilize these live online services, but if there is no connection, users can keep working with their local content.
A value of include for OnlineOnlyServicesOption means that any data that cannot be taken offline will be accessed via the URL in the offline map. Choosing this option means that your offline map will retain all of the information from the original web map, but it will require a network connection and may require authentication.
Manage synchronization of the map's geodatabases
Typically, the updateMode on the AGSGenerateOfflineMapParameters is set to syncWithFeatureServices. This mode allows you to synchronize any geodatabase changes with their online feature services.
If you want to avoid receiving any geodatabase updates, set the updateMode on the AGSGenerateOfflineMapParameters to noUpdates. This disables data synchronization on the map’s geodatabases and prevents the corresponding feature services from creating synchronization replicas. The benefits of this option are that the burden on the feature server is reduced and you will not need to unregister geodatabases when they are no longer required.
Apply feature layer definition expression filters
When taking a map offline, the AGSGenerateOfflineMapJob will apply the feature layer's definition expression by default. Applying the definition expression may reduce the number of features taken offline for display and sync. If you do not want to apply the definition expression, then set the boolean value of IsDefinitionExpressionFilterEnabled to be false.
Return all rows from a related table
If a map contains a layer or table that has a relationship with another table then you can choose to download all, or only the related rows from the destination table. The default is to download only the related rows. If you want to return all rows then you must set the value of the destinationTableRowFilter to be AGSDestinationTableRowFilterAll.
If the table is not the direct destination of a feature table, or it is a standalone table, or it is the source of a relationship then all rows are returned.
For more information, see Essentials of relating tables.
Continue downloading the map if a single layer or table fails
By default, the AGSGenerateOfflineMapJob will continue to take layers and tables offline even if a layer or table has failed. While this ensures that the map is taken offline, there can be missing data. When this job completes you should examine the job's result (discussed under Run the job) to identify if and why any layers have failed. At this point you can decide whether to continue working with the map.
If you want the job to stop immediately, if a layer or table fails to download, then set the ContinueOnErrors property to be false. In this case if a map is successfully taken offline it will contain all of its layers and tables.
The failure to take a layer or table offline may be due to an intermittent network connection, loss of the service or an unsupported layer type.
Inclusion of feature attachments
Some feature services can add attachments (pictures, videos, and other documents) to individual features. Because these files can be large, you should consider your app's offline workflow to determine whether the attachments are needed by the app, and whether attachments need to be synchronized with the service when the app is next online. These two behaviors work in conjunction with each other, and are defined using the returnLayerAttachmentOption and attachmentSyncDirection properties on the AGSGenerateOfflineMapParameters class.
- The return layer attachment property defines which layers should contain attachments in the offline map. The options are:
- returnLayerAttachmentOption.none - None of the layers will contain any attachments.
- returnLayerAttachmentOption.allLayers - All layers will have their attachments included.
- returnLayerAttachmentOption.readOnlyLayers - Layers without editing enabled will have attachments included.
- returnLayerAttachmentOption.editableLayers - Layers with editing enabled will have attachments included.
- The attachment sync direction defines how the attachments are synchronized with the service. The options are:
- attachmentSyncDirection.none - Attachments are not synchronized as part of the synchronization operation.
- attachmentSyncDirection.upload - Attachments are uploaded from the client to the service, but any changes on the service are not downloaded to the client.
- attachmentSyncDirection.bidirectional - Attachments are uploaded from client to the service, and changes on the service are pulled down to the client.
Attachment sync direction was introduced with ArcGIS Server 10.4.
Inclusion of features from editable feature layers
Here are some workflows that describe how these two parameters affect each other:
- Workflow 1—Download attachments for all layers in the map, allow the user to add or remove attachments from the layers, and then synchronize these changes between the service and the client when online. For example: multiple users collect data on the same area and they want to synchronize all the changes with the centralized services as well as sharing changes with other people in the field.
- Workflow 2—Download attachments for all read-only layers and update these layers when online. For example: users are offline and viewing a layer of buildings with photos that show how the buildings look. If there are any new photos added to the service, these will be downloaded to the client during synchronization when online.
- Workflow 3—Download attachments for editable layers only and upload them to the service when online. For example: users are offline and only need to view attachments for editable layers. If there are any read-only layers that provide context for the map, their attachments aren’t included to the local map. If users remove or add any new attachments, these changes can be synchronized to the service when online.
- Workflow 4—Do not download any attachments but allow any new attachments to be uploaded to the service when online. For example: users are offline and collecting new attachments in the field but do not need to view existing attachments.
If users are collecting new information in the field where they do not need to access previously created features, you can create an offline map with empty editable feature layers. Do this by setting the AGSGenerateOfflineMapParameters property returnSchemaOnlyForEditableLayers to true.
Update or replace map's metadata
You can access the online map's metadata from the itemInfo property. It includes portal item properties such as the title, description, short description, and thumbnail. This information is populated from the portal item that contains the map. You can override any of these metadata properties before you take the map offline. For example, if you are creating offline maps of different areas of interest on the same map, you may want to change the map's title to indicate which area it contains.
You can also create a new AGSOfflineMapItemInfo object and manually set all the details.
Create offline map parameter overrides
Managing the map content may be sufficient for your workflow, but in some cases you may also want to control how individual layers or tables are taken offline, such as the following:
- Reducing the amount of data (for example, tile data) for a given layer
- Altering the spatial extent of a given layer (for example, to give coverage beyond the study area)
- Filtering features (for example, with a where clause) to only take those that are relevant to your fieldwork
- Taking features with null geometry (for example, where the attributes are populated in the office but the geometry needs to be captured on site)
- Omitting individual layers
- Generate and modify the AGSGenerateOfflineMapParameters as described in Create offline map parameter overrides above.
- Generate the parameter overrides object (AGSGenerateOfflineMapParameterOverrides) using the generateOfflineMapParameterOverrides method on the AGSOfflineMapTask. Provide the AGSGenerateOfflineMapParameters generated from the previous step.
- When the task completes, the AGSGenerateOfflineMapParameterOverrides will be initialized, honoring the settings in the supplied AGSGenerateOfflineMapParameters. AGSGenerateOfflineMapParameterOverrides will present three sets of data-source parameters as dictionary structures:
- However, if you just want to look up a specific set of parameters for a specific layer or table, you can construct the key from the layer or the table and obtain the parameters from the dictionary.
When you are happy with your changes, you can obtain a AGSGenerateOfflineMapJob by calling generateOfflineMapJobWithParameters:parameterOverrides:downloadDirectory:() on the offline map task supplying both the parameters and the overrides.
- Advanced symbols are supported only if they are defined in the original service. Any overrides with advanced symbols will result in empty symbols in an offline map.
- Area-of-interest geometries that cross the dateline are not currently supported.
- If more than one feature layer in a map refers to the same feature service endpoint, only one feature layer will be taken offline. The other feature layers will raise an error.
Once you have obtained the offline map, follow these steps:
- Display and interact with the maps, layers, and data offline. Explore and edit the feature data, if necessary.
- Update an offline map to synchronize your edits with the online services when connectivity is restored.
- Finish using an offline map to unregister any geodatabases and release all locks on the mobile map package.