Manage Map Server Cache Tiles (Server)

Summary

Creates and updates tiles in an existing web tile layer cache (in ArcGIS Enterprise or ArcGIS Online), map image layers in ArcGIS Enterprise, and cached map or image services in a stand-alone server. This tool is used to create new tiles, replace missing tiles, overwrite outdated tiles, and delete tiles.

Usage

• This tool may take a long time to run for caches that cover a large geographic extent or very large map scales. If the tool is cancelled, tile creation is stopped, but the existing tiles are not deleted. This means you can cancel the tool if you run out of time and rerun it later on the same cache by setting the Update Mode parameter to Recreate Empty Tiles.

Parameters

Dialog

Label	Explanation	Data Type
Input Service	The web tile layer, web imagery layer, or map image layer whose cache tiles will be updated.	Image Service; Map Server
Scales	A list of scale levels at which tiles will be created. By default, the scales listed in the tool dialog box are between the minimum and maximum cached scales for the service. You cannot change the cache scale range of the service in ArcGIS Pro.	Double
Update Mode	Specifies the mode that will be used to update the cache. Recreate Empty Tiles—Only tiles that are empty will be created. Existing tiles will be left unchanged. This option is not available for web tile layers published to ArcGIS Online. Recreate All Tiles—Existing tiles will be replaced and new tiles will be added if the extent has changed. Delete Tiles—Tiles will be deleted from the cache. The cache folder structure will not be deleted.	String
Number of caching service instances (Optional)	The total number of instances of the System/CachingTools service that will be dedicated to running this tool. If the default value of -1 is used, all the caching tool instances of the ArcGIS Enterprise setup will be used. Use a lower value to use fewer caching tool instances. You can increase the Maximum number of instances per machine setting of the System/CachingTools service using the Service Editor window available through an administrative connection to ArcGIS Server. Ensure that the server machines can support the chosen number of instances. When connecting to a stand-alone server, the default number of instances is equal to the value of the Maximum number of instances setting of the caching tool service.	Long
Area Of Interest (Optional)	An area of interest that will constrain where tiles will be created or deleted. This parameter is useful for managing tiles for irregularly shaped areas. It is also useful when precaching some areas and leaving less-visited areas uncached. If you do not provide a value for this parameter, the default value uses the full extent of the map.	Feature Set
Update Extent (Optional)	A rectangular extent used to create or delete tiles, depending on the value of the Update Mode parameter. If both the Update Extent and Area of Interest parameter values are specified, the Area of Interest value will be used. Current Display Extent —The extent will be based on the active map or scene. This option is only available when there is an active map. Draw Extent —The extent will be based on a rectangle drawn on the map or scene. This option will create a feature class in the project geodatabase and add a layer to the map. The feature class will have the same coordinate system as the map. Note: This option is not available in the Environments dialog box. It is only available from a tool parameter with an extent data type or from the Environments tab on a tool dialog box. Note: When the Enable and disable editing from the Edit tab editing option is checked, you must enable editing on the Edit ribbon tab to draw the extent. Extent of a Layer —The extent will be based on an active map layer. Use the drop-down list to choose an available layer or use the Extent of data in all layers option to get the combined extent of all active map layers, excluding the basemap. This option is only available when there is an active map with layers. Each map layer has the following options: All Features —The extent of all features in the layer. Selected Features —The extent of the selected features in the layer. Visible Features —The extent of the visible features in the layer. Note: The extents from the Selected Features and Visible Features options are only available for feature layers. Browse —The extent will be based on an existing dataset. Clipboard —The extent can be copied to and pasted from the clipboard. Copy Extent —Copies the extent coordinates and coordinate system to the clipboard. Use Paste Extent —Pastes the extent coordinates and, optionally, the coordinate system from the clipboard. If the clipboard values do not include a coordinate system, the extent will use the map’s coordinate system. Note: The extent coordinates are copied to and pasted from the clipboard using the same formatting and order as the ArcPy Extent object: x-min, y-min, x-max, y-max, and the spatial reference. Reset Extent —The extent will be reset to the default value. Manually entered coordinates—The coordinates must be numeric values and in the active map's coordinate system. Caution: The map may use different display units than the entered coordinates. The use of a cardinal direction (N, S, E, W) is not supported. Use a negative value sign for south and west coordinates.	Extent
Wait for job completion (Optional)	Specifies whether the tool will continue to run while the cache job runs on ArcGIS Online or Portal for ArcGIS. Checked—The tool will continue to run while the cache job runs on ArcGIS Online or Portal for ArcGIS. Using this option, you can request detailed progress reports at any time and view the geoprocessing messages as they appear. This is the default. Unchecked—A job will be submitted to the portal, allowing you to perform other geoprocessing tasks in ArcGIS Pro or close it. Use this option when you are building a cache automatically at the time you publish the service. You can also set this option on any other cache that you build.	Boolean
Portal URL (Optional)	The URL of the portal.	String

Derived Output

Label	Explanation	Data Type
Output Map Service URL	The output URL.	String

Python

arcpy.server.ManageMapServerCacheTiles(input_service, scales, update_mode, {num_of_caching_service_instances}, {area_of_interest}, {update_extent}, {wait_for_job_completion}, {portal_url})

Name	Explanation	Data Type
input_service	The web tile layer, web imagery layer, or map image layer whose cache tiles will be updated.	Image Service; Map Server
scales [scales,...]	A list of scale levels at which tiles will be created.	Double
update_mode	Specifies the mode that will be used to update the cache. RECREATE_EMPTY_TILES—Only tiles that are empty will be created. Existing tiles will be left unchanged. This option is not available for web tile layers published to ArcGIS Online. RECREATE_ALL_TILES—Existing tiles will be replaced and new tiles will be added if the extent has changed. DELETE_TILES—Tiles will be deleted from the cache. The cache folder structure will not be deleted.	String
num_of_caching_service_instances (Optional)	The total number of instances of the System/CachingTools service that will be dedicated to running this tool. If the default value of -1 is used, all the caching tool instances of the ArcGIS Enterprise setup will be used. Use a lower value to use fewer caching tool instances. You can increase the Maximum number of instances per machine setting of the System/CachingTools service using the Service Editor window available through an administrative connection to ArcGIS Server. Ensure that the server machines can support the chosen number of instances. When connecting to a stand-alone server, the default number of instances is equal to the value of the Maximum number of instances setting of the caching tool service.	Long
area_of_interest (Optional)	An area of interest that will constrain where tiles will be created or deleted. This parameter is useful for managing tiles for irregularly shaped areas. It is also useful when precaching some areas and leaving less-visited areas uncached. If you do not provide a value for this parameter, the default value uses the full extent of the map.	Feature Set
update_extent (Optional)	A rectangular extent used to create or delete tiles, depending on the value of the update_mode parameter. If both the update_extent and area_of_interest parameter values are specified, the area_of_interest value will be used. MAXOF—The maximum extent of all inputs will be used. MINOF—The minimum area common to all inputs will be used. DISPLAY—The extent is equal to the visible display. Layer name—The extent of the specified layer will be used. Extent object—The extent of the specified object will be used. Space delimited string of coordinates—The extent of the specified string will be used. Coordinates are expressed in the order of x-min, y-min, x-max, y-max.	Extent
wait_for_job_completion (Optional)	Specifies whether the tool will continue to run while the cache job runs on ArcGIS Online or Portal for ArcGIS. WAIT—The tool will continue to run while the cache job runs on ArcGIS Online or Portal for ArcGIS. Using this option, you can request detailed progress reports at any time and view the geoprocessing messages as they appear. This is the default. It is recommended that you use this option in Python scripts. DO_NOT_WAIT—A job will be submitted to the server, allowing you to perform other geoprocessing tasks. Use this option when you are building a cache automatically at the time you publish the service. You can also set this option on any other cache that you build.	Boolean
portal_url (Optional)	The URL of the portal.	String

Derived Output

Name	Explanation	Data Type
out_job_url	The output URL.	String

Code sample

ManageMapServerCacheTiles example (stand-alone script)

The following demonstrates how to re-create all cache tiles for a map or image service using an area of interest.

# Name: ManageMapServerCacheTiles.py
# Description: The following stand-alone script demonstrates how to Recreate all 
#               cache tiles for for a map or image service using an area of interest.
#               This tool works for weblayers published to ArcGIS Enterprise and ArcGIS Online.
#               and for map and image services on a stand alone ArcGIS Server

# Example: This sample script updates map cache tiles.

import arcpy
import os

# Sign in to portal
myPortal= "https://www.myArcGISEnterprise.com/webadaptor"
arcpy.SignInToPortal(myPortal, "MyUserName", "MyPassword")
serviceName= "MyCounty"
serviceType= "MapServer"
myPortalServiceURL = (myPortal + "/" + "rest/services" +"/" + serviceName + "/" + serviceType)


# Stand alone ArcGIS Server
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
serviceName= "MyCounty"
serviceType= "MapServer"
myServerServiceURL= target_server_connection + "/" + serviceName + "." + serviceType


#variables for reporting
currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = 'C:/data/report_%s.txt' % arg1


# List of input variables for map or image service 
scales = [500000,250000]
numOfCachingServiceInstances = 8
updateMode = "RECREATE_ALL_TILES"
areaOfInterest = "C:/data/shp/CaTxFlMaMin.shp"
waitForJobCompletion = "WAIT"
updateExtents = ""
portalURL =""

# Variables for reporting
currentTime = datetime.datetime.now()
arg1 = currentTime.strftime("%H-%M")
arg2 = currentTime.strftime("%Y-%m-%d %H:%M")
file = 'C:/data/report_%s.txt' % arg1

# Print results of the script to a report
report = open(file,'w')

try:
    result = arcpy.server.ManageMapServerCacheTiles(mytest, scales, updateMode,
                                                    numOfCachingServiceInstances, areaOfInterest,
                                                    updateExtents, waitForJobCompletion,
                                                    portalURL)
    while result.status < 4:
        time.sleep(0.2)
    resultValue = result.getMessages()
    report.write ("completed " + str(resultValue))

    print ("Created cache tiles for given schema successfully for " + serviceName )
    
except Exception as e:
    # If an error occurred, print line number and error message
    import traceback, sys
    tb = sys.exc_info()[2]
    report.write("Failed at step 1 \n" "Line %i" % tb.tb_lineno)
    report.write(e.message)
report.close()

print ("Completed update of cache tiles for " + serviceName)

Environments

Current Workspace

Licensing information

• Basic: Yes
• Standard: Yes
• Advanced: Yes