Accessing the Field Maps Designer App Settings using the Python API

[MarkEastwood]

Hello, is it possible to configure the Field Maps settings shown below using the Python API? If so, is there any documentation available on how to do it? 

Thanks

[JustinReynolds · Accepted solution]

Hello,

This is a great question and the answer to the question is yes, you can update the settings using the ArcGIS API for Python and by extension using the ArcGIS REST API.

As far as I can tell, this is not publicly documented anywhere; so you heard it here first.

Where are these settings stored?

The Field Maps app settings are not stored with the map's definition.  So you won't be able to get them or set them using AGO Assistant or the by accessing the web map objects definition using the ArcGIS Python API.

You may be surprised to learn, as was I, that Portal/AGO items can have resources.  These resources are files of various types (JSON, XML, TXT, PNG, JPEG, GIF, BMP, PDF, MP3, MP4, and ZIP).  As far as I'm am aware, you can not access these resource files in the UI, it is all run behind the scenes.

Resources is a property of an item.  You can add, export, get, list, remove, or update these resource files.

The settings in question are stored in a file named field-maps-settings.json.

Accessing Item Resources

"An Item object in the GIS will often have binary or textual data provided in the form of resource files, and to manage these files we've introduced a ResourceManager helper class. When an Item is initialized, this ResourceManager instance is created and stored as the resources property of that Item. This property then provides access to a number of methods useful for viewing and modifying the files, including: list(), get(), add(), update(), remove() and export().

Users will generally not interact with the resources property directly, nor will they create a ResourceManager instance directly. Instead they will more often create classes and call methods which in turn initialize a ResourceManager instance for a portal Item and leverage these methods under the hood.

While the adding, updating, and removal of these resource files should ideally be accomplished through safer, higher-level functions and interfaces, users might be interested in directly calling the list(), get() and export() methods directly. Let's take a look at how we can use these methods and what we should expect as a response."

Example

Goal: Turn Layer Filters setting from "Off" to "All feature layers and fields".

Issue encountered:

I would like to modify the file in place using the file_name and text parameters, but the Python API's update method for some reason requires the file parameter, which means I also need a file on disk which I don't like.  Interestingly enough, the REST API does not require that.  Instead of using the update method my approach is to remove the existing file, then add it back with the new settings. The add method does not require a file on disk.

import json
from arcgis import GIS

FILENAME = 'field-maps-settings.json'
UPDATE_DICT = {'layerFilters': {'mode': 'all', 'layers': {}}}
MAP_ITEM_ID = 'f0a550fbe21f46cc9876dde4ea66fa1c' 
URL = 'https://<org>.maps.arcgis.com/'
USERNAME = 'item_owner_or_admin_username'
PASSWORD = 'thePassword'

portal = GIS(URL, USERNAME, PASSWORD)

map_item = portal.content.get(MAP_ITEM_ID)

if map_item:
    resources = map_item.resources.list()
    if resources:
        if any(d['resource'] == FILENAME for d in resources):
            app_settings = map_item.resources.get(FILENAME)
            if app_settings:
                # Replace the existing settings with the UPDATE_DICT settings
                for setting, value in UPDATE_DICT.items():
                    app_settings[setting] = value
                
                # convert app_settings to JSON string
                new_settings = str(json.dumps(app_settings)) 
                
                remove_result = map_item.resources.remove(FILENAME) # returns True or False
                if remove_result:
                    result = map_item.resources.add(file_name=FILENAME, text=new_settings)
                    print(result)
        else:
            print('The Web Map item does not have the resource you are seeking!')
    else:
        print('The Web Map item does not have resources!')

Learn more:
https://developers.arcgis.com/python/api-reference/arcgis.gis.toc.html#resourcemanager
https://developers.arcgis.com/rest/users-groups-and-items/item-resources.htm
https://developers.arcgis.com/rest/users-groups-and-items/update-resources.htm
https://developers.arcgis.com/rest/users-groups-and-items/add-resources.htm
https://developers.arcgis.com/python/guide/accessing-item-resources/

Note:

When you click the "Save" button on the App Setting tab of Field Maps Designer, it is hitting the updateResource REST Endpoint with a payload of filename="field-maps-settings.json" and text="{<all the settings>}", which falls inline with line 10 in the code snippet above.

[MarkEastwood]

@JustinReynolds - Have you successfully updated the field-maps-settings.json using the ArcGIS API for Python? I have been working on a script myself, but I'm encountering difficulties when attempting to update the field-maps-settings.json file.

[JustinReynolds]

Hey Mark,

I'm working a script as well.  I will let you know how it goes.  If I have too many issues I will pass it to a real developer.  If worst comes to worst I'll use the REST API using python.

[JustinReynolds]

I modified the original reply.  Sorry for the nested if blocks. I refactored my code to make it less abstract for others.  It works pretty well.

[MarkEastwood]

Thanks so much for the effort you put into this.

I did the same test, updating the Turn Layer Filters setting from "Off" to "All feature layers and fields", and it worked great. 

[PhilPonce]

Hi Justin - I'm trying to leverage the form layouts from Field Maps Designer in a ExB custom widget edit interface.  In your experience can I get at the form definition through the resources interface you cite?

Thanks in advance for any guidance you can lend.

-Phil Ponce, PE

[MarkEastwood]

@JustinReynolds 

Thank you for providing such a comprehensive response.

I too was surprised that the app settings were not included in the maps definition, as well as the discovery of items having resources.

I plan to implement your suggestions within the next few days and will accept this as a solution once I have successfully executed the script.

[DylanT_EsriCanada]

While technically possible, I would be careful with editing these org-wide files and would recommend having a backup.

[JustinReynolds]

Hi Dylan,

Can you elaborate a bit more on what you mean by editing org-wide files? I'd like to understand the risks a bit more.

The resource files in question are at the item level (specifically of a web map item), accessible to only the item owner or admin. It may or may not exist and merely hold easily replaceable config items relevant to only field maps.  These are the exact calls that happen in the Field Maps Designer UI to the REST API (addResource, removeResource, updateResource) when the "Save" button is clicked.