Summary
The MapServiceDraft class allows you to create a service definition draft file (.sddraft) for a map service that copies all data or references registered data to ArcGIS Server.
Discussion
To create the MapServiceDraft object, use the arcpy.sharing.CreateSharingDraft function and set the server_type parameter to STANDALONE_SERVER and the service_type parameter to MAP_SERVICE. The MapServiceDraft object can then be configured by setting service level properties and metadata properties. Use the targetServer property to specify the server to which the map service is published.
You can also set map service properties by modifying the .sddraft file. If no value is specified for a property, the default is set. You must set the appropriate property values even if you are overwriting a map service that has existing configured properties.
Note:
If metadata properties (credits, description, summary, tags, and useLimitations) are not set or consist of empty strings, the map service will source metadata from the map.
For more information about authoring metadata, see View and edit metadata.
After the MapServiceDraft object is configured, it can be saved to a service definition draft file (.sddraft) using the exportToSDDraft method. It can then be staged and shared to ArcGIS Server using the Stage Service and Upload Service Definition tools. For more information, see What is the arcpy.sharing module.
Once the .sddraft file has been staged and uploaded to the server, the tools in the Caching toolset, such as the Manage Map Server Cache Tiles tool, can be used to create and manage map server caches for faster display of map services.
Code samples are available for the following:
- Publish a map service to a server folder
- Overwrite a map service
- Publish a map service with a feature service
- Publish a cached map service
- Publish a map service that draws from existing cache
- Analyze and register a data store
- Set a time zone and configure pooling
- Create and publish an offline service definition
- Analyze to confirm map is set to allow assignment of unique numeric IDs
Properties
| Property | Explanation | Data Type |
| cache.cacheOnDemand (Read and Write) | Specifies whether tiles that are not cached will be created on demand when a client application requests them. The default value is False. | Boolean |
| cache.configuration (Read and Write) | The path and file name of a predefined tiling scheme .xml file generated by the Generate Map Server Cache Tiling Scheme tool. | String |
| cache.exportTiles (Read and Write) | Specifies whether clients will be allowed to download map tiles for offline use. The default value is False. | Boolean |
| cache.exportTilesCount (Read and Write) | The maximum number of tiles that can be downloaded in a single request. This property is only honored if the cache.exportTiles property is set to True. The default value is 100000. | Integer |
| cache.useExistingCache (Read and Write) | Specifies whether the data will be drawn from an existing cache. This property is only honored if the enableCache property is set to True. The default value is False. | Boolean |
| checkUniqueIDAssignment (Read and Write) | Specifies whether the map will be analyzed to confirm that the Allow assignment of unique numeric IDs for sharing web layers option in Map Properties is enabled. For more information, see Assign layer IDs. | Boolean |
| copyDataToServer (Read and Write) | Specifies whether the data in the map will be copied to the server. A value of True will copy all of the data in the map, including data that is registered with your server. A value of False will only copy data that is not registered with your server. Data registered with your server will be referenced by the service. The default value is False. | Boolean |
| credits (Read and Write) | The credits of the map service. | String |
| description (Read and Write) | The description of the map service. | String |
| enableCache (Read and Write) | Specifies whether the web layer will draw dynamically or from a cache. The default value is False. | Boolean |
| enableDynamicWorkspaces (Read and Write) | Specifies whether users will be allowed to change the appearance or drawing behavior of the web layer. The default value is True. | Boolean |
| extension.feature.allowTrueCurvesUpdates (Read and Write) | Specifies whether web clients will be allowed to update the true curve geometry of a feature with densified geometry. This property is only honored when editing is enabled. The default value is True. | Boolean |
| extension.feature.allowUpdateWithoutMValues (Read and Write) | Specifies whether geometry updates to m-enabled features will be allowed without specifying an m-value. The default value is False. | Boolean |
| extension.feature.featureCapabilities (Read and Write) | The enabled capabilities, separated by commas. The following capabilities are supported:
| String |
| extension.feature.isEnabled (Read and Write) | Specifies whether a feature service will be included. The default value is False. | Boolean |
| extension.feature.onlyAllowTrueCurveUpdatesByTrueCurveClients (Read and Write) | Specifies whether only clients that support true curves, such as ArcGIS Pro, will be allowed to update true curve geometries. This property is only honored when editing is enabled. The default value is True. | Boolean |
| extension.feature.zDefault.enable (Read and Write) | Specifies whether editors will be allowed to add or update features through clients that don't allow a z-value to be given. The default value is False. | Boolean |
| extension.feature.zDefault.value (Read and Write) | The default z-value that will be used when inserting or updating features. This property is only honored if the zDefault.enable property is set to True. The default value is 0. | Double |
| extension.kml.isEnabled (Read and Write) | Specifies whether the KML capability will be enabled. The default value is False. | Boolean |
| extension.ogcFeature.isEnabled (Read and Write) | Specifies whether an OGC Features service will be enabled. The default value is False. | Boolean |
| extension.wcs.isEnabled (Read and Write) | Specifies whether the WCS capability will be enabled. The default value is False. | Boolean |
| extension.wfs.isEnabled (Read and Write) | Specifies whether a WFS service will be enabled. The default value is False. | Boolean |
| extension.wms.isEnabled (Read and Write) | Specifies whether a WMS service will be enabled. The default value is False. | Boolean |
| mapOperations (Read and Write) | The enabled operations, separated by commas. The following operations are supported:
| String |
| maxRecordCount (Read and Write) | The maximum number of records that will be returned by the server during querying. The default value is 2000. | Integer |
| offline (Read and Write) | Specifies whether a server connection will be used. If set to False, you must provide a server URL or an ArcGIS Server connection file (.ags) to the targetServer property to create a service definition draft file (.sddraft) using the exportToSDDraft function. If set to True, a service definition draft file can be created without populating the targetServer property. | Boolean |
| offlineTarget (Read and Write) | The target server version to which the service definition will be published. Specifying a version ensures that the service definition contains content compatible with your server. This property is only honored if the offline property is set to True.
| String |
| overwriteExistingService (Read and Write) | Specifies whether an existing service with the same name will be overwritten. | Boolean |
| pooling.maxInstances (Read and Write) | The maximum number of instances per machine. This property is only honored if the pooling.type property is set to DEDICATED. | Integer |
| pooling.minInstances (Read and Write) | The minimum number of instances per machine. This property is only honored if the pooling.type property is set to DEDICATED. | Integer |
| pooling.type (Read and Write) | The type of instance pooling that will be used.
| String |
| serverFolder (Read and Write) | The name of the server folder where the service will be published. The default folder is the root folder of the server. The folder will be created if it does not already exist. | String |
| serverType (Read Only) | The server type as specified when the MapServiceDraft was created from the CreateSharingDraft function. The only possible value returned from serverType for a MapServiceDraft is STANDALONE_SERVER. A serverType of STANDALONE_SERVER indicates support for creating a map service for ArcGIS Server. | String |
| serviceName (Read and Write) | The name of the map service. This is the name people will see and use to identify the service. The name can only contain alphanumeric characters and underscores. No spaces or special characters are allowed. The name cannot be more than 120 characters. | String |
| summary (Read and Write) | The summary of the map service. | String |
| tags (Read and Write) | The tags of the map service. Multiple tags can be separated by commas. | String |
| targetServer (Read and Write) | The server where the map will be published. The server can be specified using either of the following formats:
For more information, see Connect to a GIS server. Tip:This property can also be used in the in_server parameter in the Upload Service Definition tool. | String |
| timezone.DaylightSavingTime (Read and Write) | Specifies whether the time zone accounts for daylight saving time. The default value is False. | Boolean |
| timezone.ID (Read and Write) | The time zone in which date values are stored. The string value must match one of the official time zone IDs recognized by the Windows operating system. For a list of time zones, see Time zones in the Microsoft documentation. | String |
| useLimitations (Read and Write) | The use limitations of the map service. | String |
Method Overview
| Method | Explanation |
| exportToSDDraft (out_sddraft) | Converts a MapServiceDraft to a service definition draft (.sddraft) file. |
Methods
exportToSDDraft (out_sddraft)
| Parameter | Explanation | Data Type |
out_sddraft | The path and file name for the output service definition draft (.sddraft) file. | String |
Once the MapServiceDraft is configured, it can be saved as a service definition draft (.sddraft) file. It can then be staged and shared to ArcGIS Server using the Stage Service and Upload Service Definition tools.
Code sample
The following script creates a service definition draft file (.sddraft) for a map service and sets metadata properties. The map service is published to a folder in a stand-alone ArcGIS Server site.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set metadata and server folder properties
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.credits = "These are credits"
sddraft.description = "This is description"
sddraft.summary = "This is summary"
sddraft.tags = "tag1, tag2"
sddraft.useLimitations = "These are use limitations"
sddraft.serverFolder = "MyServerFolder"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script overwrites a map service. If the service name already exists, the service will be overwritten. Otherwise, a new service will be created. If you want the map service to have specific properties, you must set property values even if the map service being overwritten already has properties configured. Otherwise, the existing properties will be overwritten with default settings.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set overwrite property
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.overwriteExistingService = True
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script creates a service definition draft file (.sddraft) for a map service that references registered data. The data store must already be registered on the server for the data to be referenced. It then enables the feature capability and sets map service and feature service properties. The .sddraft file is then staged and published to ArcGIS Server.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set copyDataToServer property to false to reference registered data
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.copyDataToServer = False
sddraft.mapOperations = "Map,Data"
sddraft.extension.feature.isEnabled = True
sddraft.extension.feature.featureCapabilities = "Create,Sync,Query"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script publishes a cached map service by calling the Manage Map Server Cache Tiles tool to create map service cache tiles.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.enableCache = True
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
try:
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
warnings = arcpy.GetMessages(1)
print(warnings)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")
# Manage Map server Cache Tiles
# For cache, use multiple scales separated by semicolon (;)
# For example, "591657527.591555;295828763.795777"
arcpy.server.ManageMapServerCacheTiles(target_server_connection + os.sep + service_name + ".MapServer", "591657527.591555", "RECREATE_ALL_TILES")
except Exception as stage_exception:
print("Analyzer errors encountered - {}".format(str(stage_exception)))
except arcpy.ExecuteError:
print(arcpy.GetMessages(2))The following script creates a service definition draft file (.sddraft) for a map service and uses an existing cache to draw the service. The .sddraft file is then staged and published to ArcGIS Server.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.enableCache = True
sddraft.cache.useExistingCache = True
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script creates a service definition draft file (.sddraft) for a map service. The service definition draft file is analyzed during staging. If analyzer 24011 is returned warning that the data source is not registered with the server, the data store is registered using the AddDataStoreItem function.
import arcpy
import os
arcpy.env.overwriteOutput = True
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set copyDataToServer property to False to reference registered data
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.copyDataToServer = False
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage the service and analyze the .sddraft file for registered data store
# Continue publishing only if data store is registered
print("Start Staging")
stage_service = True
while stage_service:
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Get analyzer warnings to check if data store is registered
warnings = arcpy.GetMessages(1)
print(warnings)
# If data store is not registered
if "24011" in warnings:
# Register data store
db_conn = r"C:\Project\db_conn.sde"
register_msg = arcpy.AddDataStoreItem(target_server_connection, "DATABASE", "datastore_name", db_conn)
print("Registered datastore: {0}".format(register_msg))
# Stage the service again
stage_service = True
else:
stage_service = False
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script creates a service definition draft file (.sddraft) for a map service. The data store must already be registered on the server for the data to be referenced. It then sets a time zone for layers with date fields and configures service instance settings. The .sddraft file is then staged and published to ArcGIS Server.
import arcpy
import os
import codecs
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set copyDataToServer property to False to reference registered data, set time zone, and configure pooling options
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.copyDataToServer = False
sddraft.timezone.ID = "Pacific Standard Time"
sddraft.timezone.DaylightSavingTime = True
sddraft.extension.feature.isEnabled = True
sddraft.pooling.type = "DEDICATED"
sddraft.pooling.minInstances = 0
sddraft.pooling.maxInstances = 2
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
print("Finish Publishing")The following script creates an offline service definition for the target server version and publishes it as a map service.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set offline and offlineTarget properties
# The targetServer property is not needed when the offline property is set to True
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.offline = True
# Set offlineTarget property to "ENTERPRISE_11" for ArcGIS Server 11.0 or later
# The default is ArcGIS Server 10.9.1 or earlier
sddraft.offlineTarget = "ENTERPRISE_10x"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Publish to server
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, r"C:\Project\gisserver.ags.esri.com (publisher).ags")
print("Finish Publishing")The following script creates a service definition draft file (.sddraft) for a map service that enables the checkUniqueIDAssignment property. The service definition draft file is analyzed during staging. If the map is not set to allow assignment of unique numeric IDs for sharing web layers, analyzer error 00374 is returned and a message is printed. For more information, see Assign layer IDs.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "MapServiceDraftExample"
sddraft_filename = service_name + ".sddraft"
sddraft_output_filename = os.path.join(outdir, sddraft_filename)
sd_filename = service_name + ".sd"
sd_output_filename = os.path.join(outdir, sd_filename)
# Reference map to publish
aprx = arcpy.mp.ArcGISProject(r"C:\Project\World.aprx")
m = aprx.listMaps('World')[0]
# Create MapServiceDraft and set the check unique ID assignment property
target_server_connection = r"C:\Project\gisserver.ags.esri.com (publisher).ags"
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "MAP_SERVICE", service_name, m)
sddraft.targetServer = target_server_connection
sddraft.checkUniqueIDAssignment = True
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
try:
# Stage Service
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Share to portal
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, server_type)
print("Finish Publishing")
except Exception as stage_exception:
if "00374" in str(stage_exception):
print("The map is not set to allow assignment of unique IDs")
print("Analyzer errors encountered - {}".format(str(stage_exception)))
except arcpy.ExecuteError:
print(arcpy.GetMessages(2))