Setup Map Area

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) and SQLite Geodatabase format replica packages for exportTilesAllowed tiled services (i.e. basemap layer) and sync enabled feature services (i.e. operational layers). It adds an Area2Package relationship between the map area item and created package items.

Existing package related to a map area will remain unchanged after running the task a second time as long as its corresponding layer remain existed 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 executing it since its corresponding layer no longer exists in the web map thus becomes invalid.

This task is only applicable to ArcGIS Online and available for the map area item owner and organization administrators.

Request Parameters

Parameter

Details

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:

[
  "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:

[
  {
    "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 layer definition query in the map. Each feature service is specified with its url, layers, layerQueries, returnAttachments, attachmentsSyncDirection, syncModel, and syncDirection properties. See create replica for details of each.

Example:

[
  {
    "url":"https://services.arcgis.com/ERmEceOGq5cHrItq/arcgis/rest/services/LandUse/FeatureServer",
    "layers":[0,1],
    "returnAttachments":false,
    "attachmentsSyncDirection":"upload",
    "syncModel":"perLayer"
  }
]

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:

{
  "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:

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

JSON response syntax during job execution

{
    "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 completeness, you can retrieve the output results in below form:

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:

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

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:

{
 "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

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/submitJob?mapItemId=1a6c552e5cbe4249aa307df94a84c2b3

JSON Response Example

{
 "jobId": "jf360770cb2c44398abc5ce474bbfae88",
 "jobStatus": "esriJobSubmitted"
}

Check job status

Request URL to query job status

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/jf360770cb2c44398abc5ce474bbfae88

JSON Response

{
 "jobId": "jf360770cb2c44398abc5ce474bbfae88",
 "jobStatus": "esriJobExecuting",
 "messages": []
}

Retrieve results

Request URL to return output map area item

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/SetupMapArea/jobs/j40fb94bf101840fc90f130ab2da9553b/results/packages

JSON Response

{
 "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"
  }
 ]
}
12/1/2017