ImportToolbox

Summary

Imports a geoprocessing toolbox for use in ArcPy, allowing access to the toolbox's associated tools.

Note:

This function is equivalent to the AddToolbox function.

Discussion

While any of the core ArcGIS toolboxes are accessible in a script by default, custom or third-party toolboxes must be added using ImportToolbox to use them in a script.

Other toolboxes may be included in any number of various folders or geodatabases and may have many different origins; they may be toolboxes you created, toolboxes created internally by your organization, or toolboxes you downloaded from ArcGIS Online or other sites. In any case, these toolboxes must be imported into ArcPy before they can be used as tools in Python.

Geoprocessing services can also be imported using a semicolon delimiter.

Parameter	Syntax
input_file	"SOAP_URL;servicename;{username};{password}" "SOAP_URL;servicename;UseSSOIdentityIfPortalOwned" "SOAP_URL;servicename;token={token};{referer}" "<full path to AGS connection file>;servicename"

The URL must be the SOAP URL to allow Python to access your services. In most cases, the URL will be https://machine.domain.com/webadaptor/services. If your service is in a folder on ArcGIS Server, use the <folder name>/<service name> format instead of the servicename format specified below. A username and password are not necessary if the geoprocessing service is public.

To allow any user to access your tool, use the UseSSOIdentityIfPortalOwned keyword. Running ImportToolbox will then prompt the Sign In dialog box if a user is not already signed in or will succeed if they are already signed in.

import arcpy
toolbox = "https://logistics.arcgis.com/arcgis/services;World/ServiceAreas;UseSSOIdentityIfPortalOwned"
arcpy.ImportToolbox(toolbox)
arcpy.ServiceAreas.GenerateServiceAreas()

Note:

The Sign In dialog box will be used, running a stand-alone Python file.

import arcpy
arcpy.SignInToPortal()
arcpy.ImportToolbox("https://domain.machine.com/webadaptor/services;ExtractLandUseData;UseSSOIdentityIfPortalOwned")
preprocess_result = arcpy.ExtractLandUseData.step1preprocess()
analyze_result = arcpy.ExtractLandUseData.step2analyze()

If a token has been previously obtained, it can also be used with ImportToolbox.

import arcpy
token = 'sadsa213d2j32jsdw02dm2'
referrer = 'https://www.arcgis.com/'
toolbox = 'https://logistics.arcgis.com/arcgis/services;' + \
      'World/ServiceAreas;token={};{}'.format(token, referrer)
arcpy.ImportToolbox(toolbox)
result = arcpy.ServiceAreas.GenerateServiceAreas()

ImportToolbox also supports working with secured geoprocessing services using an ArcGIS Server connection file (.ags). Using an .ags file allows credentials to be stored in the file, hidden from sight.

import arcpy
arcpy.ImportToolbox('c:/logistics/logistics.ags;World/ServiceAreas')
arcpy.ServiceAreas.GenerateServiceAreas()

Once the toolbox is imported, use the IsSynchronous function to determine if the geoprocessing service is synchronous or asynchronous. If it's asynchronous, check the status of the running job frequently until the job is finished whenever you access the geoprocessing service outside the Python window in ArcGIS AllSource. See the third example of the Result class for the sample code.

Syntax

ImportToolbox (input_file, {module_name})

Parameter	Explanation	Data Type
input_file	The geoprocessing toolbox that will be accessed from ArcPy.	String
module_name	If the toolbox does not have an alias, the module_name value is required. When a tool is accessed through the ArcPy site package, the toolbox alias where the tool is contained is a required suffix (arcpy.<toolname>_<alias> or arcpy.<alias>.<toolname>). Since ArcPy depends on toolbox aliases to access and run the correct tool, aliases are important when importing custom toolboxes. It is recommended that you define a custom toolbox's alias; however, if the toolbox alias is not defined, a temporary alias can be set as the second parameter.	String

Return Value

Data Type	Explanation
Module	Returns the imported module. If needed, tool names can be accessed from the module's __all__ property.

Code sample

ImportToolbox example 1

Import a geoprocessing toolbox for use in ArcPy.

import arcpy

# Import custom toolbox
arcpy.ImportToolbox("c:/tools/My_Analysis_Tools.atbx")

try:
    # Run tool in the custom toolbox.  The tool is identified by the tool name 
    # and the toolbox alias.
    arcpy.myanalysis.GetPoints("c:/data/forest.shp")
except arcpy.ExecuteError:
    print(arcpy.GetMessages(2))

ImportToolbox example 2

Import a publicly available toolbox.

import arcpy
tbx = 'https://machine.domain.com/arcgis/services/;Utilities/PrintingTools'
arcpy.ImportToolbox(tbx)
arcpy.PrintingTools.GetLayoutTemplatesInfo()