packaging.arcgis.com high-level questions

[CamBarnard]

Raúl Jiménez Ortega‌

I've read through the documentation several times at:

Create Map Area—ArcGIS REST API: Packaging Service | ArcGIS for Developers 

Setup Map Area—ArcGIS REST API: Packaging Service | ArcGIS for Developers 

Refresh Map Area Package—ArcGIS REST API: Packaging Service | ArcGIS for Developers 

Q1: These APIs currently work against ArcGIS Online, not yet against Portal for ArcGIS Enterprise. Correct?

Q2: I'm struggling to understand the differences between Setup Map Area and Create Map Area. Can you explain?

Q3: Is there an intended flow where all three of these APIs are to be used together? e.g. Setup > Create > Refresh?

I'm about to embark on some proof of concept work, but a high-level understanding before starting would be GREAT

Cam Barnard

[Raul_Jimenez]

Hi Cam Barnard‌,

I'll do my best to help you but I'm not an expert on this topic so... maybe Ramunas Kraujutis‌ or any other fellow can help us here .

Q1: These APIs currently work against ArcGIS Online, not yet against Portal for ArcGIS Enterprise. Correct?

Yes, I think so, that's why the URL schemas are pointing directly to arcgis.com, otherwise it should point to something like: http://server:port/arcgis/admin

Q2: I'm struggling to understand the differences between Setup Map Area and Create Map Area. Can you explain?

I think the ArcGIS Online: Taking Data Offline talk from Paul Barker and Chris Whitmore might help you better understand some differences between creating Map Area items like this (this is what Create Map Area does) and creating the tile packages (.tpk or .vtpk) and SQLite Geodatabase (this is what Setup Map Area does).

Q3: Is there an intended flow where all three of these APIs are to be used together? e.g. Setup > Create > Refresh?

mmmm, I think it doesn't but not 100% sure.

Bests,

Raul

[PaulBarker · Accepted solution]

Cam,

Here are some quick responses to your questions.  Additionally; we are working on building a user experience around these features in online to make it easier to create and manage areas over the next few releases to simplify this workflow. 

Q1: These APIs currently work against ArcGIS Online, not yet against Portal for ArcGIS Enterprise. Correct?

This one requires a bit more context.  These tools will start showing up in Enterprise in 10.6.1 and if you want to use enterprise feature services (hosted or non-hosted) they will need to be 10.6.1 to work properly.  

The packaging tools whether they're within Online or Enterprise do support packaging external services. For example if you had a web map in ArcGIS Online and it had a  tiled map service (basemap) that was on Enterprise you could still package that as part of your online map.  The caveat in that case is the service in enterprise needs to be public, or if it secured when you added it as an item to online you would need to store the portal credentials with it.

Q2: I'm struggling to understand the differences between Setup Map Area and Create Map Area. Can you explain?

Think of the process as a two steps just to give some extra flexibility depending on your workflow.  The first one Create Map Area , creates the Map Area item based on the extent/bookmark you want to use, at this point nothing gets packaged. Your simply defining the geographic area. 

Setup Map Area does all the packaging and heavy lifting. At this point you can use the the defaults to make a map area or pass in additional parameters as needed for each layer (change sync settings, define base map detail, ignore layers etc.) 

Q3: Is there an intended flow where all three of these APIs are to be used together? e.g. Setup > Create > Refresh?

The basic order is Create > Setup > Refresh (if required) 

Refresh Map Area Packages is used to keep the packaged data up to date as the underlying data in the map changes.  Think of it mostly as preventing the initial download from being too stale.  For most apps a typical pattern would be to: 

• Download the map area
• Register your replicas against the feature service
• Sync those feature services to get any changes that might have happened while downloading or since the package was last refreshed
• Start working with the map

One feature we are looking to add is the be able to schedule automatic refreshing of the packages. 

[Raul_Jimenez]

Thank you very much for the clarifications Paul!!

[CamBarnard]

This was super helpful. Thank you Paul.

I know naming is deucedly hard ... you might want to consider

DEFINE map area > BUILD map area > REFRESH map area (rather than CREATE > SETUP > REFRESH )

[CamBarnard]

I've successfully gone through the entire end-to-end a couple of times now. For those approaching this for the first time a couple of important things to note.

1. These APIs don't (yet) support multi-part form (body) style submission ... you must use actual parameters. This had me going around in circles for a while.

2. The check job status calls will often return garbage, try again a couple more times and you'll see an actual status

3. Ensure the token you are using is a user token that has access to the web map or is an admin. I started out trying to use an app specific token but the job couldn't access my web  map. I ended up just logging into may organizational AGOL account and capturing my token using Fiddler

4. Start simple with a base-map-only web map, you can add more feature data to your web map once you get the end-to-end flow working

5. The overall 'flow' I ended up with was:

CREATE map area

Check job status on CREATE

Retrieve results for CREATE

SETUP created map area

Check job status on SETUP

Retrieve results on SETUP

(optional but I wanted to test them)

REFRESH map area package

Check job status on REFRESH

Retrieve results on REFRESH

[PaulBarker]

Great summary Cam,

Like I mentioned before this will get easier soon for both Runtime developers and people testing out Collector for ArcGIS Beta (Aurora).  Here's a sneak peak at what is coming soon.  

 

[CamBarnard]

Thanks Paul. The only thing that still has me scratching my head is where the output from the CREATE map area items live. Once the area is SETUP I have new items in my content ... but the item ID resulting from CREATE doesn't live in my content. I checked the web map JSON thinking maybe it was embedded there (nope).

Where do the "CREATED" map areas live?

Is there an API call to get a list of the (up to 16) created map areas (or those that have actually been setup for that matter) that have been defined for a particular web map?

Everything else was reasonably discoverable once I got the API flow right but that still has me scratching my head.

Cam 

[PaulBarker]

The items still exist under your content (both the map area item and the packages) We just dont show them in search results and in my content (if you were doing your own search over the api you could search for them). 

As you can imagine once you have a number of maps with areas and areas with packages the items start to add up and showing them in places like my content would get in the way of managing the rest of your items. This is why we're coupling the management of map areas and packages to the webmap itself.  From a web maps item details page you will be able to manage your map areas for that map. 

To answer your other question.  As a developer you can discover the map areas (and the packages) by starting with the web map's item using the Related Items api :

Related Items—ArcGIS REST API: Users, groups, and content | ArcGIS for Developers 

To find the areas for a webmap you use the relationship type Map2Area we make a note of it in the intro topic here:

Create Map Area—ArcGIS REST API: Packaging Service | ArcGIS for Developers 

You can do the same thing from the Map Area item to find the packages for a given map area using the relationship Area2Package , we make a note of that in the Setup Map Area doc but it can be easy to miss if you don't know to look for it : Setup Map Area—ArcGIS REST API: Packaging Service | ArcGIS for Developers 

Hope that helps

[DavidChambers]

Thanks for posting this Cam - I observed the same random error message when submitting a request to get the output mapAreaItemId.  Re-submitting fixed the issue for me as well.

https://packaging.arcgis.com/arcgis/rest/services/OfflinePackaging/GPServer/CreateMapArea/jobs/<jobid>}/results/mapAreaItemId?token=<token>&f=json

{
    "error": {
        "code": 400,
        "extendedCode": -2147024809,
        "message": "Invalid or missing input parameters.",
        "details": []
    }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍