Backup Profiles REST API

Use this REST API to manage backup configuration profiles.

You can perform the following tasks to manage backup configuration profiles:
  • Get a list of existing backup configuration profiles.
  • Get information about a specific backup configuration profile, including an estimate of the storage size required to contain the backup data, and an estimate of the time to complete the backup operation.
  • Create a new backup profile for either a system level backup or a component level backup (but not both).
  • Modify an existing backup profile. Based on what items you add to or remove from the backup profile, the estimated storage size needed and time to complete the operation is recalculated.
  • Delete an existing backup profile.
  • Display a history of previous backup operations for the specified profile, including the start time, duration, number of bytes transferred, and whether the backup operation was successful.

When you retrieve information about a specified backup profile, the amount of storage required to store your selected backup data on the remote backup system is estimated, as well as the amount of time it should take to complete the backup operation. When you add or remove components, these estimations are adjusted accordingly.

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:
  • Workload resources administration with Manage workload resources (Full permission)
  • Cloud group administration with Manage cloud resources (Full permission)
  • Hardware administration with Manage hardware resources (Full permission)
  • Security administration role with permission to Manage security (Full permission)

Get a list of existing backup profiles

Table 1. Get a list of existing backup profiles
REST API information Value Description
URI /admin/resources/backup_profiles  
Method GET  
Returns 200 The list of backup profiles was returned successfully.
404 Backup profiles were not found.
500 Platform System Manager encountered an internal error while processing the request.

Response body

This REST API call returns a list of existing backup profiles. The output for each backup profile is displayed sequentially, each similar to the example shown below for the specific backup profile request.

The calculation of the state of each backup profile takes some time to complete before the list of profiles and their details is displayed. You can get a faster response if you use the ?nostate option when running this REST API:
/admin/resources/backup_profiles?nostate

Using this option displays all of the details for each backup profile except for the State attribute.

Get information about a specific backup profile

Table 2. Get information about a specific backup profile
REST API information Value Description
URI /admin/resources/backup_profiles/{id}  
Method GET  
Returns 200 The information about the specified backup profile was returned successfully.
404 The specified backup profile was not found.
500 Platform System Manager encountered an internal error while processing the request.
This REST API call specifies a particular backup profile, identified by {id}, similar to the following example URI:
/admin/resources/backup_profiles/591781e0-95c1-4572-9466-778546ebe2b5

Response body

This REST API call returns details about the specified backup profile, similar to the following example:

[
{
   "created_time_raw": 1393612498343,
   "run_wed": "T",
   "state": "ENABLED",
   "updated_time": "Mon 03 Mar 2014 17:57:00.771 UTC",
   "version": "2.0.0.0",
   "sizeestimate": {
      "total": 16754,
      "iwd_size": 0,
      "system": 0,
      "backup.component.addons": 2366,
      "comp_size": 16754,
      "backup.component.scripts": 14388,
      "fsm_size": 0,
      "dbs_size": 0
   },
   "id": "/admin/resources/backup_profiles/2de0aa31-6a2a-4724-b474-97c2eeafc03c",
   "system_backup": "F",
   "start_schedule_time": 1393869600759,
   "run_sat": "T",
   "run_sun": "T",
   "name": "philProfile",
   "run_tue": "T",
 "notifications": [ 
    {
      "auth_mode": "internal",
      "bidi_national_calendar": None,
      "bidi_text_direction": None,
      "created_time": "Jan 15, 2015 11:25:52 AM",
      "current_status": None,
      "email": "btong@us.ibm.com",
      "groups": (nested object),
      "id": "01f70f39-380a-4b83-af21-cac34e2feb86",
      "name": "Default Admin",
      "password": (write-only),
      "roles": (nested object),
      "shellaccounts": (nested object),
      "url": "/admin/resources/users/01f70f39-380a-4b83-af21-cac34e2feb86",
      "user_id": "admin"
    }],   "objecttypes": {
      "dbfixpack": false,
      "usergroup": false,
      "virtualappliance": false,
      "envprofile": false,
      "dbpattern": false,
      "cloudgroup": false,
      "patterncomponent": false,
      "vapppattern": false,
      "volumegroup": false,
      "vsyspattern": false,
      "systemplugin": false,
      "virtualimage": false,
      "addon": true,
      "vapptemplate": false,
      "vsystemplate": false,
      "scriptpackage": true,
      "ipgroup": false,
      "dbimages": false,
      "user": false,
      "efix": false,
      "ptype": false
   },
   "run_thu": "T",
   "freespaceatlocation": 9793148,
   "end_schedule_time": 1395896400000,
   "auto_run": "T",
   "updated_time_raw": 1393869420771,
   "timeestimate": 2177,
   "backup_locations": "/admin/resources/backup_locations/d70f22ce-3d2e-4541-8fcb-27ea6bd54a4d",
   "run_fri": "T",
   "run_mon": "T",
   "profile_history": [
      "/admin/resources/profile_history/d27fa17b-e4e8-47ce-a2e4-ddae9c1da332",
      "/admin/resources/profile_history/eaf82096-8b62-46f1-93f7-fbfbcbe0d668",
      "/admin/resources/profile_history/453e5c05-13cb-4d34-8f3c-1e6ee2550051",
      "/admin/resources/profile_history/3dac2a28-344d-4405-a149-178aafc51e0b",
      "/admin/resources/profile_history/9469b087-e431-44c7-b501-63ea019c9bb0",
      "/admin/resources/profile_history/bef8998c-84ca-4f68-bf32-8bebbd95e323",
      "/admin/resources/profile_history/40bbda3f-0931-4d28-9f4c-6180c049a94e",
      "/admin/resources/profile_history/36a11d4e-27ca-4c61-9e9d-b094c7f76052",
      "/admin/resources/profile_history/fdf38e35-b069-4b76-a9e3-01553de6af74",
      "/admin/resources/profile_history/bd713a7a-8b93-4834-8dc3-00f84c25c1f3",
      "/admin/resources/profile_history/bffe86bb-71e4-46e2-8545-32add5cc1c52"
   ],
   "created_time": "Fri 28 Feb 2014 18:34:58.343 UTC"
}]
Attributes list
auto_run
A boolean value indicating whether or not the backup is run automatically per the defined schedule. Valid values are T (true) or F (false).
backup_locations
The ID of the backup location configuration associated with this backup profile, including the URI, for example:
/admin/resources/backup_locations/fc856906-85ea-48db-97b3-853fc5510757
created_time
A timestamp indicating the date and time when the backup profile was created. The value is a date and time expressed in Coordinated Universal Time (UTC) format (example: Fri 03 Jan 2014 15:59:20.613 UTC).
created_time_raw
A machine-readable time stamp indicating when the backup profile was created. The value is a long integer (example: 1388764760613).
detailstatus
When the state of the backup profile is RUNNING, this attribute includes details about the steps in the backup process as it progresses, similar to the following example for a system level backup:
"detailstatus": {
      "System Management Files": "Thu Mar 06 21:39:09 UTC 2014: The backup of the subsystem started. The percentage completed is 0.",
      "Workload Configurations": "backup.component.status.start",
      "Transfer Workload Archives": "backup.component.status.pending",
      "Transfer System Management Archives": "backup.component.status.pending",
      "Overall progress": "Started for 1 hours 12 minutes",
      "System Management Database": "Finished (0 hours, 3 minutes)",
      "Trusted Platform Module": "Finished (2 seconds)",
      "Storwize V7000 Configuration": "Finished (0 hours, 1 minutes)",
      "created_time": 1394141960765,
      "overall_duration": "4299164",
      "percent_complete": "0",
      "start_time": "1394137661561",
      "updated_time": 1394141960797
   }

The detail status for a component level backup includes backup progress information about the component types that are enabled for backup.

When the state of the backup profile is MISCONFIGURED, this attribute includes details about why the profile is not configured correctly. The following messages are examples of the types of problems that might be displayed:
"detailstatus": "CTGRI0001E The application could not establish a connection to host ."

"detailstatus": "This profile is configured for component level backup, but no component types are selected and enabled to backup."

"detailstatus": "Currently assigned backup location 'Backup_X' does not have encryption enabled. Encryption is required for system backups and for component backups that include users or user groups."
end_schedule_time
A machine-readable time stamp indicating when the backup is no longer run per the defined schedule. The value is a long integer (example: 1392789600000).
freespaceatlocation
The amount of available free space, in MB, at the backup location associated with this backup profile. The value is an integer (example: 9133871). This attribute is included only when you retrieve the details for a specific backup profile.
id
The ID of this backup profile, including the URI, for example:
/admin/resources/backup_profiles/591781e0-95c1-4572-9466-778546ebe2b5
isas_rn
An integer value that indicates the relative order of the backup profile in the table (for example, the 4th backup profile listed in the table has a value of 4 in this attribute). This attribute is only included when you retrieve the list of all available backup profiles.
jobduration
The amount of time, in minutes, that the backup operation has been running.
name
The unique name assigned to this backup profile (example: Nightly Critical Backup).
notifications
The list of users that are configured to be notified by email when backup operations are performed using this backup profile. Users must already be defined in the users list for the console.
objecttypes
The collection of component type attributes that specify which component types are included in the backup. Each component type attribute is a boolean value, with valid values of true or false.
The following list of component types can be specified:
addon
Indicates whether or not add-ons are included in the backup.
cloudgroup
Indicates whether or not cloud groups are included in the backup.
dbfixpack
Indicates whether or not database fix packs are included in the backup.
dbimages
Indicates whether or not database images are included in the backup.
dbpattern
Indicates whether or not database patterns are included in the backup.
efix
Indicates whether or not emergency fixes are included in the backup.
envprofile
Indicates whether or not environment profiles are included in the backup.
ipgroup
Indicates whether or not IP groups are included in the backup.
patterncomponent
Indicates whether or not pattern components are included in the backup.
ptype
Indicates whether or not pattern types are included in the backup.
scriptpackage
Indicates whether or not script packages are included in the backup.
systemplugin
Indicates whether or not system plug-ins are included in the backup.
user
Indicates whether or not users are included in the backup.
usergroup
Indicates whether or not user groups are included in the backup.
vapppattern
Indicates whether or not virtual application patterns are included in the backup.
vapptemplate
Indicates whether or not virtual application templates are included in the backup.
virtualappliance
Indicates whether or not virtual appliances are included in the backup.
virtualimage
Indicates whether or not virtual images are included in the backup.
volumegroup
Indicates whether or not volume groups are included in the backup.
vsyspattern
Indicates whether or not virtual system patterns are included in the backup.
vsystemplate
Indicates whether or not virtual system templates are included in the backup.
profile_history
A list of profile history records showing when this backup profile was run in the past.
run_sun
A boolean value indicating whether or not the backup is run on Sundays each week. Valid values are T (true) or F (false).
run_mon
A boolean value indicating whether or not the backup is run on Mondays each week. Valid values are T (true) or F (false).
run_tue
A boolean value indicating whether or not the backup is run on Tuesdays each week. Valid values are T (true) or F (false).
run_wed
A boolean value indicating whether or not the backup is run on Wednesdays each week. Valid values are T (true) or F (false).
run_thu
A boolean value indicating whether or not the backup is run on Thursdays each week. Valid values are T (true) or F (false).
run_fri
A boolean value indicating whether or not the backup is run on Fridays each week. Valid values are T (true) or F (false).
run_sat
A boolean value indicating whether or not the backup is run on Saturdays each week. Valid values are T (true) or F (false).
sizeestimate
This attribute includes a list of estimated storage sizes for various parts of the backup. This attribute is included only when you retrieve the details for a specific backup profile. The list includes the following values:
  • total: The total estimated size of the backup (MB), whether it is a system level backup or a component level backup.
  • system: The total estimated size of the data (MB) for a system level backup. This is the sum of the following individual values:
    • iwd_size: The total size of the workload related data (MB).
    • dbs_size: The total size of the database data (MB).
    • fsm_size: The total size of the FSM data (MB) on 8278 system models. For 8283 system models, this value is displayed as 0.
    • comp_size: The total size of the component type data for all components that are enabled for backup (MB). For a system level backup, this value will always be 0.

    For a component level backup, the value of system is displayed as 0.

For a component level backup, estimated sizes for each of the enabled component types is displayed. For example:
  • backup.component.ipgroup: The total estimated size of components in the IP Group type (MB)
  • backup.component.efix: The total estimated size of components in the Emergency fixes type (MB)
  • backup.component.addons: The total estimated size of components in the Add-ons type (MB)
  • backup.component.scripts: The total estimated size of components in the Scripts type (MB)
The following example shows the sizeestimate attribute for a system level backup:
"sizeestimate": {
   "total": 11082,
   "iwd_size": 8841,
   "system": 11082,
   "comp_size": 0,
   "fsm_size": 0,
   "dbs_size": 2241
   },

In this example, the value for system is the sum of the values for iwd_size, comp_size, fsm_size, and dbs_size. The value for total is equivalent to the value for system.

The following example shows the sizeestimate attribute for a component level backup:
"sizeestimate": {
      "total": 16754,
      "iwd_size": 0,
      "system": 0,
      "backup.component.addons": 2366,
      "comp_size": 16754,
      "backup.component.scripts": 14388,
      "fsm_size": 0,
      "dbs_size": 0
   },

In this example, the value for system is 0, because this is a component level backup. Similarly, the values for iwd_size, fsm_size, and dbs_size are also 0. The comp_size value, however, is the sum of the sizes for the enabled component types. In this case, add-ons and script packages are enabled for backup, and the sizes for each are displayed, with the total shown in both comp_size and total.

start_schedule_time
A machine-readable time stamp indicating when the backup is started per the defined schedule. The value is a long integer (example: 1391832028939).
state
Indicates the state of the backup profile. The following values are valid:
ENABLED
The backup profile is enabled for backup per the defined schedule or started manually on demand.
DISABLED
The backup profile is disabled. Scheduled backups are not performed. You can still start a backup manually on demand.
MISCONFIGURED
The backup profile is not configured correctly. This state might indicate that either the backup location is not defined for this profile, or if this is a component level backup, no component types have been selected to include in the backup.
RUNNING
The backup profile is currently running and a backup operation is in process.
system_backup
A boolean value indicating whether or not the backup is a system level backup or a component level backup. Valid values are T (system level backup) or F (component level backup).
timeestimate
The total estimated time to perform the backup operation, in minutes. This attribute is included only when you retrieve the details for a specific backup profile.
updated_time
A timestamp indicating the date and time when the backup profile was last updated. The value is a date and time expressed in Coordinated Universal Time (UTC) format (example: Mon 10 Feb 2014 22:03:19.633 UTC).
updated_time_raw
A machine-readable time stamp indicating when the backup profile was last updated. The value is a long integer (example: 1392069799633).
version
The version of IBM® Cloud Pak System System that supports this backup profile (example: 2.0.0.0)

Create a new backup profile

Table 3. Create a new backup profile
REST API information Value Description
URI /admin/resources/backup_profiles  
Method POST  
Returns 200 The backup profile was created successfully.
404 The backup profile was not created successfully.
500 Platform System Manager encountered an internal error while processing the request.

Request body

This REST API call does not require any input request body, and can create a new backup profile and assign it an ID, without any further attribute definition. However, if you do provide an optional request body, the format must look similar to the following example.

{
   "name": "tiffanyProfile",
   "backup_locations": "/admin/resources/backup_locations/fc856906-85ea-48db-97b3-853fc5510757",
   "auto_run": "T",
   "run_sun": "F",
   "run_mon": "T",
   "run_tue": "F",
   "run_wed": "T",
   "run_thu": "F",
   "run_fri": "T",
   "run_sat": "F",
   "start_schedule_time": 1391832028939,
   "end_schedule_time": 1392789600000,
   "system_backup": "F",
   "objecttypes": {
      "dbfixpack": false,
      "usergroup": false,
      "virtualappliance": false,
      "envprofile": false,
      "dbpattern": false,
      "cloudgroup": false,
      "patterncomponent": true,
      "vapppattern": false,
      "volumegroup": false,
      "vsyspattern": false,
      "systemplugin": false,
      "virtualimage": false,
      "addon": false,
      "vapptemplate": false,
      "vsystemplate": false,
      "scriptpackage": true,
      "ipgroup": false,
      "dbimages": false,
      "user": false,
      "efix": false,
      "ptype": false
   },
}

In this example of a component level backup, the value for system_backup is F (false), and several component type attributes are set to true.

The following example shows another request for a system level backup. In this case, the value for system_backup is T (true), and the values for all of the component type attributes are false. Backup profiles can be configured for either a system level backup or a component level backup, but not both.
{
      "name": "rohits",
      "backup_locations": "/admin/resources/backup_locations/7cc8b3dd-e5af-4640-a068-8928f173f41a",
 
      "auto_run": "F",
      "run_sun": "T",
      "run_mon": "T",
      "run_tue": "T",
      "run_wed": "T",
      "run_thu": "T",
      "run_fri": "T",
      "run_sat": "T",
      "start_schedule_time": null,
      "end_schedule_time": null,
      "system_backup": "T",
      "objecttypes": {
         "dbfixpack": false,
         "usergroup": false,
         "virtualappliance": false,
         "envprofile": false,
         "dbpattern": false,
         "cloudgroup": false,
         "patterncomponent": false,
         "vapppattern": false,
         "volumegroup": false,
         "vsyspattern": false,
         "systemplugin": false,
         "virtualimage": false,
         "addon": false,
         "vapptemplate": false,
         "vsystemplate": false,
         "scriptpackage": false,
         "ipgroup": false,
         "dbimages": false,
         "user": false,
         "efix": false,
         "ptype": false
      },
  },

If you specify a name for the backup profile, it is checked to verify that another profile of the same name does not already exist. If you do not specify a name, the current timestamp is used to create a unique name for the profile.

If you do not specify a value for start_schedule_time or end_schedule_time, they are set to null. Otherwise these values are checked to verify that they are not negative number values, and that they are formatted as a long integer timestamp.

Response body

This REST API call returns a response body similar to that returned from a GET operation, showing the details for the newly created backup configuration profile.

Modify an existing backup profile

Table 4. Modify an existing backup profile
REST API information Value Description
URI /admin/resources/backup_profiles/{id}  
Method PUT  
Returns 200 The backup profile was updated successfully.
400 The backup profile was not updated successfully.
500 Platform System Manager encountered an internal error while processing the request.

Request body

This REST API call takes JSON input and updates the specified backup profile with the provided values. The request format must include the identifier for the specified backup location configuration, and must look similar to the following example.
Note: Regarding changing the type of backup (by changing the value of the system_backup attribute:
  • If you change from a component level backup to a system level backup, ensure that all of the object type attributes under objecttype are set to false.
  • If you change from a system level backup to a component level backup, ensure that one or more of the object type attributes under objecttype are set to true.
{
   "name": "tiffanyProfile",
   "id": "591781e0-95c1-4572-9466-778546ebe2b5",
   "backup_locations": "/admin/resources/backup_locations/fc856906-85ea-48db-97b3-853fc5510757",
   "auto_run": "T",
   "run_sun": "F",
   "run_mon": "T",
   "run_tue": "F",
   "run_wed": "T",
   "run_thu": "F",
   "run_fri": "T",
   "run_sat": "F",
   "start_schedule_time": 1391832028939,
   "end_schedule_time": 1392789600000,
   "system_backup": "F",
   "objecttypes": {
      "dbfixpack": false,
      "usergroup": false,
      "virtualappliance": false,
      "envprofile": false,
      "dbpattern": false,
      "cloudgroup": false,
      "patterncomponent": true,
      "vapppattern": false,
      "volumegroup": false,
      "vsyspattern": false,
      "systemplugin": false,
      "virtualimage": false,
      "addon": false,
      "vapptemplate": false,
      "vsystemplate": false,
      "scriptpackage": true,
      "ipgroup": false,
      "dbimages": false,
      "user": false,
      "efix": false,
      "ptype": false
   },
}

If you specify a name for the backup profile, it is checked to verify that another profile of the same name does not already exist.

If you do not specify a value for start_schedule_time or end_schedule_time, they are set to null. Otherwise these values are checked to verify that they are not negative number values, and that they are formatted as a long integer timestamp. Ensure that the value specified for end_schedule_time occurs later than the value for start_schedule_time.

Response body

This REST API call returns a response body similar to that returned from a GET operation, showing the details for the modified backup configuration profile.

Deleting an existing backup profile

Table 5. Deleting an existing backup profile
REST API information Value Description
URI /admin/resources/backup_profiles/{id}  
Method DELETE  
Returns 202 Accepted.
404 The backup profile was not found.
500 Platform System Manager encountered an internal error while processing the request.

This REST API call deletes the backup profile specified by {id}, along with any backup history information. This no request body or response body.

Retrieve backup history

Table 6. Retrieve backup history
REST API information Value Description
URI /admin/resources/backup_profiles/{id}?resolvechildren=1  
Method GET  
Returns 200 The backup history was retrieved successfully.
400 The backup history was not retrieved successfully.
500 Platform System Manager encountered an internal error while processing the request.

This REST API call returns the available backup history information for the specified backup profile in JSON format.

Response body

This REST API call returns details for backup history in the profile_history attribute for the specified backup configuration profile, similar to the following example:

 "profile_history": [
      {
         "backup_type": "Component",
         "id": "/admin/resources/profile_history/b34813ce-b244-429b-8f8d-23b342caafb8",
         "created_time_raw": 1392329482819,
         "updated_time_raw": 1392329482819,
         "status": "F",
         "backupstarttime": 1392329468360,
         "backup_profiles": "/admin/resources/backup_profiles/591781e0-95c1-4572-9466-778546ebe2b5",
         "created_time": "Thu 13 Feb 2014 22:11:22.819 UTC",
         "size_mb": 47788,
         "updated_time": "Thu 13 Feb 2014 22:11:22.819 UTC",
         "version": "2.0.0.0",
         "duration_minutes": 1
      },
      {
         "backup_type": "Component",
         "id": "/admin/resources/profile_history/cf2c6a73-0643-4227-91ef-412616c5fad1",
         "created_time_raw": 1392066469320,
         "updated_time_raw": 1392066469320,
         "status": "S",
         "backupstarttime": 1392066367869,
         "backup_profiles": "/admin/resources/backup_profiles/591781e0-95c1-4572-9466-778546ebe2b5",
         "created_time": "Mon 10 Feb 2014 21:07:49.320 UTC",
         "size_mb": 36988,
         "updated_time": "Mon 10 Feb 2014 21:07:49.320 UTC",
         "version": "2.0.0.0",
         "duration_minutes": 9
      },
Attributes list
backupstarttime
A machine-readable time stamp indicating when the backup was started for this profile history entry. The value is a long integer (example: 1392069799633).
backup_profiles
The ID of this backup profile, including the URI, for example:
/admin/resources/backup_profiles/591781e0-95c1-4572-9466-778546ebe2b5
backup_type
The type of backup. Valid values are Component or System.
created_time
A timestamp indicating the date and time when the profile history entry was created. The value is a date and time expressed in Coordinated Universal Time (UTC) format (example: Fri 03 Jan 2014 15:59:20.613 UTC).
created_time_raw
A machine-readable time stamp indicating when this profile history entry was created. The value is a long integer (example: 1388764760613).
duration_minutes
The total elapsed time, in minutes, for the backup operation to complete. This is an integer value.
id
The ID for this profile history, including the URI, for example:
/admin/resources/profile_history/b34813ce-b244-429b-8f8d-23b342caafb8
size_mb
The total storage size of the backup, in MB.
status
Indicates whether the backup completed successfully or failed. Valid values include F (failed) or S (completed successfully).
updated_time
A timestamp indicating the date and time when the profile history entry was updated. The value is a date and time expressed in Coordinated Universal Time (UTC) format (example: Fri 03 Jan 2014 15:59:20.613 UTC).
updated_time_raw
A machine-readable time stamp indicating when this profile history entry was last updated. The value is a long integer (example: 1392069799633).
version
The version of Cloud Pak System that supports this backup profile (example: 2.0.0.0)

If the backup history cannot be obtained, a message is displayed, similar to the following example:

{
   "id": "CWZIP2902E",
   "messages": {
      "message": "Resource not found",
      "lang": "en_US"
   },
   "type": "Error",
   "time": "Thu 20 Feb 2014 01:17:26.748 UTC",
   "suggestedAction": "Not Applicable",
   "uri": "/resources/backup_profiles/591781e0-95c1-4572-9466-778546ebe2b1"
}