Upgrade

URL:: https://<root>/upgrade
Methods:: GET
Required Capability:: Access allowed only with the default administrator role
Version Introduced:: 10.6

Description

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

You must input a portal license file when performing an upgrade. Starting at ArcGIS Enterprise 11.1, the license file parameter is required when upgrading a portal from one release series to another (for example, upgrading from 10.9 to 11.1) or when upgrading in the same release series (for example, upgrading from 11.0 to 11.1). In earlier releases, the license file parameter was not required when upgrading to a version in the same release series.

If you do not backup your site (isBackupRequired is false), you must set isRollbackRequired to false.

Request parameters

Parameter	Details
`isBackupRequired`	Specifies whether the upgrade will backup the content, database, and index folders. The default value is `true`. Note It is recommended that you set this parameter to `true` to create a backup of directories. When `isBackupRequired` is set to `false`, ensure that other means are in place to create a backup of the content, database, and index folders. Values: `true` \| `false`
`isRollbackRequired`	Specifies whether the content, database, and index folders will revert to the existing content when an upgrade failure occurs. The default value is `true`. Note It is recommended that you set this parameter to `true`. When this parameter is set to `true`, `isBackupRequired` must be also be set to `true` to revert to the backup content, database, and index folders. Values: `true` \| `false`
`async`	Introduced at ArcGIS Enterprise 11.0. This specifies whether the upgrade request will be submitted 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 ArcGIS Enterprise 11.0. This specifies 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`
`isReIndexRequired`	Introduced at ArcGIS Enterprise 11.1. This specifies whether a full reindex is performed during the upgrade. If `true`, a full reindex is performed. If `false`, a full reindex is not performed. The default value is `true`. Values: `true` \| `false`
`file`	The license file that contains the portal's user type and app license information. Note Starting at ArcGIS Enterprise 11.1, this parameter is required when upgrading a portal from a release series to another (for example, upgrading from 10.9 to 11.1) or when upgrading in the same release series (for example, upgrading from 11.0 to 11.1). In earlier releases, this parameter was not required when upgrading to a version in the same release series.
`f`	The response format. The default response format is `html`. Values: `html` \| `json` \| `pjson`

JSON Response examples

The subsections 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:

Use dark colors for code blocksCopy
{
  "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:

Use dark colors for code blocksCopy
{
  "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 when the upgrade operation is submitted:

Use dark colors for code blocksCopy
{
  "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:

Use dark colors for code blocksCopy
{
  "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:

Use dark colors for code blocksCopy
{
  "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 about those action items:

Use dark colors for code blocksCopy
{
  "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
}