- URL:https://<root>/upgrade
- Required Capability:Default administrator role
- Version Introduced:10.6
Description
Note:
This operation is available only while a portal is being upgraded. It is not available once a successful upgrade has finished.
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.
Caution:
If errors are returned during the upgrade operation, you must address the errors before you can continue. For example, if an error regarding an invalid license occurs, you must reauthorize the software using a valid license and retry this operation.
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:
{
"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 when the upgrade operation is 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 about those action items:
{
"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
}