Once an ArcGIS Server site is upgraded to 11.0 or later, you must migrate, republish, or remove all services that use the ArcMap service runtime. ArcGIS Server no longer supports the ArcMap service runtime, and services that use the ArcMap service runtime are unusable. Only services using the ArcGIS Pro service runtime are supported, both for newly published services and existing services on an upgraded server site.
Learn more about migrating or republishing services
The UpdateArcMapServices command line utility allows you to automate a bulk migration of supported GIS services. The utility offers the following two modes:
- analysis—Run the tool in analysis mode to assess which services in your site are ready to be migrated to the ArcGIS Pro service runtime.
- execution—Once you know which services can be migrated and have corrected conditions that would prevent an eligible service from being migrated, run the tool in execution mode to migrate all eligible services to the ArcGIS Pro service runtime. Service runtime migration won't affect the content or settings of your services.
Prerequisites to migrate a service runtime
The UpdateArcMapServices utility can migrate the following types of services:
- Map services (with or without KML enabled)
- Feature services (map services with feature access enabled)
- Image services
- WMS services (map services with WMS enabled)
- WCS services (map services with WCS enabled)
- WFS services (map services with WFS enabled)
- Network Analysis services (map services with Network Analysis enabled)
- Geodata services
The UpdateArcMapServices command utility allows you to migrate image, geodata, and map services. However, there are limitations on which of these services can be migrated to the ArcGIS Pro service runtime. To identify the services that cannot be migrated, run the utility in analysis mode. The result window and HTML report categorize ineligible services based on their reason for ineligibility.
- Map and image services flagged by code 10900 contain incompatible service capabilities. The schematics capability or custom Server Object Extensions (SOEs) or Server Object Interceptors (SOIs) must be disabled on the map or image service to make it eligible for migration. (You can migrate SOEs and SOIs and add them to the migrated services. See the Migrating ArcObjects SOEs and SOIs to ArcGIS Enterprise SDK blog post for more information.)
- Map services flagged by code 10901 contain incompatible layer types. Raster catalog layers and time-enabled layers created by the Tracking Analyst extension and feature layers from databases that are not supported by ArcGIS Pro cannot be migrated.
- Geodata services flagged by code 10903 were published from databases that are not supported with ArcGIS Pro, specifically those published from IBM Db2 for z/OS and IBM Informix databases. For geodata services that use an unsupported database, you must move the source data to a geodatabase that is in a database supported by ArcGIS Pro before you can republish it.
Certain raster functions applied to the service or raster data sources in the service will not work with the ArcGIS Pro service runtime, such as Python raster functions written in Python 2 and raster functions with certain color ramps. The HTML report does not identify individual services that contain these unsupported raster functions, but the report will notify you that there are services running on the ArcGIS Server site that contain them. Before migrating, replace Python 2 functions with Python 3 functions. You can migrate these services without removing the unsupported raster functions, but the migrated service won't work properly when accessing those functions. If migrated services do not render properly due to unsupported color ramps, contact Esri technical support (in the United States) or your Esri distributor (outside the United States).
Only services published from ArcMap are analyzed. Services originally published from ArcGIS Pro cannot be migrated to the ArcMap service runtime and will not appear in the list of analyzed services.
Service instances
The ArcGIS Pro service runtime supports both dedicated and shared instance types for map services. Therefore, during the migration process, the utility assigns an instance type to each migrated map service. This is based on the default instance type setting on your ArcGIS Server site.
Consider the implications of this before you migrate services. For example, if your ArcGIS Server site's default instance type is shared instances, and you're preparing to migrate a service that receives heavy traffic, consider editing the service to use dedicated instances after migration to ensure that it has adequate resources. If your service has custom SOEs or SOIs and you intend to recompile them and add them back to the service after you migrate, the service cannot use shared instance pooling.
Access the command line utility
The migration utility is hosted in the <ArcGIS Server installation location>\tools\UpdateArcMapServices folder on your ArcGIS Server machine. You can run the UpdateArcMapServices.bat file directly from this location or by referencing the full path to the directory. You must sign in to the ArcGIS Server machine using the ArcGIS Server account login.
When you run the UpdateArcMapServices utility in either mode, an HTML page opens to display tool results. Both modes display counts of the services that are eligible or currently ineligible to be migrated. In execution mode, logs relating to the migration operation are displayed, as well as a count of the services that have successfully been migrated to the ArcGIS Pro service runtime.
Parameters
The utility supports the following input parameters:
| Parameter | Description |
|---|---|
-m, --mode | Specify the mode in which you want the tool to run: analysis mode (the default) assesses and displays the services that are currently eligible and ineligible to be migrated, while execution mode migrates all eligible services to the ArcGIS Pro service runtime. |
-o, --output | Define the directory to which the tool report file will be generated. If undefined, the tool generates the report to a temporary directory on the machine where you run the utility. |
-u, --username | Specify the username for the Primary Site Administrator of the ArcGIS Server site. If your site's Primary Site Administrator account is unavailable, specify an account username for a server administrator or, if the server is federated, a portal administrator. |
-h, --help | Print help for the utility. |
Example usage
A GIS administrator wants all the organization's services to use the ArcGIS Pro service runtime. First, the administrator signs in to ArcGIS Server Manager to make a list of the geoprocessing and geocoding services running on the ArcGIS Server site. These cannot be migrated; they must be republished.
Next, the administrator runs the UpdateArcMapServices utility in analysis mode to determine which map, image, and geodata services contain unsupported capabilities or layers.
The GIS administrator signs in to one of the machines in the ArcGIS Server site using the login that runs the ArcGIS Server service. The administrator opens a command window, accesses the tool directory, and runs the command in analysis mode. Because the HTML report will be shared with colleagues, the administrator specifies a shared directory for the output location.
cd <ArcGIS Server installation location>\arcgis\server\tools\UpdateArcMapServices
UpdateArcMapServices.bat -m analysis -o C:\\Desktop
The tool runs and determines that five of the services in the ArcGIS Server site are currently ineligible for migration. Results are shown at the command line and are listed in the HTML report. The report shows that four of the services have unsupported capabilities enabled (Warning code 10900) and one service contains an unsupported layer type (Warning code 10901).
WARNING: Service [Mapservice1] with extensions [JavaRESTSOE] enabled needs to be addressed. Code 10900. WARNING: Service [Mapservice2] with extensions [JavaMapExtension] enabled needs to be addressed. Code 10900. WARNING: Service [Mapservice3] with extensions [CustomExtension] enabled needs to be addressed. Code 10900. WARNING: Service [Mapservice4] with extensions [JavaMapExtension,JavaRESTSOE] enabled needs to be addressed. Code 10900. WARNING: Service [Imageservice] with data in layers [coral_reefs] needs to be addressed. Code 10901.
GIS staff members review the report and check each of the five services. They determine that the four services with unsupported extensions have custom SOEs enabled and that the other service contains a raster dataset. To allow the first four services to be migrated, they disable the SOEs from each service in ArcGIS Server Manager. They will recompile the SOEs and add them back to the map services after they are migrated to the ArcGIS Pro service runtime.
Because layers cannot be removed from services, they won't migrate the image service. The service is added to the GIS administrator's list of services to be re-created and published in ArcGIS Pro.
When the SOEs are removed from the first four services, the administrator runs the tool in execution mode to migrate all qualifying services from the ArcMap service runtime to the ArcGIS Pro service runtime.
UpdateArcMapServices.bat -m execution
While the tool is running, the administrator monitors the HTML results page to view the logs for each migration task. When the tool completes, each eligible service has been successfully migrated to the ArcGIS Pro service runtime.
The remaining services cannot be migrated. The GIS staff members begin authoring content in ArcGIS Pro to be republished.
GIS staff members also use ArcGIS Enterprise SDK to recompile the JavaRESTSOE, JavaMapExtension, and CustomExtension SOEs. When they have updated the SOEs, they add them back to each of the four map services.