Setup Map Area

URL:: ArcGIS Online:https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/submitJob
ArcGIS Enterprise:https://<catalog-url>/Utilities/OfflinePackaging/GPServer/SetupMapArea/submitJob
Methods:: POST
Version Introduced:: 10.6.1

Description

The Setup Map Area task creates packages for each service in the web map within the map area extent. The tool generates tile packages (.tpk or .vtpk) for exportTilesAllowed tiled services (in other words, basemap layers) and SQLite Geodatabase format replica packages for sync-enabled feature services (in other words, operational layers). It adds an Area2Package relationship between the map area item and created package items.

An existing package related to a map area will remain unchanged after running the task a second time as long as its corresponding layer remains in the web map and therefore a valid map layer. For example, if a web map is updated with a feature layer removed after a package is created for that layer using the GP tool, the package will be removed the next time it is executed since its corresponding layer no longer exists in the web map and thus becomes invalid.

This task is available for the map area item owner and organization administrators in ArcGIS Online and ArcGIS Enterprise.

Request parameters

Parameter	Details
`f`	The supported output format is JSON. Example Use dark colors for code blocksCopy `1 f=json`
`token`	An access token that identifies the authenticated user and controls access to restricted resources and operations.
`mapAreaItemId`	Map area item ID, created by the Create Map Area tool.
`mapLayersToIgnore` (Optional)	A list of individual layers, specified with their service URLs, in the map to ignore. The task generates packages for all map layers by default. Example: Use dark colors for code blocksCopy `1 2 3 4 [ "https://services.arcgis.com/ERmEceOGq5cHrItq/arcgis/rest/services/SaveTheBaySync/FeatureServer/1", "https://services.arcgis.com/ERmEceOGq5cHrItq/arcgis/rest/services/WildfireSync/FeatureServer/0" ]`
`tileServices` (Optional)	An array of JSON objects that contains additional export tiles-enabled tile services for which tile packages (`.tpk` or `.vtpk`) need to be created. Each tile service is specified with its URL and desired level of details. Example: Use dark colors for code blocksCopy `1 2 3 4 5 6 [ { "url": "https://tiledbasemaps.arcgis.com/arcgis/rest/services/World_Imagery/MapServer", "levels": "17,18,19" } ]`
`featureServices` (Optional)	An array of JSON objects that contains additional sync-enabled feature services for which replicas need to be created. It can also be used to override a layer definition query in the map. Each feature service is specified with its `url` , `layers` , `layerQueries` , `returnAttachments` , `attachmentsSyncDirection` , `syncModel` , `syncDirection` , and `createPkgDeltas` properties. See create replica for details of each. Example: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 [ { "url":"https://services.arcgis.com/ERmEceOGq5cHrItq/arcgis/rest/services/LandUse/FeatureServer", "layers":[0,1], "returnAttachments":false, "attachmentsSyncDirection":"upload", "syncModel":"perLayer" } ]` Feature services support scheduled updates (version 10.7.1 and later). Scheduled updates allow apps to download server side changes based on a fixed schedule. This is to support download-only workflows in which you only need a copy of the data for reference even if the service supports editing. It is not intended for workflows in which clients make edits and sync. If `createPkgDeltas` is configured, apps downloading the map area can periodically download changes from the server based on a schedule. The `maxDeltaAge` property of `createPkgDeltas` is used to set the number of days that individual deltas are kept on the server and are available for download (the default is 5 days). If an app goes too long without downloading updates, they may be required to redownload the full map area again. Example: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 [ { "url": "https://services.arcgis.com/ERmEceOGq5cHrItq/arcgis/rest/services/LandUse/FeatureServer", "layers": [0,1], "returnAttachments": false, "attachmentsSyncDirection": "upload", "syncModel": "perLayer", "createPkgDeltas": { "maxDeltaAge": 5 } } ]`

Response properties

When a job request is submitted, the service assigns a unique job identifier for the transaction. A JSON response with the job ID and job status are returned as below:

Use dark colors for code blocksCopy
{
  "jobId": "<jobID>",
  "jobStatus": "esriJobSubmitted" | "esriJobWaiting" | "esriJobExecuting" | "esriJobSucceeded" | "esriJobFailed" | "esriJobTimedOut" | "esriJobCancelling" | "esriJobCancelled"
}

Check job status

After the initial request is submitted, you can use the job ID to check its status and messages periodically by calling as below:

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/<jobID>?token=<token>&returnMessages=true&f=json

JSON response syntax during job execution

Use dark colors for code blocksCopy
{
    "jobId": "<jobId>",
    "jobStatus": "<jobStatus>",
    "messages": [
        {
            "type": "<type1>",
            "description": "<description1>"
        },
        {
            "type": "<type2>",
            "description": "<description2>"
        }
    ]
}

Retrieve results

When the status of the job is esriJobSucceeded upon its successful completion, you can retrieve the output results by calling as below:

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/<jobID>/results/<outputParameter>?token=<token>&f=json

You can also retrieve the value of any input parameter by calling as below:

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/<jobID>/inputs/<inputParameter>?token=<token>&f=json

Upon successful execution, the service returns a JSON object that contains an array of packages for the given map area using the following output parameter:

Parameter Details

Parameter	Details
`packages`	A JSON object that contains properties for the output parameter name, data type, and value. The `value` property is a JSON array that contains the list of packages for the given map area; each has `source` (for the source service URL), `itemId` (for the corresponding package item ID), and `state` (for the package state). Supported values for `state` are: `new` \| `deleted` \| `unchanged`. Example: Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "paramName": "packages", "dataType": "GPString", "value": [ { "source": "https://services.arcgis.com/J423vH8fR9HV444k/arcgis/rest/services/myFeatureService1/FeatureServer", "itemId": "0da8bbef893a44a484be48732c7f018b", "state": "new" }, { "source": "https://services.arcgis.com/J423vH8fR9HV444k/arcgis/rest/services/myFeatureService2/FeatureServer", "itemId": "817cbd6752aa42f89d80e86a4560bc0f", "state": "deleted" }, { "source": "https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer", "itemId": "c8d1ae20448b487c9e28ad1e8eab13b7", "state": "unchanged" } ] }

packages

A JSON object that contains properties for the output parameter name, data type, and value. The value property is a JSON array that contains the list of packages for the given map area; each has source (for the source service URL), itemId (for the corresponding package item ID), and state (for the package state).

Supported values for state are: new | deleted | unchanged.

Example:

Use dark colors for code blocksCopy
{
 "paramName": "packages",
 "dataType": "GPString",
 "value": [
  {
   "source": "https://services.arcgis.com/J423vH8fR9HV444k/arcgis/rest/services/myFeatureService1/FeatureServer",
   "itemId": "0da8bbef893a44a484be48732c7f018b",
   "state": "new"
  },
  {
   "source": "https://services.arcgis.com/J423vH8fR9HV444k/arcgis/rest/services/myFeatureService2/FeatureServer",
   "itemId": "817cbd6752aa42f89d80e86a4560bc0f",
   "state": "deleted"
  },
  {
   "source": "https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer",
   "itemId": "c8d1ae20448b487c9e28ad1e8eab13b7",
   "state": "unchanged"
  }
 ]
}

Example usage

Request URL to submit the job

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/submitJob?mapItemId=1a6c552e5cbe4249aa307df94a84c2b3

JSON Response example

Use dark colors for code blocksCopy
{
 "jobId": "jf360770cb2c44398abc5ce474bbfae88",
 "jobStatus": "esriJobSubmitted"
}

Check job status

Request URL to query job status

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/jf360770cb2c44398abc5ce474bbfae88

JSON Response

Use dark colors for code blocksCopy
{
 "jobId": "jf360770cb2c44398abc5ce474bbfae88",
 "jobStatus": "esriJobExecuting",
 "messages": []
}

Retrieve results

Request URL to return output map area item

Use dark colors for code blocksCopy
https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/j40fb94bf101840fc90f130ab2da9553b/results/packages

JSON Response

Use dark colors for code blocksCopy
{
 "paramName": "packages",
 "dataType": "GPString",
 "value": [
  {
   "source":  "https://services.arcgis.com/J423vH8fR9HV444k/arcgis/rest/services/featureService1/FeatureServer",
    "error":  "Sync not enabled on service featureService1"
  },
   {
   "source":  "https://services.arcgis.com/J423vH8fR9HV444k/arcgis/rest/services/featureService2/FeatureServer",
    "itemId":  "0da8bbef893a44a484be48732c7f018b",
    "state":  "new"
  },
   {
   "source":  "https://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer",
    "itemId":  "c8d1ae20448b487c9e28ad1e8eab13b7",
    "state":  "unchanged"
  }
 ]
}