Skip To Content ArcGIS for Developers Sign In Dashboard

Take a map offline - preplanned

The preplanned workflow allows an organization to prepare offline maps so that they can be taken into the field, as required. The map author creates a map area defined by a specific geographical area of work. This process generates the associated map, tile package, and geodatabase files and stores them in a mobile map package. The offline map resides in this mobile map package, in ArcGIS Online or ArcGIS Enterprise, until the field worker downloads it. As soon as the mobile map package is downloaded, the field worker can disconnect their device and work with the map offline.

The main advantages of this workflow are as follows:

  • The map author can organize and define very specific map areas for the field workers.
  • The user can obtain the preplanned map area more quickly because the mobile map package has been generated, in advance, by the author. In contrast, during the on-demand workflow, the user has to both generate and download the mobile map package to their device.
  • Many users can download exactly the same mobile map package.

  1. Create preplanned map areas
  2. Identify a map area
  3. Create the parameters
  4. Create the job
  5. Run the job

Create preplanned map areas

The preplanned workflow allows you to create a map area and publish its mobile map package, in advance, so that it can be downloaded by field workers when they need it.

Note:

To create preplanned map areas, 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 user interface, or programmatically, using Python scripts or the ArcGIS REST API, as follows:

ArcGIS Online or ArcGIS Enterprise

Manually create, edit, and manage map areas as follows:

Note:

If a map area was created with a version earlier than 10.6.1, you can take it offline. If you want to edit the map area, you must re-create it with ArcGIS Portal 10.6.1 or later.

Python scripts

Use the ArcGIS API for Python to write python scripts to create map areas and generate their associated data packages. This is detailed in the managing map areas Python topic along with other useful map area management functions such as the following:

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

Note:

It is recommended that you use ArcGIS API for Python 1.7 or later.

ArcGIS Rest API

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

  • To create a map area, you must run the Create Map Area task, providing a bookmark or geographical extent as the area of interest. Upon completion, the task will generate a new portal item of type MapArea. This task requires that the web map is enabled for offline use. It is only available to the owner of the web map and organization administrators.
  • To create the data defined by the map area, you must run the Setup Map Area task, providing the map area portal item ID. This will create a set of data files such as tile packages, vector tile packages, and SQLite geodatabases. For good data management, it is strongly recommended that you also provide a folder to organize these files. This task is only available to the map area portal item owner and organization administrators.

Note:

You must use ArcGIS REST API 10.6.1 or later.

Define updates

In addition to creating the map area, you can also define how users receive updates to the geodatabases in the offline map. Updates can happen by synchronizing 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, once connectivity is restored. You can configure this synchronization direction to determine in which direction edits are synchronized—download only, upload only, or bi-directional.
  • Apply scheduled updates allows you to schedule the regular creation of a file containing updates made to the feature service. The ArcGIS Runtine API can download the files it requires and apply them to the offline map's geodatabases. These files are relatively small so they are quick to download and fast to apply. This is a scalable solution for receiving updates to read-only geodatabases. This option is useful in cases in which 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. Applying these updates will be described in Update an offline map.
Note:

Scheduled updates are supported with feature services created using ArcGIS Online or ArcGIS Enterprise 10.7.1 or later. Therefore, you must use ArcGIS REST API 10.7.1 or later.

Using 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 the map area.

Identify a map area

Each web map can contain one or more preplanned map areas. Your app needs to determine which map area should be downloaded. You can do this by allowing the field 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 field 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.

    // 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 getPreplannedMapAreas 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.

    // 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 take a map offline you can provide a set of AGSDownloadPreplannedOfflineMapParameters. To obtain a set of default parameters pass in the map area to the defaultDownloadPreplannedOfflineMapParametersWithArea method on the AGSOfflineMapTask. The value of these default parameters will match the advanced offline settings configured by the web map author (discussed in Take web maps offline.

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 download preplanned map area job by calling the downloadPreplannedOfflineMapJob method on the AGSOfflineMapTask. Pass in the AGSPreplannedMapArea and a download directory on the device. If this download directory already exists it must be empty. If the directory doesn't exist, it will be created by the job.

// construct the download preplanned offline map job
self.downloadPreplannedMapJob = self.offlineMapTask.downloadPreplannedOfflineMapJob(with: self.preplannedMapArea, downloadDirectory: URL(string: fullPath)!)

If, however, you have created parameters to control the map content you must create the AGSDownloadPreplannedOfflineMapJob using the downloadPreplannedOfflineMapJob method on the AGSOfflineMapTask and provide both the AGSDownloadPreplannedOfflineMapParameters and the download directory.

// 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 map area to your device start the AGSDownloadPreplannedOfflineMapJob. Upon completion the job will return an instance of the AGSDownloadPreplannedOfflineMapResult.

Consider the following problems or failures:

  • 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 job's ContinueOnErrors parameter has been set to false then the job will be terminated immediately if a single layer or table fails to be taken offline.
  • If the preplanned map area 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.

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

//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
 }
})

Note:
Note that this job will behave the same whether it was created with or without the AGSDownloadPreplannedOfflineMapParameters.

For more details on how to work with jobs, see the Tasks and jobs topic.

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 downloadDirectory stored on your device. See Open an offline map for more information.

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 takes a map's tables and layers offline. By default this job will continue to do this even if one table of 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 is stopped if any layer or table fails to download. To do this set the ContinueOnErrors property to false.

downloadPreplannedOfflineMapParameters.continueOnErrors = 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 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 which contains the tile package. It is recommended that you confirm that the tile package file, referenceBasemapFilename, exists on the device before running the AGSDownloadPreplannedOfflineMapJob. This job will add the tile package, as a basemap, to the offline map.

    //confirm that the basemap tile package is on the device
    let documentsDir =  (NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0])
    let path = documentsDir + "\" + parameters.referenceBasemapFilename
    let exists = FileManager.default.fileExists(atPath: self.path)
      
    //if it exists then set the referenceBasemapDirectory value so that the 
    //AGSDownloadPreplannedOfflineMapJob can use the local tilepackage as the map's basemap 
    if (exists) {       
     parameters.referenceBasemapDirectory = documentsDir
    }

    Note:

    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 you 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 AGSDownloadPreplannedOfflineMapJob will not download layers included as part of the map's basemap. This task will not use the local tile package, even if you have specified one.

    parameters.includeBasemap = false

Manage the update mode

Typically, the updateMode on the AGSDownloadPreplannedOfflineMapParameters is set to syncWithFeatureServices. This mode allows you to synchronize any geodatabase changes with the online feature services.

If the web map author has specified that scheduled updates will be generated for all feature services in the map (discussed in Define updates, then the updateMode on the AGSDownloadPreplannedOfflineMapParameters will be set to downloadScheduledUpdates. 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 updateMode by setting it to syncWithFeatureServices. 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 updateMode on the AGSDownloadPreplannedOfflineMapParameters 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.

Note:

Instead of obtaining the default set of AGSDownloadPreplannedOfflineMapParameters you could construct them manually. The author of the web map can recommended how data is downloaded to offline devices, and subsequently synchronized, by adjusting the map's advanced offline settings (discussed in Take web maps offline). You can access these advanced settings from the map's OfflineSettings. They include:

  • working with feature attachments
  • synchronizing edits
  • downloading a basemap or using one which is already on the device

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.