Restore backup object REST API

Use this REST API to perform restore operations for a specified backed up component.

You can perform the following tasks to manage restore operations on your backed up data:

For a specified enabled component type and backup location, get a list of components that you can restore from the backup location.
For a list of specified component artifacts to restore, obtain estimates of storage and time required to perform the component level restore operation.
Import a list of artifacts from a specified backup.

You can use optional parameters to modify the response from the REST API call. For more information, see the Related information section.

To use this REST API, you must have all of the following user roles and permissions:

Get a list of components that you can restore

Table 1. Get a list of components that you can restore
REST API information	Value	Description
URI	/admin/resources/restoreBackupObject?objecttype={obj}&backup_location={backup_location_id}
Method	GET
Returns	200	The list of components that you can restore for the specified object type and the specified backup location was returned successfully.
	404	The list of components was not returned successfully.
	500	Platform System Manager encountered an internal error while processing the request.

For example, to obtain a list of script packages that can be restored from the backup location with ID of fc856906-85ea-48db-97b3-853fc5510757 the URI would be specified as follows:

/admin/resources/restoreBackupObject?
objecttype=scriptpackage&
backup_location=fc856906-85ea-48db-97b3-853fc5510757

Note that the object type must have been enabled for backup in the backup configuration profile.

Response body

This REST API call returns a list of components for the specified object type that can be restored from the specified backup location. The following example shows the output format for a list of script packages that can be restored

{
   "scriptpackage": [
      {
         "backuptime": 1392329996489,
         "id": 921,
         "encrypted": "F",
         "updated": 1392063914854,
         "description": "AMC Cleanup Script Package : Script Package that calls out to AMC and removes any artifacts associated with this instance.",
         "objecttype": "scriptpackage",
         "name": "AMC Cleanup Script Package",
         "path": "/cygdrive/f/backups/82831000257/backupStorage/scriptpackage/AMC_Cleanup_Script_Package/1392329996489",
         "currentstatus": "RM01027",
         "version": "1.0.0"
      },
      {
         "backuptime": 1392329996489,
         "id": 129,
         "encrypted": "F",
         "updated": 1392324413231,
         "description": "AMC Import Script Package : Script Package that calls out to AMC and invokes an automation plan to import configuration and applications.",
         "objecttype": "scriptpackage",
         "name": "AMC Import Script Package",
         "path": "/cygdrive/f/backups/82831000257/backupStorage/scriptpackage/AMC_Import_Script_Package/1392329996489",
         "currentstatus": "RM01027",
         "version": "1.0.0"
      },
      {
         "backuptime": 1392329996489,
         "id": 130,
         "encrypted": "F",
         "updated": 1392063935307,
         "description": "AMC Integration Script Package : None",
         "objecttype": "scriptpackage",
         "name": "AMC Integration Script Package",
         "path": "/cygdrive/f/backups/82831000257/backupStorage/scriptpackage/AMC_Integration_Script_Package/1392329996489",
         "currentstatus": "RM01027",
         "version": "1.0.0"
      },
  ]
}

This example shows three script packages that can be restored from the specified backup location.

Here is another example, using object type vsyspatterns to obtain a list of virtual system pattern definitions than can be restored from the specified backup location. The URI would be specified as follows:

admin/resources/restoreBackupObject?
objecttype=vsyspattern&
backup_location=fc856906-85ea-48db-97b3-853fc5510757

Note: Be aware that only pattern definitions from the catalog, not their instance deployments, are backed up and restored.

The resulting JSON response body contains the list of virtual system pattern definitions that can be restored, similar to the following example output:

{
   "vsyspattern": [
      {
         "backuptime": 1392059906140,
         "id": null,
         "encrypted": "F",
         "updated": 1382473481533,
         "description": null,
         "objecttype": "vsyspattern",
         "name": "AP_TDS_LDIF",
         "path": "/cygdrive/f/backups/82831000257/backupStorage/vsyspattern/AP_TDS_LDIF/1392059906140",
         "currentstatus": "RM01027",
         "version": null
      },
      {
         "backuptime": 1392059906140,
         "id": null,
         "encrypted": "F",
         "updated": 1381936909732,
         "description": null,
         "objecttype": "vsyspattern",
         "name": "AP_TDS_NoBinaries",
         "path": "/cygdrive/f/backups/82831000257/backupStorage/vsyspattern/AP_TDS_NoBinaries/1392059906140",
         "currentstatus": "RM01027",
         "version": null
      },
      {
         "backuptime": 1392059906140,
         "id": null,
         "encrypted": "F",
         "updated": 1392061827841,
         "description": null,
         "objecttype": "vsyspattern",
         "name": "AnkitTest",
         "path": "/cygdrive/f/backups/82831000257/backupStorage/vsyspattern/AnkitTest/1392059906140",
         "currentstatus": "RM01027",
         "version": null
      },

Obtain size and time estimates to restore a list of specified components

Table 2. Obtain size and time estimates to restore a list of specified components
REST API information	Value	Description
URI	/admin/resources/restoreBackupObject
Method	PUT
Returns	200	The restore estimates were calculated and returned successfully.
	404	The restore estimates were not calculated and returned successfully.
	500	Platform System Manager encountered an internal error while processing the request.

Request body

This REST API call requires a JSON request body, which includes the details of the components to be restored, along with the backup location ID and password for accessing encrypted files. The following example is for estimating the storage needed and time to restore a specified script package:

{
   "scriptpackage": [
      {
         "encrypted": "F",
         "path": "/br_storage_1/november_20_base/82831000257/backupStorage/scriptpackage/AMC_Cleanup_Script_Package/1389647043753",
         "version": "1.0.0",
         "objecttype": "scriptpackage",
         "currentstatus": "RM01027",
         "updated": 1368804196914,
         "name": "AMC Cleanup Script Package",
         "id": 131,
         "description": "AMC Cleanup Script Package : Script Package that calls out to AMC and removes any artifacts associated with this instance.",
         "backuptime": 1389647043753
      }
  ],
"backup_location":"4d386ca0-4f25-4d27-8d08-ff336b225c68",
"keyPassword":"passw0rd"
}

In this example, the restore location (also referred to as the backup location) is specified in the JSON, along with the password that is valid for certificate and private key authentication. The specific details about the script package to be restored is also provided. You can specify more than one component, and you can specify a variety of component types in a single request. For other component types, you must specify the appropriate attributes for that particular component.

The REST API performs the following general tasks:

Verifies the JSON input. If the request is not formatted correctly, an error message is issued and the calculation is not completed successfully.
If all is well, the estimates of size and time to restore are calculated and returned in a JSON response body, similar to the following example.

Response body

{
   restoreTimeEstimate: 111,
   totalBackupSize: 899777,
   totalRestoreSize: 2336
}

Attributes list

backup_location: The ID of the backup location configuration where the backup is located.
keyPassword: The password associated with the certificate and private key information, which is required for restoring encrypted backup data.
<Component specific attributes>: For each specified component type, you can include a list of specific components to restore (for example, under the scriptpackage component type, you can specify a list of specific script package artifacts to restore from the backup.
restoreTimeEstimate: The estimate (in seconds) of the time required to restore the specified component artifacts.
totalBackupSize: The total size of the data (in megabytes) stored at the specified backup (restore) location.
totalRestoreSize: The total size (in megabytes) of the specified component artifacts being restored.

Restore a list of specified components

Table 3. Restore a list of specified components
REST API information	Value	Description
URI	/admin/resources/restoreBackupObject
Method	POST
Returns	200	The restore operation was started successfully.
	404	The restore operations was not started successfully.
	500	Platform System Manager encountered an internal error while processing the request.

Request body

This REST API call requires a JSON request body, similar to the following example for restoring a script package component (this is the same input used in the PUT method).

{
   "scriptpackage": [
      {
         "encrypted": "F",
         "path": "/br_storage_1/november_20_base/82831000257/backupStorage/scriptpackage/AMC_Cleanup_Script_Package/1389647043753",
         "version": "1.0.0",
         "objecttype": "scriptpackage",
         "currentstatus": "RM01027",
         "updated": 1368804196914,
         "name": "AMC Cleanup Script Package",
         "id": 131,
         "description": "AMC Cleanup Script Package : Script Package that calls out to AMC and removes any artifacts associated with this instance.",
         "backuptime": 1389647043753
      }
  ],
"backup_location":"4d386ca0-4f25-4d27-8d08-ff336b225c68",
"keyPassword":"passw0rd"
}

In this example, the backup location is specified in the JSON, along with the password that is valid for certificate and private key authentication. The specific details about the script package to be restored is also provided. You can specify more than one component, and you can specify a variety of component types in a single restore request. For other component types, you must specify the appropriate attributes for that particular component.

The REST API performs the following general tasks:

Verifies the JSON input. If the request is not formatted correctly, error message CWZIP1924E is issued and the restore operation is not started.
If all is well, the restore operation is started.

Attributes list

backup_location: The ID of the backup location configuration where the backup is located.
keyPassword: The password associated with the certificate and private key information, which is required for restoring encrypted backup data.
<Component specific attributes>: For each specified component type, you can include a list of specific components to restore (for example, under the scriptpackage component type, you can specify a list of specific script package artifacts to restore from the backup.