Upgrade Portal for ArcGIS

The Portal for ArcGIS setup is designed to detect and upgrade an existing installation of Portal for ArcGIS. You can choose to upgrade interactively using the setup program or to upgrade silently.

Important:

Before upgrading, carefully review the information for upgrading ArcGIS Enterprise in general, as well as the following information specific to Portal for ArcGIS.

Caution:

Your base deployment, its federated server sites and ArcGIS Pro (if licensed through the portal) will be offline during the upgrade.

Prepare to upgrade

To ensure your upgrade can be successfully completed, review the following sections to prepare before you begin the upgrade process.

Back up your content

Take a a backup of the data and configuration of your ArcGIS Enterprise deployment before upgrading Portal for ArcGIS. To ensure you have the necessary backups complete the following steps:

Verify you have created backups of the following:

Tip:

You can follow steps below to back up your site, or you can use the WebGISDR tool to create a back up of your ArcGIS Enterprise deployment. To do so, follow steps to export ArcGIS Enterprise.
- All data stores deployed through ArcGIS Data Store. See Upgrade ArcGIS Data Store for details on running the backup.
- All federated ArcGIS Server sites. If you need to revert your site to the earlier version, you can import and restore the site. See Back up and restore an ArcGIS Server site configuration for more information.
Determine the amount of disk space allocated to the portal's content, index, db, and temp directories. Validate that the amount of free space available on disk is at least 2.5 times this amount. If not, allocate at least 2.5 times more space on disk.

The Portal for ArcGIS upgrade needs this free space to successfully back up and upgrade your portal's content, site information, and security settings. The default location for these directories is <Portal for ArcGIS installation directory>/arcgisportal. If the content directory resides on a different machine, the same recommendation applies.

The Portal for ArcGIS upgrade needs this free space to successfully back up and upgrade your portal's content, site information, and security settings. The default location for these directories is C:\arcgisportal. If the content directory resides on a different machine, the same recommendation applies.

Upgrade concepts

Keep the following in mind when upgrading:

The time it takes to complete the upgrade varies, depending on how much content your portal contains and how many accounts are registered, as well as how many components and customizations you deploy.
Ensure that members of your organization are aware that upgrading requires downtime and are prepared for the new features and changes that will be introduced in the new version.
If your portal is currently in read-only mode, turn the mode off before running the upgrade.
If you cannot update your current web adaptor, you can alternatively install an updated version of ArcGIS Web Adaptor (IIS) alongside your previous version on the same machine. You must keep the same web adaptor context when upgrading. To do this, uninstall the web adaptor currently configured with your portal, and then install the new version of the web adaptor with the same name used previously. Note that two web adaptors with the same context cannot be installed on the same machine.

Note:

The Portal for ArcGIS setup asks for the account the Windows service will run as. You can upgrade existing content on a shared network directory provided the account running the Windows service has full access to these locations.

If the Windows service is currently running as a LocalSystem account with no password applied, you must first change the account to a local account with a password before proceeding with the upgrade.

Licensing

Keep the following in mind when licensing:

You must obtain a new portal license file from My Esri and reauthorize your software.

Note:

The license file you input during the upgrade is used to license your portal's users and apps. Ensure the new license file is adequate for your current user and app configuration.
Before upgrading Portal for ArcGIS, you must ensure all offline ArcGIS Pro licenses are checked in by your organization members. You can view License activity to see which members have checked out their ArcGIS Pro license for offline use. For information about how to check in an offline license, see Check in an offline license.
The Editor, GIS Professional Standard, and GIS Professional Advanced user type names used in some older versions have changed to Contributor, Professional, and Professional Plus, respectively. You may notice this update when importing a new Portal for ArcGIS license file.
If a member's user type is no longer available after upgrading, you must assign them a different user type. For a list of available user types, see User types.
After upgrading, some user types may include additional apps that were previously available only as add-on licenses. If an app is included with a member's assigned user type, you don't need to assign the member an add-on license for that app. See An introduction to licensing apps to learn more about apps and the user types that include them.
When one or more add-on licenses assigned to members are included with their user types after upgrading, you will see a notice on the Overview tab of the organization page stating that some members have licenses assigned twice. You can unassign duplicate add-on licenses from all applicable members to free up those licenses.
As of 11.4, ArcGIS License Manager is no longer required to enable named user licensing for ArcGIS Pro, ArcGIS Pro extensions, ArcGIS Drone2Map, and ArcGIS AllSource.

Content

Keep the following in mind when working with content:

If you have registered items in your portal from a nonfederated ArcGIS Server site, you do not need to upgrade this ArcGIS Server site to use the site's services with your portal. Services from previous versions of ArcGIS Server can be consumed by Portal for ArcGIS.
If you created a custom basemap or configurable app group, and shared Esri basemaps or ArcGIS Configurable Apps to this group, you must share these items to the group again after upgrade.
If you use ArcGIS Living Atlas of the World content in maps or apps, confirm that the items you use are not in a mature support or deprecated status before you upgrade. At each release, some ArcGIS Living Atlas content is retired and no longer available. If you are using one of these items, it will no longer function once you upgrade. For a list of the ArcGIS Living Atlas content retired at this release, see ArcGIS Living Atlas content life cycles and updates.

Apps

Keep the following in mind when working with apps:

If you have Esri apps configured with your portal, ensure you are at a version that's compatible with the version of Portal for ArcGIS after upgrading.
If you configured ArcGIS Navigator mobile map packages with your portal, you must reconfigure them after upgrading Portal for ArcGIS.

Highly available and replicated environments

To minimize downtime during upgrades, you can set up a duplicate environment and replicate content to it before upgrading the primary environment. To learn more about this upgrade strategy and about how to upgrade your highly available or replicated environment, see Upgrade highly available and replicated environments.

Upgrade using the setup program

From the command prompt, launch the Portal for ArcGIS setup script as the same user that was used to install the existing portal (for example, <CD ROOT or untar directory>/Setup).

You do not need to stop Portal for ArcGIS before launching this script.

Tip:

To launch the setup script from the Portal for ArcGIS setup media, click the setup script, and select the Run in Terminal button.

Choose to continue or exit the upgrade after the setup detects your existing version of Portal for ArcGIS on the target machine. See the following example:

=========================================================================
Portal for ArcGIS <New Version> (Linux)
=========================================================================

Your Portal for ArcGIS <Previous Version> is installed at:

/home/ags/arcgis/portal

Confirm Settings
=========================================================================
Product to upgrade:             Portal for ArcGIS <Previous Version> (Linux)
Location to upgrade:            /home/ags/arcgis/portal

Your Portal for ArcGIS <Previous Version> will be stopped when performing the
upgrade and Portal for ArcGIS <New Version>
will be started after the upgrade completes.

  'y' to continue with these settings
  'q' to exit without upgrading this product

Enter choice [y,q] (y):

Type y, and press Enter to accept the detected settings and continue with the upgrade.

You must authorize your software with a new .json authorization file. When the Portal for ArcGIS upgrade completes, the portal website opens in a browser window.
Start the Portal for ArcGIS setup program, Setup.exe, and read the welcome screen and terms. Click Next when you're ready to proceed.
Read the license agreement and accept it, or exit if you do not agree with the terms.

The features that will be installed display.
Click Install to begin the upgrade. Do not interrupt the installation process.

Note:

This may take some time to complete.
Click Finish to close the installation wizard.

The portal website opens in a browser window.
Clear your browser's cache (including cookies).

Information left over in the cache from the previous version of the website may cause the upgraded website to display incorrectly, and you may not be able to sign in. It's recommended that you clear the cache (including cookies) on all browsers that will view the upgraded portal website.
On the Import license file page, browse to your license .json file that you obtained from My Esri containing authorized user types and apps. Click Continue portal upgrade.

This triggers the upgrade and creates a backup of your portal's content, site information, and security settings. This step will take a few minutes to complete.

Note:

The license file you input during the upgrade is used to license your portal's users and apps. Ensure the new license file is adequate for your current user and app configuration.
Sign in to the machine hosting the ArcGIS Web Adaptor you're using with your portal, and uninstall ArcGIS Web Adaptor. For full instructions, see the uninstallation topic for Java (Linux). Be sure to note the name of the web adaptor before you uninstall it.
Install the web adaptor that will be used with your portal. For full instructions, see the installation topic for Java (Linux). Ensure that you use the web adaptor name that you used in the previous version.
Configure ArcGIS Web Adaptor with your portal. For full instructions, see the configuring topic for Java (Linux).

Note:

If present, the DNS alias should be used to access the web adapter when re-registering with the portal if there is no WebContextURL set in System Properties.
Sign in to the machine hosting the ArcGIS Web Adaptor you're using with your portal, and uninstall ArcGIS Web Adaptor. For full instructions, see the uninstallation topic for IIS or Java (Windows). Be sure to note the name of the web adaptor before you uninstall it.
Install the web adaptor that will be used with your portal. For full instructions, see the installation topic for IIS or Java (Windows). Ensure that you use the web adaptor name that you used in the previous version.
Configure ArcGIS Web Adaptor with your portal. For full instructions, see the configuring topic for IIS or Java (Windows).

Note:

If present, the DNS alias should be used to access the web adapter when re-registering with the portal if there is no WebContextURL set in System Properties.
Verify that you can sign in to the portal through the ArcGIS Web Adaptor URL as an administrator of your organization.

The URL is formatted https://webadaptorhost.example.com/webadaptorname/home.
Note:
- If you receive a notice that post-upgrade steps are required, you must click OK on the message dialog box to complete the required post-upgrade steps. These include upgrading re-indexing content (manual re-indexing is required after every upgrade if the content is in an Amazon S3 bucket or Azure Blob Storage) and updating the association between Portal for ArcGIS machines in a highly available portal.
- If you receive a notice regarding licenses when you sign in to the portal after an upgrade, you may not have imported a license file that meets your current licensing configuration, or your users may be assigned a temporary user type. See Considerations after upgrading Portal for ArcGIS for more details.
Upgrade the remaining ArcGIS Enterprise components.

Upgrade silently

To upgrade silently, complete the following steps:

From the command prompt, launch the Portal for ArcGIS setup script as the same user that was used to install the existing portal

The following example provides the script with arguments required to upgrade Portal for ArcGIS silently.
```
<CD ROOT or untar directory>/Setup -l yes -m silent
```
For the full explanation of arguments that can be used with the setup script, see Install Portal for ArcGIS silently on Linux
From the command prompt, launch the Portal for ArcGIS setup script.

In the following example, the Portal for ArcGIS account used by the software is admin and the password is itsasecret.

<path to Portal for ArcGIS setup download>\setup.exe /qb USER_NAME=admin PASSWORD=itsasecret ACCEPTEULA=yes

For the full explanation of arguments that can be used with the setup script, see Installing Portal for ArcGIS silently
Use the upgradeportal command line utility to complete the upgrade and post-upgrade operations silently.
1. In the command line, browse to your <Portal install directory>/tools/upgradeportal folder.
2. In the command line, browse to your <Portal install directory>\tools\upgradeportal folder.
3. Run the following command:
  
  upgradeportal.sh -lf <path to portal json file> -s
  
  upgradeportal.bat -lf <path to portal json file> -s
  
  For assistance, run the command with -h or --help. You can also use the upgrade operation in the ArcGIS Portal Administrator API to upgrade Portal for ArcGIS. For more information on the upgrade operation, see the Upgrade documentation in the ArcGIS Portal Admin API help.

Post-upgrade tasks

After upgrading Portal for ArcGIS, you may need to complete the following post-upgrade tasks to ensure your deployment functions as expected.

Update WebGISDR properties files created prior to upgrading

If you plan to use a WebGISDR properties file that was created before upgrading ArcGIS Enterprise, review the file before running backup or restore operations. Only properties files that contain encrypted values require updates.

If the properties file includes encrypted values, replace them with their unencrypted values and set the corresponding boolean values that indicate whether a property is encrypted to false.

For more information, see WebGISDR tool properties file.

Manually update utility services

If you use the OfflinePackaging, RasterUtilities, or GeocodingTools utility services, you must manually update them after you upgrade:

Once your upgrade is complete, sign in to ArcGIS Server Manager as the user who owns the utility services.
On the Manage Services section of the Services tab, click the Utilities folder.
Click the Sharing Properties button.
On the dialog box that appears, click Save.

This updates the service in your portal.
Sign in to the portal as an administrator. On the Content tab, locate the service you've updated. Click Share. Update the sharing settings if needed, and click OK.

This updates the service with each group it's shared to.
Repeat these steps for each applicable service.

Configure routing services

If you configure routing services by publishing routing services using your network dataset, it is recommended that you reconfigure your routing services after server upgrade to use the latest capabilities. For geoprocessing based routing services, new service parameters and new service capabilities will only be available when you republish routing services after upgrading your server.

To republish routing services using your network dataset, complete the following steps:

Sign in as a default administrator or custom role with the correct privileges to manage portal settings.
At the top of the site, click Organization and click Settings.
Click Utility services on the left side of the page.
Click Directions and Routing on the right side of the page.
Click Update routing services and choose A network dataset that I'd like to publish.
Follow the steps in Configure routing services to configure routing services using your network dataset.

Once it runs successfully, you can use ArcGIS Server Manager to delete the folder containing routing services published previously.

Troubleshoot issues after upgrading

If you experienced any issues with the upgrade, carefully review the following information and solutions to common issues.

Note:

Keep in mind that issues you encounter after upgrading do not necessarily indicate that the upgrade failed.

The portal does not display correctly or prevents signing in

Clear your browser's cache (including cookies). These errors are typically due to leftover information from the previous version of the website being cached in the browser. If you still can't sign in, make sure you are using the initial administrator account or an account that has administrative privileges to your portal. If the cards on the Organization Overview tab are not loading, import your portal license file (.json). You can import the license file through the Portal Administrator Directory using the URL https://portal.example.com:7443/arcgis/portaladmin/license/importLicense. Ensure that this is the correct license file for your portal. When importing a new license file, any user types or app licenses in your organization are overwritten by the new license file.

Items, groups, and users in a portal are not visible

After installing the software and specifying the initial administrator account, a reindex of your portal is initialized. Initially, you may not see all of your items, groups, and users because the reindex is not complete. Depending on the number of users and volume of content in your organization, it will take some time for the reindex to complete. For example, a small organization (hundreds of users and content items) running Portal for ArcGIS on a machine with 8 cores may take 15 minutes to reindex. Conversely, a large organization (tens of thousands of users and content items) running Portal for ArcGIS on a machine with 8 cores may take over 3 hours to reindex.

Check the status of the reindex

You can check the status of the reindex by following the steps below. When the store and index counts are equal, the reindex and upgrade are complete.

Open the Portal Administrator API and sign in with the initial administrator account.

The URL is formatted as https://portal.example.com:7443/arcgis/portaladmin.
Click System > Indexer > Index Status.
Refresh the page to obtain the latest status.

ArcGIS Living Atlas content is no longer accessible

If an ArcGIS Living Atlas layer is not accessible in your organization's content after you upgrade, it's possible that the item is retired at this release. Check ArcGIS Living Atlas content life cycles and updates for an updated list of retired items.

If subscriber or premium content items cannot be opened post-upgrade, verify that the ArcGIS Online account you used when you configured the portal to access this content is still valid. If it is not, you must complete additional steps to update this account and the ArcGIS Living Atlas content.

Licenses assigned exceed the number of licenses available

The The number of licenses assigned exceed the number of licenses available. Members assigned these licenses may not be able to access the portal. Go to the Licenses tab for more details. notice displays for administrators when they sign in to the portal and the portal's licensing is in overdraft. The number of users assigned a user type or add on license exceeds the number of licenses available.

The administrator can browse to the Licenses tab to view the licenses in overdraft. Licenses in overdraft have a greater number assigned than the number available. Depending on your organization's needs, you can reassign licenses or obtain a new portal license file with the correct allocation of licenses.

Members have licenses assigned twice

The Some members have licenses assigned twice. These members have access to the same license through their user type and an add-on license. notice displays for administrators when one or more add-on licenses assigned to members are included with their user types after upgrading the portal. The administrator can unassign duplicate add-on licenses from all applicable members.

Error creating an initial administrator account

If you receive this error when creating the initial administrator account, information in the portal logs can help you resolve the issue. Often, this error may occur if network connectivity was temporarily lost when creating the account. To access the logs, browse to the logs directory and open the most recent log file (for example, <Portal for ArcGIS installation directory>/arcgisportal/logs/<machine name>/portal/portal-20141201.095803-8596-0.0.log). If necessary, you can share this information with Esri Support.

If you are reverting to your previous deployment, copy all log files before reverting to help troubleshoot your support incident. To access the logs, browse to the logs directory (for example, <Portal for ArcGIS installation directory>/arcgisportal/logs/).

If you receive this error when creating the initial administrator account, information in the portal logs can help you resolve the issue. Often, this error may occur if network connectivity was temporarily lost when creating the account. To access the logs, browse to the logs directory and open the most recent log file (for example, C:\arcgisportal\logs\<machine name>\portal\portal-20141201.095803-8596-0.0.log). If necessary, you can share this information with Esri Support.

Upgrade Portal for ArcGIS

Important:

Caution:

Prepare to upgrade

Back up your content

Tip:

Upgrade concepts

Note:

Licensing

Note:

Content

Apps

Highly available and replicated environments

Upgrade using the setup program

Tip:

Note:

Note:

Note:

Note:

Note:

Upgrade silently

Post-upgrade tasks

Update WebGISDR properties files created prior to upgrading

Manually update utility services

Configure routing services

Troubleshoot issues after upgrading

Note:

The portal does not display correctly or prevents signing in

Items, groups, and users in a portal are not visible

Check the status of the reindex

ArcGIS Living Atlas content is no longer accessible

Licenses assigned exceed the number of licenses available

Members have licenses assigned twice

Error creating an initial administrator account