Download an offline map (preplanned)

Your ArcGIS Runtime app can use a web map while it has no internet connection by first downloading an offline map from the web map. As soon as the offline map is downloaded, a mobile worker can disconnect their device and work with the map offline.

The owner of a web map can define geographic areas of the web map to be packaged as offline maps before they are needed. Offline maps defined and created this way are known as preplanned offline maps. Preplanned offline maps are well-suited to field apps used by mobile workers and scale well to large workforces.

The main advantages of preplanned offline maps are:

  • The map author can organize a set of specific map areas for mobile workers to use.
  • Users can download the preplanned offline maps quickly and with minimal interaction. Since the preplanned offline maps are generated before they are needed, their download time is comparable to any other files and resources.
  • Many users can download the same preplanned offline map.

The steps to use preplanned offline maps are:

  1. Create preplanned offline maps for your web map.
  2. Get a list of map areas in your app.
  3. Create the parameters
  4. Create the job
  5. Run the job

Create preplanned offline maps

To create preplanned offline maps, you must use web maps created with ArcGIS or with ArcGIS Enterprise 10.6.1 or later. You must ensure that all services used in the web map are enabled for offline use.

You can create map areas manually using the ArcGIS Online or ArcGIS Enterprise. You can also create them programmatically, using Python scripts or the ArcGIS REST API, as described below.

ArcGIS Online or ArcGIS Enterprise

Use ArcGIS Online or ArcGIS Enterprise to create, edit, and manage map areas for your web maps. See the topics below for details.

Python scripts

Use ArcGIS API for Python to write python scripts to create offline maps and generate their associated data packages. See the managing map areas Python topic for details.

  • Update the map area of an offline map and any of its packages that have been deleted or contain more recent data.
  • Delete an individual data package.
  • Delete an offline map along with its associated packages.
  • Inspect any of the offline maps's packages.
  • List the web map's current map areas.

ArcGIS Rest API

Use the ArcGIS REST API if you need even more control when creating your preplanned offline maps. There are two stages to this process:

  1. Create an offline map: Run the Create Map Area task with a bookmark or geographical extent to define the area of interest for a web map that's enabled for offline use. The task generates a new portal item of type MapArea. Only the owner of the web map and organization administrators can run this task.
  2. Create the data defined by the map area: Run the Setup Map Area task with the map area portal item ID. This creates a set of data files such as tile packages, vector tile packages, and SQLite geodatabases. For good data management, you should organize these files into folders. Only the owner of the map area portal item owner and organization administrators can run this task.

Define updates

In addition to creating the map area, you can also define how users receive updates to the data used in the offline map. Updates can come from synchronization of the offline map's geodatabases with their online services or by applying scheduled update files to the geodatabases (read-only).

  • Synchronization allows you to download updates from the online service and upload edits from the offline map when connectivity is available. You can configure the synchronization direction control how edits are synchronized download only, upload only, or bi-directional.
  • Scheduled updates provide feature service udpates in a file that is created on a regular basis. ArcGIS Runtine API can download the required files and apply their updates to the offline map's geodatabases. These files are relatively small so they are quick to download and fast to apply. This provides a scalable solution for receiving updates to read-only geodatabases and is useful when you need to provide many clients with an up-to-date read-only copy of the feature data. You can set the scheduled update parameters using the Setup Map Area task in the ArcGIS REST API.

Use the preplanned map area

Once you have created a preplanned map area, the mobile map package publication will be initiated. The following section describes how you build a Runtime app to download the mobile map package for offline map.

Get a list of map areas

Each web map can have up to sixteen preplanned offline map areas defined, which are available to download as offline maps. Your app needs to determine which map area to download. You can do this by allowing the mobile worker to select a map area from a map view or from a list of map areas. Alternatively, the app logic could select a map area for the mobile worker.

Follow these steps to retrieve all of the map areas:

  1. Instantiate the offline map task by passing either a map (created from a web map) or a web map's portal item to the AGSOfflineMapTask constructor.

         
    1
    2
    3
    4
    5
    // create the offline map task from a map
    self.offlineMapTask = AGSOfflineMapTask(onlineMap: self.map)
    
    // or from a portal item
    self.offlineMapTask = AGSOfflineMapTask(portalItem: self.portalItem)
  2. Retrieve a list of the preplanned map areas from the web map using the getPreplannedMapAreasWithCompletion:() method on the AGSOfflineMapTask.

  3. Load the preplanned map area; AGSPreplannedMapArea.

  4. Display the map area titles and thumbnails in a list, or show the map area extents or just select a map area by name.

                                 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    // get all of the preplanned map areas in the web map
    self.offlineMapTask?.getPreplannedMapAreas(completion: {[weak self] (mapAreas, error) in
        if let error = error {
            print(error.localizedDescription)
        }
        guard mapAreas != nil else {
            print("No map areas")
            return
        }
    
        if let mapAreas = mapAreas {
            // load each of the preplanned map areas
            for mapArea in mapAreas {
                mapArea.load(completion: { [weak self] (error) in
                    if let error = error {
                        print(error.localizedDescription)
                    }
                    // Retrieve properties of the preplanned map areas so that you can build a UI that displays the
                    // area of interest, the title and thumbnail of each map area. Or use this information to select
                    // a map area (for example, you may already know the name of the map area name you want to download).
                    var areaOfInterest = self?.mapArea?.areaOfInterest
                    if let portalItem = mapArea.portalItem {
                        var theTitle = portalItem.title
                        var theThumbnailImage = portalItem.thumbnail
                    }
                })
            }
        }
    })
    

Create the parameters

To download a preplanned offline map to your device, you should provide a set of AGSDownloadPreplannedOfflineMapParameters. To obtain a set of default parameters pass in the map area to AGSOfflineMapTask.defaultDownloadPreplannedOfflineMapParametersWithArea:completion:(). The value of these default parameters will match the advanced offline settings configured by the web map author (discussed in Take web maps offline).

                  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
offlineMapTask?.defaultDownloadPreplannedOfflineMapParameters(withArea: mapArea, completion: {[weak self] (parameters, error) in
    if let error = error {
        print(error)
        return
    }
    guard parameters != nil else {
        print("No parameters")
        return
    }

    if let parameters = parameters {
        // Update any of these parameters values, if needed
        parameters.continueOnErrors = false
        parameters.includeBasemap = true
        parameters.referenceBasemapDirectory = "\mytilepackages"
        self?.preplannedParameters = parameters
    }
})

For more information see Advanced parameters.

Create the job

Create the AGSDownloadPreplannedOfflineMapJob using AGSOfflineMapTask.downloadPreplannedOfflineMapJobWithParameters:downloadDirectory:() and provide both the AGSDownloadPreplannedOfflineMapParameters and the download directory.

     
1
2
3
4
5
// construct the download preplanned offline map job
self.downloadPreplannedMapJob = self.offlineMapTask.downloadPreplannedOfflineMapJob(
    with: self.downloadPreplannedOfflineMapParameters,
    downloadDirectory: URL(string: fullPath)!
)

Run the job

To download the preplanned offline map to your device, start the AGSDownloadPreplannedOfflineMapJob. Upon completion, the job returns an instance of the AGSDownloadPreplannedOfflineMapResult.

To ensure the job was successful, check the following:

  • If at least one table or layer failed to be downloaded successfully, hasErrors in AGSDownloadPreplannedOfflineMapResult will be true. In that case, you should examine the layerErrors and tableErrors dictionaries in that result object to identify the problem.
  • The job's parameters property is a reference to the AGSDownloadPreplannedOfflineMapParameters with which the job was created. If continueOnErrors in that parameters object is false, then the job will be terminated immediately if a single layer or table fails to be taken offline.
  • If the preplanned offline map publishing has failed, or is still in progress, you will not be able to download its mobile map package. Before running this job, you can check whether the publishing process is complete, has failed, or is still in progress by examining the packagingStatus of the AGSPreplannedMapArea. (Note: The download preplanned offline map job has a parameters property that returns the job's AGSDownloadPreplannedOfflineMapParameters, which contain preplannedMapArea.)

If you want to display the map immediately, then use DownloadPreplannedOfflineMapResult.offlineMap.

                        
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
//start the job
self.downloadPreplannedMapJob.start(statusHandler: { [weak self] (status) in
    print("Status [\(String(describing: self?.downloadPreplannedMapJob.progress.fractionCompleted))]: \(status)")
}, completion: { (result, error) in
    if let error = error {
        print(error)
        return
    }

    guard let result = result else {return}

    if result.hasErrors {
        result.layerErrors.forEach{(layerError) in
            print((layerError.key.name), " Error taking this layer offline")
        }
        result.tableErrors.forEach{(tableError) in
            print((tableError.key.tableName), " Error taking this table offline")
        }
    }
    else {
        //display the offline map
        self.mapView.map = result.offlineMap
    }
})

Offline maps created by the preplanned 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 the mobile map package's download directory stored on your device.

Advanced parameters

Once you have the default parameters you can customize them in the following ways:

Continue if a table or layer fails

The AGSDownloadPreplannedOfflineMapJob downloads a map's tables and layers for offline use. By default this job will continue doing so, even if one table or layer has failed. Failures could be due to an intermittent network connection, loss of the service, or an unsupported layer type. The approach ensures that you can take a map offline but you may have some data missing.

To ensure that the offline map contains all of its layers and tables, you can request that the job be stopped if any layer or table fails to download. To do this, set continueOnErrors in AGSDownloadPreplannedOfflineMapParameters to false.

Which basemap should the map use?

The author of the web map can define whether the map uses:

  • 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 offline map(s). 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, employ certain properties in AGSDownloadPreplannedOfflineMapParameters:

    • Set referenceBasemapDirectory to the directory which contains the tile package.
    • Confirm that the tile package file, referenceBasemapFilename, exists on the device.

    Only then should you run the AGSDownloadPreplannedOfflineMapJob. This job will add the tile package, as a basemap, to the offline map.

  • No basemap

    If you only want to take the operational layers offline, you can programmatically exclude the basemap by setting includeBasemap in AGSDownloadPreplannedOfflineMapParameters to false. In that case, the AGSDownloadPreplannedOfflineMapJob will not download layers included as part of the map's basemap. (For more information, see basemap in AGSMap or its base class AGSGeoModel.) This task will not use the local tile package, even if you have specified one.

Manage the update mode

Typically, updateMode in the AGSDownloadPreplannedOfflineMapParameters is set to the enum value AGSPreplannedUpdateModeSyncWithFeatureServices. This mode allows you to synchronize any geodatabase changes with the online feature services. For other possible values, see the AGSPreplannedUpdateMode enum.

If the web map author specified that scheduled updates will be generated for all feature services in the map (discussed in Define updates), then updateMode on the AGSDownloadPreplannedOfflineMapParameters will be set to AGSPreplannedUpdateModeDownloadScheduledUpdates. This means that the map's geodatabases are read-only and can only receive updates via the scheduled update files.

If you want to edit the geodatabases and adopt the synchronization approach, you can override this update mode and set it to AGSPreplannedUpdateModeSyncWithFeatureServices using updateMode. From this point you will not be able to apply the scheduled update files.

If you want to avoid receiving any geodatabase updates, set the update mode in AGSDownloadPreplannedOfflineMapParameters to AGSPreplannedUpdateModeNoUpdates. 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.

Next steps

Once you have obtained the offline map follow these steps:

  1. Display and interact with the maps, layers and data offline. Explore and edit the feature data, if necessary.
  2. Update an offline map by synchronizing your edits with the online services, when connectivity is restored.
  3. Finish using an offline map by unregistering any geodatabases and fully releasing all locks on the mobile map package.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.