Summary
The GeoprocessingSharingDraft class allows you to create a service definition draft file (.sddraft) for a web tool for ArcGIS Enterprise or a geoprocessing service for ArcGIS Server.
Discussion
To create a GeoprocessingSharingDraft object, use the CreateSharingDraft function or create a GeoprocessingSharingDraft object directly using keyword arguments.
- To share a web tool, set the serverType parameter to FEDERATED_SERVER and the serviceType parameter to WEB_TOOL.
- To share a geoprocessing service, set the serverType parameter to STANDALONE_SERVER and the serviceType parameter to GP_SERVICE.
After the GeoprocessingSharingDraft object has been configured, it can be saved to a service definition draft file (.sddraft) using the exportToSDDraft method. It can then be staged and shared to either ArcGIS Enterprise or ArcGIS Server using the Stage Service and Upload Service Definition tools. For more information, see Introduction to arcpy.sharing.
Syntax
GeoprocessingSharingDraft (**kwargs)
| Parameter | Explanation | Data Type |
**kwargs | All properties supported by the GeoprocessingShaingDraft object can be used as keyword arguments. | String |
Properties
| Property | Explanation | Data Type |
| GPStringValues (Read and Write) | A list of parameter names for which the data type will become a string once published. If multiple tools are included in the web tool, parameter names must be qualified with the tool name, such as ["CreateHexagons.Input_Areal_Unit", "Select_Features.New_Expression"]. This only applies to areal unit, SQL expression, spatial reference, coordinate system, envelope, and extent data types. There is no effect for parameters with other data types. If you don't specify a parameter in this list, and the ArcGIS GIS Server machine you published to supports these newer types, the data types will be converted to the applicable parameter name (for example, GPArealUnit) by default. | List |
| capabilities (Read and Write) | Specifies the capabilities a service will support.
| String |
| choiceLists (Read and Write) | Constrains values for any input parameter with a choice list input mode in the web tool or geoprocessing service. The choice list and its values must be created before using this property; you cannot use this property to add new values to the choice list. If you have a feature or raster input, you must create the layer for each value in the choice list first and use this property to constrain the values. The property uses a dictionary with the service task and parameter name as the key, and a list of the string values as the value, for example, {"ServiceTaskName.parameterName":["string1", "string2"]}. The default value is None. | Dictionary |
| constantValues (Read and Write) | A list of parameter names to be set as a constant. If multiple tools are included, parameter names must be qualified with the tool name, for example, ["toolX.parameterA", "toolY.parameterD"]. The default value is None. | List |
| convertFeatureLayerURL (Read and Write) | Specifies whether the feature layer URL will be converted to a file geodatabase feature class. This property is used to preserve the URL of a feature layer or service for the tool input or output parameter or project data. It can only be used when publishing to ArcGIS Enterprise or ArcGIS Server 11.2 or later.
| Boolean |
| copyDataToServer (Read and Write) | Specifies whether the data referenced in the result will be copied to the server. If the value is True, all data in the result will be copied, including data that is registered with the server. If the value is False, only data that is not registered with the server will be copied. Data registered with the federated server will be referenced by the service. The default value is False. | Boolean |
| description (Read and Write) | The description of the web tool or geoprocessing service. The default value is None. | String |
| draftValue (Read and Write) | A list of geoprocessing Result objects used for creating the service definition draft. This is required if you use the keyword arguments without running the CreateSharingDraft function. | List |
| enableOutputFeatureService (Read and Write) | Specifies whether the optional Output feature service name parameter will be available with the name esri_out_feature_service_name. The default value is None. To set this property to True, the resultMapService value must be False, the executionType value must be Asynchronous, and the serviceType value must be WEB_TOOL. If not specified, this property will be set to True automatically when all of the following conditions are met:
See Use web tools with an output feature service for more information about output feature services. | Boolean |
| enableOutputImageService (Read and Write) | Specifies whether the optional Output Image Service parameter will be available with the name esri_out_image_service. The default value is False. To set this property to True, the resultMapService value must be False and the executionType value must be Asynchronous. See Use web tools with output image service for more information about output image services. | Boolean |
| executionType (Read and Write) | Specifies how the client (the application using the task) will interact with the server and get the result from the task. ArcGIS AllSource handles both processing types natively. The default value is Asynchronous.
| String |
| maxInstances (Read and Write) | The maximum number of instances a web tool or service can start and make available for use. For heavily used web tools or services, you can increase this value. Ensure that the server has adequate hardware to support the maximum number of instances indicated. | Integer |
| maxUsageTime (Read and Write) | The maximum time, in seconds, that a service can be used. You can increase the default of 600 seconds (10 minutes) for long-running geoprocessing tasks. Alternatively, you can reduce this time to ensure that a client will not misapply the service. The default value is 600. | Integer |
| maxWaitTime (Read and Write) | The maximum time, in seconds, that a client will wait to connect to an instance before timing out. When all instances are busy processing requests, subsequent requests are queued. If this time-out elapses before an instance becomes available, the task will fail. The default value is 60. | Integer |
| maximumRecords (Read and Write) | The maximum number of results the web tool or service can return to a client. Setting this value to a large number means the GIS server can handle sending that number of individual records or features to the client. If you don't want to return any features, set this value to 0 (zero). Typically, you set this value to zero only when you enable the view result with a map service. The default value is 1000. | Integer |
| messageLevel (Read and Write) | Specifies the message level that will be used for the web tool or geoprocessing service. The following is a list of valid message levels the service will return to the client:
The default is Error. | String |
| minInstances (Read and Write) | The minimum number of instances a service will start and make available for use. For heavily used services, you can increase this value. The default value is 1. | Integer |
| offline (Read and Write) | Specifies whether an offline service definition will be saved. The default value is False.
| Boolean |
| offlineTarget (Read and Write) | Specifies 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. You can use this property in the following ways:
| String |
| overwriteExistingService (Read and Write) | Specifies whether an existing web tool or geoprocessing service will be overwritten. The default value is False. | Boolean |
| portalFolder (Read and Write) | The name of the folder of the portal that will be published as a web tool. The default folder is the root folder in My Content. This property is only available when serverType is FEDERATED_SERVER. | String |
| removeDefaultValues (Read and Write) | A list of parameter names for which the default values will be removed in the web tool. If multiple tools are included in the web tool, parameter names must be qualified with the tool name, such as ["BufferModel.Output_Feature_Class", "BufferModel.Distance_value_or_field"]. To remove the default values for all parameters use the keyword REMOVE_ALL in the format ["BufferModel.REMOVE_ALL"]. | List |
| resultMapService (Read and Write) | Specifies whether the result of all tasks with the service will be viewable as a map (in addition to other results of the task). When True, the map will be created on the server using a map service for transport back to the client as an image (a .jpeg file, for example). The symbology, labeling, transparency, and all other properties of the returned map are the same as the settings of the output layer. If you are creating result layers in the Python scripting environment (outside ArcGIS AllSource), default symbology will be used. To maintain control over symbology, create the layer files with symbology and use them to modify the output symbology of the task. When True, a map service is automatically created on the server with the same name as the web tool or geoprocessing service. The default value is False. | Boolean |
| serverFolder (Read and Write) | The folder name that will be published to the server. If the folder does not currently exist, it will be created. The default folder is the server root level. The default value is None. | String |
| serverType (Read and Write) | Specifies the server type that was used when the sharing draft was created and is supported for sharing.
| String |
| serviceName (Read and Write) | The name of the web tool or geoprocessing service. This is the name people will see and use to identify the service. The name can only contain alphanumeric characters and underscores. For a web tool, spaces are allowed. For a geoprocessing service, no spaces or special characters are allowed. The name cannot be more than 120 characters. The default value is None. This is required if you use the keyword arguments without running the CreateSharingDraft function. | String |
| serviceType (Read and Write) | Specifies the service type that was used when the sharing draft was created and will be shared.
| String |
| summary (Read and Write) | The web tool or service summary. Use this property to override the user interface summary or to provide a summary if one does not exist. The summary provided here will not persist back to the original geoprocessing tool. The default value is None. | String |
| tags (Read and Write) | The web tool or service tags. Use this property to override the user interface tags or to provide tags if they do not exist. The tags provided here will not persist back to the original geoprocessing tool. The default value is None. | String |
| targetServer (Read and Write) | The server where the web tool or geoprocessing service will be published. This property is required if the offline property is set to False, which is the default. If the serverType property is set to FEDERATED_SERVER, provide the server URL to the ArcGIS Enterprise portal federated server. If the serverType property is set to STANDALONE_SERVER, the following are supported:
| String |
Method Overview
| Method | Explanation |
| analyzeSDDraft () | The analyzeSDDraft method analyzes the service definition draft before staging a service. The method can return a number of errors and warnings, such as for missing metadata, copying data to the server, or incompatible parameters. Use this method after running the exportToSDDraft method successfully. If there is no service definition draft file generated, there will be an error when trying to use this method. |
| exportToSDDraft (out_sddraft) | Converts a GeoprocessingSharingDraft to a service definition draft file (.sddraft). |
Methods
analyzeSDDraft ()
| Data Type | Explanation |
| Dictionary | A dictionary containing analyzer errors and warnings. Both the errors and the warnings in the dictionary will be provided as a list of tuples, with an analyzer code and an analyzer message in each tuple, if any. If there are no errors or warnings, the errors key or the warnings key in the dictionary will have an empty list as the value. |
The following is a sample return of the analyzeSDDraft function showing no analyzer error but one analyzer warning:
{
'errors': [],
'warnings': [
(24032, 'Data source used by CustomizedModel is not registered with the server and will be copied to the server: raster_data')
],
'messages': []
}exportToSDDraft (out_sddraft)
| Parameter | Explanation | Data Type |
out_sddraft | A string that represents the path and file name for the output service definition draft file (.sddraft). | String |
Code sample
The following script creates a GeoprocessingSharingDraft object using keyword arguments. It will publish a web tool to ArcGIS Enterprise when the script finishes running. Because the input parameter of the tool is a feature layer, the input mode of the web tool parameter is a choice list, and an analyzer warning about the data being copied to the federated ArcGIS Server will be issued.
import arcpy
import os
# Sign in to portal
arcpy.SignInToPortal("https://portal.domain.com/webadaptor",
"MyUsername", "MyPassword")
# Set output file names
outdir = r"C:\Project"
service_name = "GeoprocessingSharingDraftExample"
federated_server_url = "https://server.domain.com/webadaptor"
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)
# Run the tool and set the history to a result object
arcpy.ImportToolbox(os.path.join(outdir, "MyAnalysisTools.atbx"))
result = arcpy.reports.MyCustomAnalysis(os.path.join(outdir, "parcels.gdb", "taxlots"), "40", "MyOutput.pdf")
# Create GeoprocessingSharingDraft using keyword arguments
sddraft = arcpy.sharing.GeoprocessingSharingDraft(serverType="FEDERATED_SERVER", serviceType="WEB_TOOL",
serviceName=service_name, draftValue=[result], targetServer=federated_server_url,
GPStringValues=["Input_Areal_Unit"])
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Get the analyzer messages
analyzer_results = sddraft.analyzeSDDraft()
if len(analyzer_results["errors"]) > 0:
# Display the analyzer error or processing error messages
for code, message in analyzer_results["errors"]:
print (message)
# Raise an exception and exit the script
raise arcpy.ExecuteError
# Display the analyzer warning messages using the analyze function
for code, message in analyzer_results["warnings"]:
print (message)
# Run Stage Service tool
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Share to portal
arcpy.server.UploadServiceDefinition(sd_output_filename, federated_server_url)The following script creates a web tool service definition draft file (.sddraft). The service definition draft file is then staged and published to ArcGIS Enterprise as a web tool. Since the first tool input parameter of the tool is a feature class, the input mode of the web tool parameter is user defined.
import arcpy
import os
# Sign in to portal
arcpy.SignInToPortal("https://portal.domain.com/webadaptor",
"MyUsername", "MyPassword")
# Set output file names
outdir = r"C:\Project"
service_name = "GeoprocessingSharingDraftExample"
federated_server_url = "https://MyFederatedServer.domain.com/serverWebadaptor"
toolbox = os.path.join(outdir, "MyAnalysisTools.tbx")
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)
# Run the tool and set to a result object
arcpy.ImportToolbox(toolbox)
result = arcpy.reports.MyCustomAnalysis(os.path.join(outdir, "parcels.gdb", "taxlots"), "40", "MyOutput.pdf")
# Create GeoprocessingSharingDraft and set its properties
sddraft = arcpy.sharing.CreateSharingDraft("FEDERATED_SERVER", "WEB_TOOL", service_name, result)
sddraft.targetServer = federated_server_url
sddraft.description = "This is description"
sddraft.summary = "This is summary"
sddraft.tags = "tag1, tag2"
sddraft.serverFolder = "MyServerFolder"
sddraft.portalFolder = "MyPortalFolder"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
try:
# Run Stage Service tool
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Display the analyzer warning messages
print(arcpy.GetMessages(1))
# Share to portal
arcpy.server.UploadServiceDefinition(sd_output_filename, federated_server_url)
except arcpy.ExecuteError:
# Display the analyzer error or processing error messages
print(arcpy.GetMessages(2))The following script overwrites a web tool service definition draft file (.sddraft). If the service name already exists, the web tool will be overwritten. Otherwise, a new web tool will be created. Since the first tool input parameter is a layer and the choiceLists parameter of the GeoprocessingSharingDraft class contains two layers, the input mode of the web tool parameter is a choice list containing two layers.
import arcpy
import os
# Sign in to portal
arcpy.SignInToPortal("https://portal.domain.com/webadaptor",
"MyUsername", "MyPassword")
# Set output file names
outdir = r"C:\Project\Output"
service_name = "GeoprocessingSharingDraftExample"
federated_server_url = "https://MyFederatedServer.domain.com/serverWebadaptor"
toolbox = os.path.join(outdir, "MyAnalysisTools.tbx")
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)
# Run the tool and set to a result object
arcpy.management.MakeFeatureLayer(os.path.join(outdir, "parcels.gdb", "taxlots1"), "taxlotslayer1")
arcpy.management.MakeFeatureLayer(os.path.join(outdir, "parcels.gdb", "taxlots2"), "taxlotslayer2")
arcpy.ImportToolbox(toolbox)
result = arcpy.reports.MyCustomAnalysis("taxlotslayer1", "40", "MyOutput.pdf")
# Create GeoprocessingSharingDraft and set overwrite and choicelists properties
sddraft = arcpy.sharing.CreateSharingDraft("FEDERATED_SERVER", "WEB_TOOL", service_name, result)
sddraft.targetServer = federated_server_url
sddraft.description = "This is description"
sddraft.summary = "This is summary"
sddraft.tags = "tag1, tag2"
sddraft.serverFolder = "MyServerFolder"
sddraft.portalFolder = "MyPortalFolder"
sddraft.overwriteExistingService = True
sddraft.choicelists = {"mywebtooltask.parameter1": ["taxlotslayer1", "taxlotslayer2"]}
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
try:
# Run Stage Service tool
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Display the analyzer warning messages
print(arcpy.GetMessages(1))
# Share to portal
arcpy.server.UploadServiceDefinition(sd_output_filename, federated_server_url)
except arcpy.ExecuteError:
# Display the analyzer error or processing error messages
print(arcpy.GetMessages(2))The following script creates an offline service definition for the target portal version and publishes it as a web tool.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "GeoprocessingSharingDraftExample"
toolbox = os.path.join(outdir, "MyAnalysisTools.tbx")
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)
# Run the tool and set to a result object
arcpy.ImportToolbox(toolbox)
result = arcpy.reports.MyCustomAnalysis(os.path.join(outdir, "parcels.gdb", "taxlots"), "50", "MyOutput.pdf")
# Create GeoprocessingSharingDraft and set offline and offlineTarget properties
server_type = "FEDERATED_SERVER"
sddraft = arcpy.sharing.CreateSharingDraft("FEDERATED_SERVER", "WEB_TOOL", service_name, result)
sddraft.offline = True
# Set offlineTarget property to "11" for ArcGIS Enterprise 11.0 or later
# The default is ArcGIS Enterprise 10.9.1 or earlier
sddraft.offlineTarget = "10x"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
# Run Stage Service tool
print("Start Staging")
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Sign in to portal to upload and publish
arcpy.SignInToPortal("https://portal.domain.com/webadaptor",
"MyUserName", "MyPassword")
# Share to portal
print("Start Uploading")
arcpy.server.UploadServiceDefinition(sd_output_filename, server_type)
print("Finish Publishing")The following script creates a geoprocessing service service definition draft file (.sddraft). The script service definition draft file is then staged and published to ArcGIS Server as a geoprocessing service. Since the first tool input parameter of the tool is a feature class, the input mode of the geoprocessing parameter is user defined.
import arcpy
import os
# Set output file names
outdir = r"C:\Project\Output"
service_name = "GeoprocessingSharingDraftExample"
toolbox = os.path.join(outdir, "MyAnalysisTools.tbx")
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)
# Run the tool and set to a result object
arcpy.ImportToolbox(toolbox)
result = arcpy.reports.MyCustomAnalysis(os.path.join(outdir, "parcels.gdb", "taxlots"), "40", "MyOutput.pdf")
# Create GeoprocessingSharingDraft
target_server_connection = os.path.join(outdir, "gp_publisher_conn.ags")
sddraft = arcpy.sharing.CreateSharingDraft("STANDALONE_SERVER", "GP_SERVICE", service_name, result)
sddraft.targetServer = target_server_connection
sddraft.description = "This is description"
sddraft.summary = "This is summary"
sddraft.tags = "tag1, tag2"
sddraft.serverFolder = "MyServerFolder"
# Create Service Definition Draft file
sddraft.exportToSDDraft(sddraft_output_filename)
try:
# Run Stage Service tool
arcpy.server.StageService(sddraft_output_filename, sd_output_filename)
# Display the analyzer warning messages
print(arcpy.GetMessages(1))
# Publish to stand-alone server
arcpy.server.UploadServiceDefinition(sd_output_filename, target_server_connection)
except arcpy.ExecuteError:
# Display the analyzer error or processing error messages
print(arcpy.GetMessages(2))