Skip To Content

Migrate services with the UpdateArcMapServices utility

After ArcGIS Enterprise 10.9.1, ArcGIS Server will no longer support the ArcMap service runtime. Only services using the ArcGIS Pro service runtime will be supported, both for newly published services and existing services on an upgraded server site.

It is recommended that you migrate, republish, or remove all services that use the ArcMap service runtime before it is no longer supported.

Learn more about migrating 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

Unlike the Edit Runtime operation in ArcGIS Server Manager, the command utility allows you to migrate image and geodata services in addition to map services. However, there are still limitations on which services can be migrated to the ArcGIS Pro service runtime. To identify these services, run the utility in analysis mode. The result window and HTML report categorize ineligible services based on their reason for ineligibility.

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.

Learn more about configuring service instance settings

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:

ParameterDescription

-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 user name for the Primary Site Administrator of the ArcGIS Server site. If your site's Primary Site Administrator account is unavailable, specify an account user name 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 begins authoring content in ArcGIS Pro to be republished.

GIS staff members also use the 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.