Skip To Content
ArcGIS Developer
Dashboard

Upgrade

Description

This is the first operation that must be invoked during a Portal for ArcGIS upgrade. Once the new software version has been installed and the setup has completed, this operation will be available. A successful run of this operation will complete the portal upgrade.

You will be required to input a portal license file unless you are upgrading to a version within the same release series, such as upgrading from 10.7 to 10.7.1. If you are upgrading within the same release series a license file is not required and will not be applied.

Caution:

If errors are returned with the upgrade operation, you must address the errors before you may continue. For example, if you encounter an error about an invalid license, you will need to re-authorize the software using a valid license and you may then retry this operation.

Note:

This operation is available only while a portal is being upgraded. It will not be available once a successful upgrade has finished.

In scenarios where you choose to not backup your site (isBackupRequired = false), you must set isRollbackRequired to false.

Request parameters

ParameterDetails
isBackupRequired

Specifies whether the upgrade will backup the content, db, and index folders. The default value is true.

Note:

It is recommended that this parameter is set to true. Creating a backup of directories is strongly recommended. In cases where backupDirectories is set to false, ensure other means are in place to create a backup of the content, db, and index folders.

Values: true | false

isRollbackRequired

Determines whether to revert to the pre-existing content, db and index where an upgrade failure occurs. The default value is true.

Note:

It is recommended that this parameter is set to true. When this parameter is set to true, isBackupRequired must be also be set to true in order to revert to the backup content, db, and index folders.

Values: true | false

file

The license file that contains your portal's user type and app license information.

Note:
The license file parameter is not required when upgrading to a version within the same release series. For example, if you are upgrading from 10.7 to 10.7.1 a license file will not be applied.

async

Introduced at 11.0. Determines whether to submit the upgrade request asynchronously or synchronously. If submitted synchronously, the response is returned once the upgrade process completes successfully or if the request fails. If submitted asynchronously, the upgrade operation can be polled by making a request to the root resource. The default value is false (synchronously).

Values: true | false

enableDebug

Introduced at 11.0. Sets the log level for the upgrade process. If true, the log level is set to DEBUG during the upgrade, which can aid in troubleshooting issues related to the upgrade process. If false, the log level is set to VERBOSE during the upgrade process. The default value is false.

Values: true | false

f

The response format. The default response format is html.

Values: html | json | pjson

JSON Response examples

The sections below outline the various responses returned when performing an upgrade, depending on whether the job was run synchronously or asynchronously.

Synchronous upgrades

The following example demonstrates the response returned when the upgrade completes successfully:

{
  "status": "success",
  "recheckAfterSecs": 20
}

When the upgrade completes successfully, but there are action items that the administrator must perform, a success response with a warnings property will be returned:

{
  "status": "success with warnings",
  "recheckAfterSecs": 20,
  "warnings": [
    "Failed to update the web server certificate configuration with the certificate in configStore."
  ],
}

Asynchronous upgrades

The following response is returned immediately upon the upgrade operation being submitted:

{
  "upgradeFromVersion": "10.7.1",
  "upgradeToVersion": "11.0.0",
  "status": "in progress",
  "warnings": [],
  "stages": [
    {
      "lastUpdated": 1646337782721,
      "name": "Back up content, database, and index directories",
      "startTime": 1646337782659,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Upgrade portal content",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Upgrade database",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Migrate configuration settings",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Update configuration settings",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Configure index service",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Reindex",
      "startTime": 0,
      "state": "not started"
    }
  ],
  "messages": []
}

While the upgrade is in process, the root resource can be polled to return the upgrade's current status. The sample response below demonstrates this updated response:

{
  "upgradeFromVersion": "10.7.1",
  "upgradeToVersion": "11.0.0",
  "status": "in progress",
  "warnings": [],
  "stages": [
    {
      "lastUpdated": 1646337782721,
      "name": "Back up content, database, and index directories",
      "startTime": 1646337782659,
      "state": "completed"
    },
    {
      "lastUpdated": 0,
      "name": "Upgrade portal content",
      "startTime": 0,
      "state": "in progress"
    },
    {
      "lastUpdated": 0,
      "name": "Upgrade database",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Migrate configuration settings",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Update configuration settings",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Configure index service",
      "startTime": 0,
      "state": "not started"
    },
    {
      "lastUpdated": 0,
      "name": "Reindex",
      "startTime": 0,
      "state": "not started"
    }
  ],
  "messages": []
}

Once the upgrade has completed successfully, the root resource will return the following success response:

{
  "upgradeFromVersion": "10.7.1",
  "upgradeToVersion": "11.0.0",
  "status": "success",
  "warnings": [],
  "stages": [
    {
      "lastUpdated": 1646339105630,
      "name": "Back up content, database, and index directories",
      "startTime": 1646339105563,
      "state": "completed"
    },
    {
      "lastUpdated": 1646339321902,
      "name": "Upgrade portal content",
      "startTime": 1646339106985,
      "state": "completed"
    },
    {
      "lastUpdated": 1646339462088,
      "name": "Upgrade database",
      "startTime": 1646339106985,
      "state": "completed"
    },
    {
      "lastUpdated": 1646339478570,
      "name": "Migrate configuration settings",
      "startTime": 1646339462089,
      "state": "completed"
    },
    {
      "lastUpdated": 1646339478570,
      "name": "Update configuration settings",
      "startTime": 1646339462089,
      "state": "completed"
    },
    {
      "lastUpdated": 1646339531393,
      "name": "Configure index service",
      "startTime": 1646339478570,
      "state": "completed"
    },
    {
      "lastUpdated": 1646339689202,
      "name": "Reindex",
      "startTime": 1646339615524,
      "state": "completed"
    }
  ],
  "messages": [],
  "recheckAfterSeconds": 20
}

If the upgrade is complete, but there are action items that must be performed, the root resource will return a success response with a warnings property, which will contain information on those action items for the administrator:

{
  "upgradeFromVersion": "10.7.1",
  "upgradeToVersion": "11.0.0",
  "status": "success with warnings",
  "warnings": [
    "Failed to update the web server certificate configuration with the certificate in configStore."
  ],
  "stages": [
    {
      "lastUpdated": 1646353243839,
      "name": "Back up content, database, and index directories",
      "startTime": 1646352892223,
      "state": "completed"
    },
    {
      "lastUpdated": 1646353374026,
      "name": "Upgrade portal content",
      "startTime": 1646353246494,
      "state": "completed"
    },
    {
      "lastUpdated": 1646353512931,
      "name": "Upgrade database",
      "startTime": 1646353246494,
      "state": "completed"
    },
    {
      "lastUpdated": 1646353529552,
      "name": "Migrate configuration settings",
      "startTime": 1646353512931,
      "state": "completed"
    },
    {
      "lastUpdated": 1646353529552,
      "name": "Update configuration settings",
      "startTime": 1646353512931,
      "state": "completed"
    },
    {
      "lastUpdated": 1646353580805,
      "name": "Configure index service",
      "startTime": 1646353529552,
      "state": "completed"
    },
    {
      "lastUpdated": 1646353712761,
      "name": "Reindex",
      "startTime": 1646353650598,
      "state": "completed"
    }
  ],
  "messages": [],
  "recheckAfterSeconds": 20
}