API Explorer
API Explorer
Introduction
What's New
Appliance Management
Application Data Management
Asset Management
Asset Metadata
Authentication and Authorization
Cloud Disaster Recovery
Compliance
Copy Management
Credentials Management
Discovery
File Level Restore
Installation
Inventory Source Management
Kubernetes Data Management
Licenses Management
Location Management
Log Management
Monitoring
Protection Policies
Recovery and Reuse Management
Remote Service
Search Clusters
Secrets Manager
Server Disaster Recovery
Storage Management
Telemetry Setting
Upgrade
User Security Management
Virtual Machine Data Management
Whitelist Management

Create protection policy for VMs

Create a protection policy to backup VMs

Create a protection policy to back up VMs to the PowerProtect DD.

POST /api/v2/protection-policies

Sample request body:

{
    "name": "ProtectionPolicy-VM-Sample",
    "description": "This is a Protection Policy for my virtual machines",
    "assetType": "VMWARE_VIRTUAL_MACHINE",
    "type": "ACTIVE",
    "encrypted": false,
    "enabled": true,
    "priority": 1,
    "dataConsistency": "CRASH_CONSISTENT",
    "passive": false,
    "forceFull": false,
    "details": {
        "vm": {
            "protectionEngine": "VMDIRECT"
        }
    },
    "stages": [
        {
            "id": "ad35057c-4b13-f4d1-62fd-fdd99dbddcb2",
            "type": "PROTECTION",
            "passive": false,
            "attributes": {},
            "target": {
                "storageSystemId": "{{datadomain_storagesystem_id}}"
            },
            "sourceStageId": null,
            "operations": [
                {
                    "backupType": "SYNTHETIC_FULL",
                    "schedule": {
                        "frequency": "MONTHLY",
                        "startTime": "2019-11-05T12:00:00.000Z",
                        "duration": "PT10H",
                        "dayOfMonth": 1
                    }
                }
            ],
            "retention": {
                "interval": 1,
                "unit": "MONTH"
            }
        }
    ],
    "credentials": null,
    "slaId": null
}

This sample protection policy does the following:

  1. Protect VM assets by setting the assetType to VMWARE_VIRTUAL_MACHINE.
  2. Protect the VM at the image level only by setting the dataConsistency to CRASH_CONSISTENT.
  3. Add a stage of type PROTECTION in stages to indicate that you are doing backups, and generate an UUID for the stage id.
  4. In the stage target section, assign the storage system ID that you previously retrieved to storageSystemId and leave the dataTargetId as null. The data target is created on the target storage system and is automatically assigned during configuration.
  5. Inside the stage, create one operation of type SYNTHETIC_FULL in operations to indicate that you are creating full backups, automatically using CBT when possible.
  6. Inside the operation, create one schedule. The sample schedule above directs the following sequence: Back up my asset using a MONTHLY frequency. Do the backup on the first (1) day of the month (dayOfMonth). The schedule is effective starting on 2019-11-05, 12:00 AM UTC, with a backup window of 10 hours for each schedule backup action.
  7. Inside the retention, set the interval and unit (DAY|WEEK|MONTH|YEAR). The sample retention keeps copies for 1 month.
  8. (Optional) Assign the Service Level Agreement ID that you previously retrieved to the slaId.

The response of the API is similar to:

{
  "id": "917e9315-153e-4e5f-bc49-c322d144ef8e",
  "name": "ProtectionPolicy-VM-Sample",
  "description": "This is a Protection Policy for my virtual machines",
  ...
}

From the response, you can obtain the ID of the created protection policy 917e9315-153e-4e5f-bc49-c322d144ef8e. A protection policy configuration activity is started to create the data target for this protection policy.

Assign assets to the protection policy

POST /api/v2/protection-policies/{id}/asset-assignments

In this POST example, the {id} is the protection policy ID that you obtained from the create protection policy call. The POST body looks similar to this example:

["3d43deca-3ff6-4d1a-83ff-5ab5dbb3147c", "235f964b-e2a5-4572-9a34-734b0f4a4ac9"]

The array of IDs is what you retrieved from the list assets API call.

Add replication stage to the protection policy

Get the protection policy by ID

To retrieve the protection policy by ID, use this call:

GET /api/v2/protection-policies/{id}

The response of the API call:


OK (200)
{
	"id": "917e9315-153e-4e5f-bc49-c322d144ef8e",
    "name": "ProtectionPolicy-VM-Sample",
    "description": "This is a Protection Policy for my virtual machines",
    "assetType": "VMWARE_VIRTUAL_MACHINE",
    "type": "ACTIVE",
    "enabled": true,
    "passive": false,
    "forceFull": false,
    "priority": 1,
    "credentials": null,
    "encrypted": false,
    "dataConsistency": "CRASH_CONSISTENT",
    "complianceInterval": null,
    "details": {
        "vm": {
            "protectionEngine": "VMDIRECT",
            "metadataIndexingEnabled": false
        }
    },
    "summary": {
        "numberOfAssets": 2,
        "totalAssetCapacity": 14284999389,
        "numberOfJobFailures": 0,
        "numberOfSlaFailures": 0,
        "numberOfSlaSuccess": 0
    },
    "stages": [
        {
            "id": "ad35057c-4b13-f4d1-62fd-fdd99dbddcb2",
            "type": "PROTECTION",
            "passive": false,
            "retention": {
                "interval": 1,
                "unit": "MONTH",
                "storageSystemRetentionLock": false
            },
            "target": {
                "storageSystemId": "a83f6011-4de0-4cdb-96aa-88e986cb6d8b",
                "dataTargetId": "69717d89-3b0b-495e-a034-da53522ace96",
                "preferredInterface": "10.110.217.159"
            },
            "attributes": {
                "protection": {}
            },
            "operations": [
                {
                    "backupType": "SYNTHETIC_FULL",
                    "schedule": {
                        "frequency": "MONTHLY",
                        "startTime": "2019-11-05T12:00:00Z",
                        "duration": "PT10H",
                        "dayOfMonth": 3
                    }
                }
            ],
            "storageUnit": {
                "name": "ProtectionPolicy-VM-Sample-dhvm-vmqa-152-44587",
                "credentialName": "ProtectionPolicy-VM-Sample-dhvm-vmqa-1-44587"
            }
        }
    ]
}
  • The protection stage ID is used as sourceStageId in subsequent calls.

Add replication stage to the protection policy

To add replication stage to the existing protection policy, use this call:

PUT /api/v2/protection-policies/{id}

The {id} is the protection policy ID that you obtained from the create protection policy call. In the PUT body, add a new stage with stage type “Replication”. It looks similar to this example:

"id": "917e9315-153e-4e5f-bc49-c322d144ef8e",
    "name": "ProtectionPolicy-VM-Sample",
    "description": "This is a Protection Policy for my virtual machines",
    "assetType": "VMWARE_VIRTUAL_MACHINE",
    "type": "ACTIVE",
    "enabled": true,
    "passive": false,
    "forceFull": false,
    "priority": 1,
    "credentials": null,
    "encrypted": false,
    "dataConsistency": "CRASH_CONSISTENT",
    "complianceInterval": null,
    "details": {
        "vm": {
            "protectionEngine": "VMDIRECT",
            "metadataIndexingEnabled": false
        }
    },
    "summary": {
        "numberOfAssets": 2,
        "totalAssetCapacity": 14284999389,
        "numberOfJobFailures": 0,
        "numberOfSlaFailures": 0,
        "numberOfSlaSuccess": 0
    },
    "stages": [
        {
            "id": "ad35057c-4b13-f4d1-62fd-fdd99dbddcb2",
            "type": "PROTECTION",
            "passive": false,
            "retention": {
                "interval": 1,
                "unit": "MONTH",
                "storageSystemRetentionLock": false
            },
            "target": {
                "storageSystemId": "a83f6011-4de0-4cdb-96aa-88e986cb6d8b",
                "dataTargetId": "69717d89-3b0b-495e-a034-da53522ace96",
                "preferredInterface": "10.110.217.159"
            },
            "attributes": {
                "protection": {}
            },
            "operations": [
                {
                    "backupType": "SYNTHETIC_FULL",
                    "schedule": {
                        "frequency": "MONTHLY",
                        "startTime": "2019-11-05T12:00:00Z",
                        "duration": "PT10H",
                        "dayOfMonth": 3
                    }
                }
            ],
            "storageUnit": {
                "name": "ProtectionPolicy-VM-Sample1-dhvm-vmqa-152-44587",
                "credentialName": "ProtectionPolicy-VM-Sample-dhvm-vmqa-1-44587"
            }
        },
        {
            "id": "a12516db-da45-eb2f-38c8-b430e5298a98",
            "type": "REPLICATION",
            "passive": false,
            "attributes": {},
            "target": {
                "storageSystemId": "a6cead7c-58b0-49b8-aaa4-6a044149226b"
            },
            "slaId": null,
            "sourceStageId": "ad35057c-4b13-f4d1-62fd-fdd99dbddcb2",
            "operations": [
                {
                    "backupType": "SYNTHETIC_FULL",
                    "schedule": {                       
                        "frequency": "MONTHLY",
                        "startTime": "2019-11-05T12:00:00.000Z",
						"duration": "PT10H",
						"interval": 12
                    }
                }
            ],
            "retention": {
                "interval": 1,
                "unit": "DAY"
            }
        }
    ]

Remember to specify the sourceStageId to be the ID of the PROTECTION stage so that the replication stage can take backups that are generated from that source stage. Also, you can create a protection policy directly to enable the replication. See: Create protection policy with replication configured.

Create protection policy with replication configured

In addition to backups, you can also enable “REPLICATION” stage in the protection policy. To enable “REPLICATION” in the protection policy, create the protection policy by adding a REPLICATION stage:

POST /api/v2/protection-policies

With this request body:

{
    "name": "ProtectionPolicy-VM-Sample",
    "description": "This is a Protection Policy for my virtual machines",
    "assetType": "VMWARE_VIRTUAL_MACHINE",
    "type": "ACTIVE",
    "encrypted": false,
    "enabled": true,
    "priority": 1,
    "dataConsistency": "CRASH_CONSISTENT",
    "passive": false,
    "forceFull": false,
    "details": {
        "vm": {
            "protectionEngine": "VMDIRECT"
        }
    },
    "stages": [
        {
            "id": "ad35057c-4b13-f4d1-62fd-fdd99dbddcb2",
            "type": "PROTECTION",
            "passive": false,
            "attributes": {},
            "target": {
                "storageSystemId": "96ad5064-b558-453c-91f7-c2977ce06308"
            },
            "slaId": null,
            "sourceStageId": null,
            "operations": [
                {
                    "backupType": "AUTO_FULL",
                    "schedule": {
                        "frequency": "MONTHLY",
                        "startTime": "2019-11-05T12:00:00.000Z",
                        "duration": "PT10H",
                        "dayOfMonth": 1
                    }
                }
            ],
            "retention": {
                "interval": 1,
                "unit": "MONTH"
            }
        },
        {
            "id": "fa86f508-758c-409d-554b-1b11ced6e013",
            "type": "REPLICATION",
            "passive": false,
            "attributes": {},
            "target": {
                "storageSystemId": "a83f6011-4de0-4cdb-96aa-88e986cb6d8b",
                "dataTargetId": null
            },
            "slaId": null,
            "sourceStageId": "ad35057c-4b13-f4d1-62fd-fdd99dbddcb2",
            "operations": [
                {
                    "backupType": "AUTO_FULL",
                    "schedule": {
                        "frequency": "MONTHLY",
                        "startTime": "2019-11-05T22:00:00.000Z",
                        "duration": "PT10H",
                        "dayOfMonth": 2
                    }
                }
            ],
            "retention": {
                "interval": 1,
                "unit": "MONTH"
            }
        }
    ],
    "credentials": null,
    "slaId": null
}

In contrast to the previous protection policy example, notice the new stage of type REPLICATION. This stage type is used to schedule replications to another storage system by using a different storageSystemId.

Remember to specify the sourceStageId to be the ID of the PROTECTION stage so that the replication stage can take backups that are generated from that source stage.

The response of the API call also gives the created protection policy ID:

{
  "id": "c37b447f-716c-4f36-9258-d0ce8464124b",
  "name": "ProtectionPolicy-VM-Sample",
  "description": "This is a Protection Policy for my virtual machines",
  ...
}

Similar to the first protection policy example, you can use this ID to assign and unassign assets, and monitor activities.

Create protection policy with promotion configured

A stage of type “PROMOTION” may depend on the “PROTECTION” stage, which generates a backup. To configure promotion in the protection policy, you can create the protection policy by using this API call:

POST /api/v2/protection-policies

With this request body:

{
	"name": "PLC-VM-WithPromotion",
    "description": "The description for 'PLC-VM-WithPromotion' policy",
    "assetType": "VMWARE_VIRTUAL_MACHINE",
    "type": "ACTIVE",
    "encrypted": false,
    "enabled": true,
    "priority": 1,
    "dataConsistency": "CRASH_CONSISTENT",
    "passive": false,
    "forceFull": false,
    "details": {
        "vm": {
            "protectionEngine": "VMDIRECT"
        }
    },
    "stages": [
        {
            "id": "5ab35dbe-c823-810a-bbc2-5ac5c1b11447",
            "type": "PROTECTION",
            "passive": false,
            "target": {
                "storageSystemId": "a83f6011-4de0-4cdb-96aa-88e986cb6d8b",
                "dataTargetId": null,
                "preferredInterface": "10.110.217.159"
            },
            "slaId": null,
            "sourceStageId": null,
            "operations": [
                {
                    "type": "AUTO_FULL",
                    "schedule": {
                        "frequency": "DAILY",
                        "startTime": "2019-11-05T12:00:00.000Z",
                        "interval": null,
                        "duration": "PT10H"
                    }
                }
            ],
            "retention": {
                "interval": 1,
                "unit": "DAY"
            }
        },
        {
            "id": "db817fd7-2e2b-05bf-aa51-2f6c673f05f0",
            "type": "PROMOTION",
            "passive": false,
            "attributes": {},
            "target": {
                "storageSystemId": "a83f6011-4de0-4cdb-96aa-88e986cb6d8b"
            },
            "slaId": null,
            "sourceStageId": "5ab35dbe-c823-810a-bbc2-5ac5c1b11447",
            "operations": [
                {
                    "type": "AUTO_FULL",
                    "schedule": {
                        "frequency": "WEEKLY",
                        "startTime": "2019-11-05T22:00:00.000Z",
                        "weekDaysList": {
                            "weekDay": "SUNDAY"
                        },
                        "weekDays": [
                            "SUNDAY"
                        ],
                        "interval": null,
                        "duration": "PT1H"
                    }
                }
            ],
            "retention": {
                "interval": 1,
                "unit": "WEEK"
            }
        }
    ],
    "credentials": null,
    "slaId": ""
}

In contrast to the protection policy example, notice the new stage of type PROMOTION that is used. Remember to specify the sourceStageId to be the ID of the PROTECTION stage so that the promotion stage can take backups that are generated from that source stage.

The response of the API call also gives the created protection policy ID:

{
  "id": "7a8668e7-57b0-436d-87c2-2e3c406d555f",
  "name": "PLC-VM-WithPromotion",
  "description": "The description for 'PLC-VM-WithPromotion' policy",
  "assetType": "VMWARE_VIRTUAL_MACHINE",
  ...
}

Also, this ID can be used to assign assets, unassign assets, and monitor activities.

VM disk exclusion

Once you assign assets to the protection policy, you can set the value to TRUE or FALSE for VM disk exclusion. Here are some key fields that are used:

Field Data Type Description
id String The unique ID for an asset
details.vm.disks Array Each element in this array represents a VM disk.
details.vm.disks.key String Unique key string for a disk in VM asset.
details.vm.disks.name String The name of the VMDK on vCenter storage.
details.vm.disks.excluded Boolean Indicates if this disk is marked as excluded. By default, the value is false.
  • Notice that the “details.vm.disks” block must include all the disks that belong to that VM. This ensures patch data consistency.

To set VM disks exclusion at the asset level, use this call:

PATCH /api/v2/assets/{assetId}

With this request body:

{
    "id": "3f3ae277-7ad6-587f-bf26-fcf15d78ae9e",
    "details": {
        "vm": {
            "disks": [
                {
                    "name": "[RG16-7TB-LUN_1] MJ-VM/MJ-VM_1.vmdk",
                    "key": 2001,
                    "excluded": true
                },
                {
                    "name": "[RG16-7TB-LUN_1] MJ-VM/MJ-VM.vmdk",
                    "key": 2000,
                    "excluded": false
                }
            ]
        }
    }
}

The response of the API call:


200 OK
{
  "id": "3f3ae277-7ad6-587f-bf26-fcf15d78ae9e",
  "name": "MJ-VM",
  "type": "VMWARE_VIRTUAL_MACHINE",
  "userTags": null,
  "dataTargetIds": null,
  "assetGroupId": null,
  "protectionLifeCycleId": "3157b6b9-bb6a-46ea-b50c-789a4497d00c",
  "protectionPolicyId": "3157b6b9-bb6a-46ea-b50c-789a4497d00c",
  "credentialId": null,
  "deleted": false,
  "protectable": true,
  "size": 2099247,
  "lastAvailableCopyTime": null,
  "details": {
    "vm": {
      "guestOS": "Microsoft Windows Server 2008 R2 (64-bit)",
      "datacenter": "Archmage",
      "resourcePool": "Resources",
      "hostName": "10.110.216.52",
      "folder": "vm",
      "vmBiosUuid": "421f8d6f-3dd1-12d0-7ce4-0a41578fa676",
      "vcenterName": "10.110.217.158",
      "inventorySourceName": "10.110.217.158",
      "esxName": "10.110.216.52",
      "clusterName": "Archmage_Cluster",
      "protectedApplication": "NONE",
      "disks": [
        {
          "name": "[RG16-7TB-LUN_1] MJ-VM/MJ-VM_1.vmdk",
          "sizeInBytes": 1048576,
          "label": "Hard disk 2",
          "key": 2001,
          "thinProvisioned": false,
          "excluded": true
        },
        {
          "name": "[RG16-7TB-LUN_1] MJ-VM/MJ-VM.vmdk",
          "sizeInBytes": 1048576,
          "label": "Hard disk 1",
          "key": 2000,
          "thinProvisioned": false,
          "excluded": false
        }
      ],
      "externalId": "501f7002-164f-21c4-398d-af2389e4fa7f",
      "datastore": [
        {
          "datastoreMoref": "Datastore:datastore-44",
          "datastoreName": "RG16-7TB-LUN_1"
        }
      ]
    }
  },
  "ruleId": null,
  "createdAt": "2019-12-18T08:14:26.659Z",
  "updatedAt": "2019-12-19T07:18:56.278Z",
  "_embedded": {
    "protectionlifeCycle": {
      "id": "3157b6b9-bb6a-46ea-b50c-789a4497d00c",
      "name": "PLC-VM-Exclution test",
      "type": "ACTIVE",
      "protectionEngine": "VMDIRECT"
    },
    "protectionPolicy": {
      "id": "3157b6b9-bb6a-46ea-b50c-789a4497d00c",
      "name": "PLC-VM-Exclution test",
      "type": "ACTIVE",
      "protectionEngine": "VMDIRECT"
    }
  },
  "ruleName": null
}

If you try to set VM disks exclusion for a VM asset that is not protected in the protection policy, you get a 400 error response code.