Cloud Director Availability

Overview

The Programming Guide provides information about the VMware Cloud Director Availability REST APIs, including how to use the API services and resources, how to authenticate and construct REST API calls.

The guide focuses on common use cases.

HTTP verbs

To retrieve object representations, clients make HTTP requests to object references. The server supplies these references as href attribute values in responses to GET requests.

This API closely adheres to standard HTTP and REST conventions in the HTTP verbs usage.

Verb Usage

GET

Retrieve a resource.

POST

Create a new resource.

PUT

Replace an existing resource.

PATCH

Update an existing resource, including partial update.

DELETE

Delete an existing resource.

HTTP status codes

All responses include an HTTP status code and, unless the status code is 204 (No Content), a Content-Type header. Response content depends on the request. Some responses include a document body, some include only a URL, and some are empty.

This API closely adheres to standard HTTP and REST conventions in the HTTP status codes usage.

Status code Usage

200 OK

The request is valid and is completed. The response includes a document body.

201 Created

The request is valid. The requested object is created and can be found at the URL specified in the Location header.

204 No Content

The request is valid and an update to an existing object is successfully applied. The response does not include a body.

400 Bad Request

The request body is malformed, incomplete, or otherwise invalid. The response body includes an error that provides additional information.

404 Not Found

The requested object does not exist.

Errors

When returning an error response (status code >=400), the response body contains a JSON object describing the problem. The JSON error contains the following structure:

Path Type Description

code

String

A unique error identifier, for example NotAuthenticated.

msg

String

A detailed message.

args

Array

Additional parameters.

stacktrace

String

Stacktrace.

The following example shows a request attempting to apply a non-existent tag to a note, resulting in a 400 Bad Request response.

HTTP/1.1 403 Forbidden
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 8289

{
  "code" : "Forbidden",
  "msg" : "Permission denied.",
  "args" : [ ],
  "stacktrace" : "com.vmware.h4.api.error.exceptions.PermissionDeniedException: Permission denied.\n\tat com.vmware.h4.common.error.ApiErrorProvider.lambda$createStatusCodeMap$4(ApiErrorProvider.java:120)\n\tat com.vmware.h4.common.error.ApiErrorProvider.convertHttpStatusCode(ApiErrorProvider.java:67)\n\tat com.vmware.h4.common.controller.BaseErrorController.error(BaseErrorController.java:71)\n\tat com.vmware.h4.cloud.controller.error.JsonErrorController.error(JsonErrorController.java:31)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)\n\tat java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\n\tat java.base/java.lang.reflect.Method.invoke(Method.java:566)\n\tat org.springframework.web.method.support.InvocableHandlerMethod.doInvoke(InvocableHandlerMethod.java:190)\n\tat org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:138)\n\tat org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:105)\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:878)\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:792)\n\tat org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)\n\tat org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1040)\n\tat org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:943)\n\tat org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006)\n\tat org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:898)\n\tat javax.servlet.http.HttpServlet.service(HttpServlet.java:645)\n\tat org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:883)\n\tat org.springframework.test.web.servlet.TestDispatcherServlet.service(TestDispatcherServlet.java:72)\n\tat javax.servlet.http.HttpServlet.service(HttpServlet.java:750)\n\tat org.springframework.mock.web.MockFilterChain$ServletFilterProxy.doFilter(MockFilterChain.java:167)\n\tat org.springframework.mock.web.MockFilterChain.doFilter(MockFilterChain.java:134)\n\tat org.springframework.test.web.servlet.MockMvc.perform(MockMvc.java:183)\n\tat com.vmware.spring.restdocs.BaseApiDocumentation.errorExample(BaseApiDocumentation.java:705)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)\n\tat java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\n\tat java.base/java.lang.reflect.Method.invoke(Method.java:566)\n\tat org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:59)\n\tat org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12)\n\tat org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:56)\n\tat org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17)\n\tat org.springframework.test.context.junit4.statements.RunBeforeTestExecutionCallbacks.evaluate(RunBeforeTestExecutionCallbacks.java:74)\n\tat org.springframework.test.context.junit4.statements.RunAfterTestExecutionCallbacks.evaluate(RunAfterTestExecutionCallbacks.java:84)\n\tat org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26)\n\tat org.springframework.test.context.junit4.statements.RunBeforeTestMethodCallbacks.evaluate(RunBeforeTestMethodCallbacks.java:75)\n\tat org.springframework.test.context.junit4.statements.RunAfterTestMethodCallbacks.evaluate(RunAfterTestMethodCallbacks.java:86)\n\tat org.springframework.restdocs.JUnitRestDocumentation$1.evaluate(JUnitRestDocumentation.java:61)\n\tat org.springframework.test.context.junit4.statements.SpringRepeat.evaluate(SpringRepeat.java:84)\n\tat org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:366)\n\tat org.springframework.test.context.junit4.SpringJUnit4ClassRunner.runChild(SpringJUnit4ClassRunner.java:251)\n\tat org.springframework.test.context.junit4.SpringJUnit4ClassRunner.runChild(SpringJUnit4ClassRunner.java:97)\n\tat org.junit.runners.ParentRunner$4.run(ParentRunner.java:331)\n\tat org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:79)\n\tat org.junit.runners.ParentRunner.runChildren(ParentRunner.java:329)\n\tat org.junit.runners.ParentRunner.access$100(ParentRunner.java:66)\n\tat org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:293)\n\tat org.springframework.test.context.junit4.statements.RunBeforeTestClassCallbacks.evaluate(RunBeforeTestClassCallbacks.java:61)\n\tat org.springframework.test.context.junit4.statements.RunAfterTestClassCallbacks.evaluate(RunAfterTestClassCallbacks.java:70)\n\tat org.junit.runners.ParentRunner$3.evaluate(ParentRunner.java:306)\n\tat org.junit.runners.ParentRunner.run(ParentRunner.java:413)\n\tat org.springframework.test.context.junit4.SpringJUnit4ClassRunner.run(SpringJUnit4ClassRunner.java:190)\n\tat org.gradle.api.internal.tasks.testing.junit.JUnitTestClassExecutor.runTestClass(JUnitTestClassExecutor.java:110)\n\tat org.gradle.api.internal.tasks.testing.junit.JUnitTestClassExecutor.execute(JUnitTestClassExecutor.java:58)\n\tat org.gradle.api.internal.tasks.testing.junit.JUnitTestClassExecutor.execute(JUnitTestClassExecutor.java:38)\n\tat org.gradle.api.internal.tasks.testing.junit.AbstractJUnitTestClassProcessor.processTestClass(AbstractJUnitTestClassProcessor.java:62)\n\tat org.gradle.api.internal.tasks.testing.SuiteTestClassProcessor.processTestClass(SuiteTestClassProcessor.java:51)\n\tat jdk.internal.reflect.GeneratedMethodAccessor508.invoke(Unknown Source)\n\tat java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\n\tat java.base/java.lang.reflect.Method.invoke(Method.java:566)\n\tat org.gradle.internal.dispatch.ReflectionDispatch.dispatch(ReflectionDispatch.java:36)\n\tat org.gradle.internal.dispatch.ReflectionDispatch.dispatch(ReflectionDispatch.java:24)\n\tat org.gradle.internal.dispatch.ContextClassLoaderDispatch.dispatch(ContextClassLoaderDispatch.java:33)\n\tat org.gradle.internal.dispatch.ProxyDispatchAdapter$DispatchingInvocationHandler.invoke(ProxyDispatchAdapter.java:94)\n\tat com.sun.proxy.$Proxy2.processTestClass(Unknown Source)\n\tat org.gradle.api.internal.tasks.testing.worker.TestWorker.processTestClass(TestWorker.java:119)\n\tat jdk.internal.reflect.GeneratedMethodAccessor507.invoke(Unknown Source)\n\tat java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)\n\tat java.base/java.lang.reflect.Method.invoke(Method.java:566)\n\tat org.gradle.internal.dispatch.ReflectionDispatch.dispatch(ReflectionDispatch.java:36)\n\tat org.gradle.internal.dispatch.ReflectionDispatch.dispatch(ReflectionDispatch.java:24)\n\tat org.gradle.internal.remote.internal.hub.MessageHubBackedObjectConnection$DispatchWrapper.dispatch(MessageHubBackedObjectConnection.java:182)\n\tat org.gradle.internal.remote.internal.hub.MessageHubBackedObjectConnection$DispatchWrapper.dispatch(MessageHubBackedObjectConnection.java:164)\n\tat org.gradle.internal.remote.internal.hub.MessageHub$Handler.run(MessageHub.java:414)\n\tat org.gradle.internal.concurrent.ExecutorPolicy$CatchAndRecordFailures.onExecute(ExecutorPolicy.java:64)\n\tat org.gradle.internal.concurrent.ManagedExecutorImpl$1.run(ManagedExecutorImpl.java:48)\n\tat java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)\n\tat java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)\n\tat org.gradle.internal.concurrent.ThreadFactoryImpl$ManagedThreadRunnable.run(ThreadFactoryImpl.java:56)\n\tat java.base/java.lang.Thread.run(Thread.java:834)\n"
}

Operation IDs

By setting a value for 'operationID' in the HTTP header, you can trace an operation across all services.

Request headers

Name Description

operationID

A string used as an identifier for tracing an operation in the logs across services.

Request structure

GET /config/is-configured HTTP/1.1
operationID: 2bfb7696-3aa1-49d3-bb40-d9e97df1baba
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/config/is-configured' -i -X GET \
    -H 'operationID: 2bfb7696-3aa1-49d3-bb40-d9e97df1baba' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Health Information and Support Bundles

The Cloud Service provides the following diagnostics APIs:

  • health information - provides basic service health information such as database health, connectivity to remote services, and others.

  • support bundle(s) - representing an archive containing system information, logs, configurations of Cloud service instance as well as the same information for Manager Service instance, Replicator Service instances, and Tunnel Service instance.

Get Health Information

GET /diagnostics/health provides the following information:

  • if the Cloud Service can access its database

  • if the Cloud Service can communicate with the vCenter Server Lookup Service

  • if the Cloud Service can communicate with the Tunnel Service

  • if the Cloud Service can communicate with VMware Cloud Director

  • if the Cloud Service can communicate with the Manager Service

  • the overall health of the Manager Service

Available since: v4.1

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Request structure

GET /diagnostics/health HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/diagnostics/health' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.productName

String

The name of the product.

result.buildVersion

String

Represents the product version along with the build ID.

result.buildDate

Number

RPM build time.

result.instanceId

String

Unique identifier of the service, which never changes.

result.runtimeId

String

A value that remains constant for as long as the Cloud Service is running. If the value changes, this indicates the Cloud Service is restarted.

result.currentTime

Number

The current time (in UTC) of the appliance.

result.address

String

The IP address or hostname of the appliance.

result.tunnelError

Object

Indicates if the Cloud Service can communicate with the local Tunnel Service. The connection is successfull when the value is Null, otherwise the value shows the error.

result.vcdError

Object

Indicates if the Cloud Service can communicate with the local VMware Cloud Director. The connection is successfull when the value is Null, otherwise the value shows the error.

result.managerError

Object

Indicates if the Cloud Service can communicate with the local Manager Service. The connection is successfull when the value is Null, otherwise the value shows the error.

result.managerHealth

Object

Diagnostics information about the local Manager service.

result.lsError

Object

Indicates if the Cloud Service can communicate with the vCenter Server Lookup Service. The connection is successfull when the value is Null, otherwise the value shows the error.

result.dbError

Object

Indicates if the Cloud Service can communicate with its database. The connection is successfull when the value is Null, otherwise the value shows the error.

result.ntpError

Object

Diagnostics information about the NTP server.

result.diskUsage

Object

Details for the disk usage and free disk space.

result.diskUsage.total

Number

File system size (in bytes).

result.diskUsage.usable

Number

Free disk space available to user processes (in bytes).

result.diskUsage.free

Number

Free disk space available to the appliance OS (in bytes).

site

String

The site name where the task runs.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 2792

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "healthInfo",
    "resourceType" : "cloudService",
    "resourceId" : "resourceId",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "CloudHealthInfo",
  "result" : {
    "productName" : "VMware Cloud Director Availability Cloud Service",
    "buildVersion" : "4.1.0.1660207-48e5972493",
    "buildDate" : 1606132528104,
    "instanceId" : "0d326966-6338-48ff-86fb-ee0e55b8cd93",
    "runtimeId" : "49453711-3448-47c5-9e11-d63287ccfd27",
    "currentTime" : 1499177196042,
    "address" : "1.2.3.4",
    "tunnelError" : {
      "code" : "TunnelNotConfigured",
      "msg" : "Missing Tunnel settings.",
      "args" : [ ],
      "stacktrace" : ""
    },
    "vcdError" : {
      "code" : "FailedToRetrieveVcdFromLookupService",
      "msg" : "Unable to retrieve vCloud Director endpoint from the LookupService.",
      "args" : [ ],
      "stacktrace" : ""
    },
    "managerError" : {
      "code" : "ConnectionRefused",
      "msg" : "Connection refused.",
      "args" : [ ],
      "stacktrace" : ""
    },
    "managerHealth" : {
      "productName" : "VMware Cloud Director Availability Manager Service",
      "buildVersion" : "4.1.0.1660207-48e5972493",
      "buildDate" : 1606132528104,
      "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "runtimeId" : "107102e0-e03b-404e-8e17-0688c657a74b",
      "currentTime" : 1499177196042,
      "address" : "1.2.3.4",
      "offlineReplicators" : [ ],
      "onlineReplicators" : [ ],
      "localReplicatorsHealth" : [ ],
      "lsError" : null,
      "dbError" : {
        "code" : "GeneralServerFailure",
        "msg" : "Operation aborted due to an unexpected error.",
        "args" : [ ],
        "stacktrace" : null
      },
      "ntpError" : null,
      "localReplicatorsLsMismatch" : null,
      "diskUsage" : {
        "total" : 10123528,
        "usable" : 8691736,
        "free" : 897832
      }
    },
    "lsError" : {
      "code" : "LookupServiceNotConfigured",
      "msg" : "Missing Lookup Service setting. Please, set one.",
      "args" : [ ],
      "stacktrace" : ""
    },
    "dbError" : {
      "code" : "ConnectionRefused",
      "msg" : "Connection refused.",
      "args" : [ ],
      "stacktrace" : ""
    },
    "ntpError" : {
      "code" : "FailedToConnectToNtpServer",
      "msg" : "Time is not synchronized with the NTP server.",
      "args" : [ ],
      "stacktrace" : ""
    },
    "diskUsage" : {
      "total" : 10123528,
      "usable" : 8691736,
      "free" : 897832
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Support Bundles

The support bundles contain logs and configuration files that are useful for troubleshooting issues.

Generate a Support Bundle

POST /diagnostics/bundles generates a new support bundle. Note that this operation requires administrative permissions and might take some time to complete.

Available since: v2

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Request structure
POST /diagnostics/bundles HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The ID of the generated bundle.

result.generatedOn

Number

The timestamp of the moment the bundle was generated.

result.sha

String

A SHA-512 checksum of the bundle payload.

result.owner

String

The owner of the bundle.

site

String

The site name where the task runs.

Example response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 608

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "unknown",
    "resourceType" : "unknown",
    "resourceId" : null,
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SupportBundleInfo",
  "result" : {
    "id" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "generatedOn" : 1499929548951,
    "sha" : "SHA-512:2C:...:ED:A0",
    "owner" : "owner1"
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Generate a Support Bundle with an ID

POST /diagnostics/bundles/{bundleId} generates a new support bundle with an ID provided by the user. This operation requires administrative permissions and might take some time.

Available since: v2

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters
/diagnostics/bundles/{bundleId}
Parameter Description

bundleId

User-provided ID to use when generating the bundle.

Request structure
POST /diagnostics/bundles/2bfb7696-3aa1-49d3-bb40-d9e97df1baba HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles/2bfb7696-3aa1-49d3-bb40-d9e97df1baba' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The ID of the generated bundle.

result.generatedOn

Number

The timestamp of the moment the bundle was generated.

result.sha

String

A SHA-512 checksum of the bundle payload.

result.owner

String

The owner of the bundle.

site

String

The site name where the task runs.

Example response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 649

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "generate",
    "resourceType" : "supportBundle",
    "resourceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SupportBundleInfo",
  "result" : {
    "id" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "generatedOn" : 1499929548951,
    "sha" : "SHA-512:2C:...:ED:A0",
    "owner" : "owner1"
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

POST /diagnostics/bundles/cookie/{bundleId} generates a one-time cookie that can be used to download a support bundle. This operation requires administrative permissions.

Available since: v2

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters
/diagnostics/bundles/cookie/{bundleId}
Parameter Description

bundleId

User-provided ID to use when generating the bundle.

Request structure
POST /diagnostics/bundles/cookie/5ee9224f-305d-46f6-865f-b605e70acef8 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles/cookie/5ee9224f-305d-46f6-865f-b605e70acef8' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

cookie

String

The generated cookie.

Example response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 47

{
  "cookie" : "lBvDMttZLLnWVZwC+85ufqiNt4M="
}

List the Available to Download Support Bundles

GET /diagnostics/bundles lists all support bundles that are available to download.

Available since: v2

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Request structure
GET /diagnostics/bundles HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

[].id

String

The id of the bundle.

[].generatedOn

Number

The timestamp of the moment the bundle was generated.

[].sha

String

A SHA-512 checksum of the bundle payload.

[].owner

String

The owner of the bundle.

Example response
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 144

[ {
  "id" : "5ee9224f-305d-46f6-865f-b605e70acef8",
  "generatedOn" : 1499929548951,
  "sha" : "SHA-512:2C:...:ED:A0",
  "owner" : "owner1"
} ]

Download a Support Bundle

GET /diagnostics/bundles/{bundleId} downloads the specified support bundle by ID.

Available since: v3.5

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters
/diagnostics/bundles/{bundleId}
Parameter Description

bundleId

The id of the bundle to download.

Request structure
GET /diagnostics/bundles/5ee9224f-305d-46f6-865f-b605e70acef8 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+octet-stream;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles/5ee9224f-305d-46f6-865f-b605e70acef8' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+octet-stream;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
To save the bundle file in the current folder, pass the -J and -O arguments to curl.
Example response
HTTP/1.1 200 OK
Content-Type: application/x-gtar
Content-Disposition: inline; filename="cloud-bundle-2bfb7696-3aa1-49d3-bb40-d9e97df1baba-2017-07-13_07-05-48_UTC.tar.bz2"
Accept-Ranges: bytes
Content-Length: 39

<<bundle contents, a .tar.bz2 archive>>

GET /diagnostics/bundles/cookie/{bundleId} downloads the specified support bundle by ID, without requiring a valid API key. Use this API in client-side web browsers.

Available since: v3.5

Required roles: (authentication not required)

Path parameters
/diagnostics/bundles/cookie/{bundleId}
Parameter Description

bundleId

The id of the bundle to download.

Request structure
GET /diagnostics/bundles/cookie/5ee9224f-305d-46f6-865f-b605e70acef8?cookie=lBvDMttZLLnWVZwC+85ufqiNt4M%3D&cookie=lBvDMttZLLnWVZwC%2B85ufqiNt4M%3D HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+octet-stream;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles/cookie/5ee9224f-305d-46f6-865f-b605e70acef8?cookie=lBvDMttZLLnWVZwC+85ufqiNt4M%3D&cookie=lBvDMttZLLnWVZwC%2B85ufqiNt4M%3D' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+octet-stream;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
To save the bundle file in the current folder, pass the -J and -O arguments to curl.
Example response
HTTP/1.1 200 OK
Content-Type: application/x-gtar
Content-Disposition: inline; filename="cloud-bundle-null-2017-07-13_07-05-48_UTC.tar.bz2"
Accept-Ranges: bytes
Content-Length: 39

<<bundle contents, a .tar.bz2 archive>>

Delete a Support Bundle

DELETE /diagnostics/bundles/{bundleId} deletes the specified support bundle by ID and reclaims the disk space that the support bundle occupies.

Available since: v2

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters
/diagnostics/bundles/{bundleId}
Parameter Description

bundleId

The ID of the bundle to delete.

Request structure
DELETE /diagnostics/bundles/5ee9224f-305d-46f6-865f-b605e70acef8 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/diagnostics/bundles/5ee9224f-305d-46f6-865f-b605e70acef8' -i -X DELETE \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

Details of the deleted support bundle.

site

String

The site name where the task runs.

Example response
HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 608

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "unknown",
    "resourceType" : "unknown",
    "resourceId" : null,
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SupportBundleInfo",
  "result" : {
    "id" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "generatedOn" : 1499929548951,
    "sha" : "SHA-512:2C:...:ED:A0",
    "owner" : "owner1"
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Get product information

GET /diagnostics/about returns information about the product, such as service type, version, build number, and others.

Available since: v3.5

Required roles: EVERYONE

Request structure

GET /diagnostics/about HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/diagnostics/about' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

serviceType

String

Machine readable service type ID.

productName

String

The name of the product.

instanceId

String

Unique identifier of the service, which never changes.

buildVersion

String

Represents the product version along with the build ID.

buildDate

Number

The build time of the product measured in milliseconds.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 234

{
  "serviceType" : "CLOUD",
  "productName" : "VMware Cloud Director Availability Cloud Service",
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "buildVersion" : "4.1.0.1660207-48e5972493",
  "buildDate" : 1606132528104
}

Long running tasks

By using the tasks resources you can track the progress of long-running operations, like job executions. To retrieve an update on the progress, currently polling is the only supported method.

Get the Details of a Task

GET /tasks/{taskId} retrieves the current state of the task. The result (failure or success) is not available yet.

User A cannot retrieve the tasks of user B.
Different tasks have different result types.
During the execution of the task, warnings may occur, indicating a failure that is not critical and the task continues to execute.

Available since: v2

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/tasks/{taskId}
Parameter Description

taskId

UUID of the task.

Request parameters

Parameter Description

site

Optional site to retrieve the task from. Could be a remote site or the local one.

Request structure

GET /tasks/2bfb7696-3aa1-49d3-bb40-d9e97df1baba?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/tasks/2bfb7696-3aa1-49d3-bb40-d9e97df1baba?site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

The result of the task. Populated only if the execution was successful.

site

String

The site name where the task runs.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 622

{
  "id" : "f61d60d2-698a-46dc-a266-88df27644956",
  "user" : "root",
  "workflowInfo" : {
    "type" : "update",
    "resourceType" : "appliance",
    "resourceId" : null,
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "UpdateRepoConfig",
  "result" : {
    "defaultUpdateRepo" : "my-update-url.com",
    "customUpdateRepo" : {
      "repositoryUrl" : "cdrom://",
      "username" : null,
      "password" : null
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Get the Details of Multiple Tasks

POST /tasks/poll requests the tasks that are specified in the body. Use this request for efficient task polling. The returned task is filtered and only the task that belongs to the current user is returned.

Available since: v2

Required roles: One of EVERYONE, PEER_MONITORING

Request parameters

Parameter Description

site

Optional site to retrieve the task from. Could be a remote site or the local one.

Request fields

Path Type Description

[]

Array

List of task ids.

Request structure

POST /tasks/poll?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 122

[ "f61d60d2-698a-46dc-a266-88df27644956", "5ee9224f-305d-46f6-865f-b605e70acef8", "2bfb7696-3aa1-49d3-bb40-d9e97df1baba" ]

Example request

$ curl 'https://localhost:8046/tasks/poll?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '[ "f61d60d2-698a-46dc-a266-88df27644956", "5ee9224f-305d-46f6-865f-b605e70acef8", "2bfb7696-3aa1-49d3-bb40-d9e97df1baba" ]'

Response structure

Path Type Description

propertyNames

Array

Names of task properties.

values

Array

List of values of task properties.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 277

{
  "propertyNames" : [ "id", "user", "workflowInfo.type", "workflowInfo.resourceType", "workflowInfo.resourceId", "workflowInfo.resourceName", "progress", "state", "lastUpdated", "startTime", "endTime", "resultType", "result", "error", "warnings", "site" ],
  "values" : [ ]
}

Get the Details of All the Tasks

GET /tasks retrieves all the tasks of the current user. This request allows paging. The result contains multiple task details. See Get the Details of a Task for information about the details of each task.

By default, the maximum retrievable elements are 100.
By default, the tasks are sorted in descending order by startTime.

Available since: v4

Required roles: One of EVERYONE, PEER_MONITORING

Request parameters

Parameter Description

site

Optional site to retrieve the task from. Could be a remote site or the local one.

ids

When present, the IDs of the returned tasks are listed. Expects comma-separated task IDs.

sourceOrg

Optional case sensitive filtering field.

destinationOrg

Optional case sensitive filtering field, available only to admins.When present, filtering by user is not supported.

user

When present, applies equals filtering by username. Available only to admins.

state

When present, applies equals filtering by state. Available values: [RUNNING, SUCCEEDED, FAILED].

startTimeBefore

When present, applies less-than filtering by startTime.

startTimeAfter

When present, applies greater-than filtering by startTime.

endTimeBefore

When present, applies less-than filtering by endTime.

endTimeAfter

When present, applies greater-than filtering by endTime.

type

When present, applies equals filtering by workflowinfo.type.

resourceId

When present, applies equals filtering by workflowinfo.resourceId.

resourceName

When present, applies equals filtering by workflowinfo.resourceName.

resourceType

When present, applies equals filtering by workflowinfo.resourceType.

sort

An optional list of comma-separated fields, used to sort the result. The default sorting direction is ascending. When a field finishes with a hyphen, the sorting direction for this field is descending. This allows chaining e.g. col,col2-,col3 will result in sorting by col (asc), then by col2 (desc) and finally by col3 (asc). Supported fields: [startTime, state, endTime, user]. If this field is omitted, the result is sorted by start time in descending order.

limit

The maximum number of items the query retrieves. By default the limit is 100, when omitted or higher than the limit of the server.

offset

Number of items to skip before retrieving the items. By default, when ommited, the query offset is 0.

Request structure

GET /tasks?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/tasks?site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

total

Number

The total number of items in the database of the Cloud Service.

offset

Number

Number of items skipped before retrieving the items.

limit

Number

The maximum number of items that this query retrieves.

items

Array

A list of tasks.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 1885

{
  "items" : [ {
    "id" : "f61d60d2-698a-46dc-a266-88df27644956",
    "user" : "root",
    "workflowInfo" : {
      "type" : "update",
      "resourceType" : "appliance",
      "resourceId" : null,
      "resourceName" : null
    },
    "progress" : 100,
    "state" : "SUCCEEDED",
    "lastUpdated" : 1499929558827,
    "startTime" : 1499929548951,
    "endTime" : 1499929558827,
    "resultType" : "UpdateRepoConfig",
    "result" : {
      "defaultUpdateRepo" : "my-update-url.com",
      "customUpdateRepo" : {
        "repositoryUrl" : "cdrom://",
        "username" : null,
        "password" : null
      }
    },
    "error" : null,
    "warnings" : [ ],
    "site" : "site2"
  }, {
    "id" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "user" : "user1",
    "workflowInfo" : {
      "type" : "replication",
      "resourceType" : "stop",
      "resourceId" : "123",
      "resourceName" : null
    },
    "progress" : 100,
    "state" : "FAILED",
    "lastUpdated" : 1499929558827,
    "startTime" : 1499929548951,
    "endTime" : 1499929558827,
    "resultType" : null,
    "result" : null,
    "error" : {
      "code" : "ReplicationNotFound",
      "msg" : "Replication with id '123' was not found.",
      "args" : [ "123" ],
      "stacktrace" : null
    },
    "warnings" : [ ],
    "site" : "site2"
  }, {
    "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
    "user" : "tenant1",
    "workflowInfo" : {
      "type" : "generate",
      "resourceType" : "supportBundle",
      "resourceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "resourceName" : null
    },
    "progress" : 10,
    "state" : "RUNNING",
    "lastUpdated" : 1499929548951,
    "startTime" : 1499929548951,
    "endTime" : -1,
    "resultType" : null,
    "result" : null,
    "error" : null,
    "warnings" : [ ],
    "site" : "site2"
  } ],
  "total" : 3,
  "offset" : 0,
  "limit" : 100
}

Authentication Methods

Administrative Authentication

To establish an administrative connection to the Cloud Service, provide valid SSO credentials for an SSO account that is a member of the ADMINISTRATORS or VRADMINISTRATORS SSO groups. Alternatively, to establish an administrative connection you can use the appliance root user credentials. By using an administrative connection you can monitor and manage any replication and the service itself.

Establish a Session by Using the Appliance Credentials

POST /sessions creates a new administrative session to the Cloud Service when the supplied appliance root user credentials are correct.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The authentication scheme used to establish the new session. To login by using local appliance credentials, you must set this field to 'localUser'.

localUser

String

Must be set to 'root'.

localPassword

String

The password corresponding to the 'root' user account.

Request structure
POST /sessions HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Host: localhost:8046
Content-Length: 82

{
  "type" : "localUser",
  "localUser" : "root",
  "localPassword" : "password"
}
Example request
$ curl 'https://localhost:8046/sessions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -d '{
  "type" : "localUser",
  "localUser" : "root",
  "localPassword" : "password"
}'
Response headers
Name Description

X-VCAV-Auth

API authentication token the client should use on subsequent requests.

Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 132

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  } ]
}

Establish a Session by Using SSO credentials

POST /sessions creates a new administrative session to the Cloud Service when the supplied SSO credentials are correct.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The authentication scheme used to establish the new session. To login by using SSO credentials, you must set this field to 'ssoCredentials'.

username

String

The SSO username.

password

String

The SSO password.

Request structure
POST /sessions HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Host: localhost:8046
Content-Length: 83

{
  "type" : "ssoCredentials",
  "username" : "ssoUser",
  "password" : "ssoPass"
}
Example request
$ curl 'https://localhost:8046/sessions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -d '{
  "type" : "ssoCredentials",
  "username" : "ssoUser",
  "password" : "ssoPass"
}'
Response headers
Name Description

X-VCAV-Auth

API authentication token the client should use on subsequent requests.

Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 132

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  } ]
}

Establish a Session by Using SSO SAML token

Use the SSO SAML token as a recommended authentication method for the external systems to communicate with the Cloud Service API.

POST /sessions creates a new administrative session to the Cloud service.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The authentication scheme used to establish the new session. To login by using SAML token, you must set this field to 'ssoToken'.

samlToken

String

The SAML token.

timestamp

Number

The difference, according to the client, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

nonce

String

A sequence of random characters that the client generates for each login request.

signature

String

A Base64-encoded SHA256withRSA signature of samlToken + timestamp + nonce. Only needed for Holder-of-Key SAML tokens.

Request structure
POST /sessions HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Host: localhost:8046
Content-Length: 205

{
  "type" : "ssoToken",
  "samlToken" : "<saml2:Assertion xmlns:saml2=...>...</saml2:Assertion>",
  "timestamp" : 1465194049081,
  "nonce" : "jF845646gJzx734",
  "signature" : "c2FtcGxlU2lnbmF0dXJlCg=="
}
Example request
$ curl 'https://localhost:8046/sessions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -d '{
  "type" : "ssoToken",
  "samlToken" : "<saml2:Assertion xmlns:saml2=...>...</saml2:Assertion>",
  "timestamp" : 1465194049081,
  "nonce" : "jF845646gJzx734",
  "signature" : "c2FtcGxlU2lnbmF0dXJlCg=="
}'
Response headers
Name Description

X-VCAV-Auth

API authentication token the client should use on subsequent requests.

Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 132

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  } ]
}

Establish a Session by Using VMware Cloud Director Provider Credentials

POST /sessions creates a new administrative session to the Cloud Service.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The authentication scheme used to establish the new session. To login by using VMware Cloud Director credentials, you must set this field to 'vcdCredentials'.

vcdUser

String

Must be set to 'root@System'.

vcdPassword

String

The password corresponding to the 'root' user account.

Request structure
POST /sessions HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Host: localhost:8046
Content-Length: 90

{
  "type" : "vcdCredentials",
  "vcdUser" : "root@System",
  "vcdPassword" : "password"
}
Example request
$ curl 'https://localhost:8046/sessions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -d '{
  "type" : "vcdCredentials",
  "vcdUser" : "root@System",
  "vcdPassword" : "password"
}'
Response headers
Name Description

X-VCAV-Auth

API authentication token the client should use on subsequent requests.

Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 132

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  } ]
}

Tenant Authentication

Use VMware Cloud Director tenant credentials to establish a user session to the Cloud Service. User sessions do not have administrative privileges and can only manage and monitor the replications that the user owns.

Establish a Session by Using VMware Cloud Director Tenant Credentials

POST /sessions creates a new user session to the Cloud Service.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

Identifies the authentication scheme to use for beginning the new session. To login using VMware Cloud Director credentials, you must set this field to 'vcdCredentials'.

vcdUser

String

The fully qualified username of the tenant.

vcdPassword

String

The password corresponding to tenant account.

Request structure
POST /sessions HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Host: localhost:8046
Content-Length: 90

{
  "type" : "vcdCredentials",
  "vcdUser" : "admin1@org2",
  "vcdPassword" : "password"
}
Example request
$ curl 'https://localhost:8046/sessions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -d '{
  "type" : "vcdCredentials",
  "vcdUser" : "admin1@org2",
  "vcdPassword" : "password"
}'
Response headers
Name Description

X-VCAV-Auth

API authentication token the client should use on subsequent requests.

Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 132

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  } ]
}

Establish a Session by Using VMware Cloud Director JWT

When you have access to a VMware Cloud Director JSON Web Token (JWT) that is associated with an active VMware Cloud Director session, you can use the JWT to create a user session to the Cloud Service. For more information about JWT, see https://docs.vmware.com/en/VMware-Cloud-Director-Availability/4.0/VMware-Cloud-Director-Availability-40-User-Guide/GUID-C56B7E35-70F1-455D-A9D0-704E4A3A073D.html

POST /sessions creates a new user session to the Cloud Service.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The authentication scheme used to establish the new session. To login by using VMware Cloud Director JWT, you must set this field to 'vcdAccessToken'.

vcdAccessToken

String

The VMware Cloud Director JWT.

context

String

If this token is issued by a VMware Cloud Director instance different than the local one, this field is used to setup the authorization context header used for Multisite.

Request structure
POST /sessions HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Host: localhost:8046
Content-Length: 105

{
  "type" : "vcdAccessToken",
  "vcdAccessToken" : "eyJhbGciOiJSUzI1NiJ9....",
  "context" : "acme-dr"
}
Example request
$ curl 'https://localhost:8046/sessions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -d '{
  "type" : "vcdAccessToken",
  "vcdAccessToken" : "eyJhbGciOiJSUzI1NiJ9....",
  "context" : "acme-dr"
}'
Response headers
Name Description

X-VCAV-Auth

API authentication token the client should use on subsequent requests.

Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 132

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  } ]
}

Session Lifecycle Management

Get the Current Session

GET /sessions returns the currently authenticated session.

Available since: v2

Required roles: One of EVERYONE, PEER_MONITORING

Request structure
GET /sessions HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/sessions' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 180

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  }, {
    "site" : "site2",
    "org" : "org2"
  } ]
}

Extend the Session by Using VMware Cloud Director Credentials

To manage replications on remote cloud sites, you must first extend your session to the remote site by using VMware Cloud Director mulltisite authentication. Prerequisites are that the VMware Cloud Director instances and the respective organization in each site must be associated.

POST /sessions/extend extends the Cloud Service session by using VMware Cloud Director organization credentials for the remote site.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The type of authentication. For authentication with VMware Cloud Director credentials, you must set this field to 'credentials'.

site

String

The VMware Cloud Director site that you are logging in to.

vcdUsername

String

A fully qualified VMware Cloud Director username.

vcdPassword

String

The corresponding password.

Request structure
POST /sessions/extend HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 111

{
  "type" : "credentials",
  "site" : "site1",
  "vcdUsername" : "admin1@org2",
  "vcdPassword" : "password"
}
Example request
$ curl 'https://localhost:8046/sessions/extend' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "credentials",
  "site" : "site1",
  "vcdUsername" : "admin1@org2",
  "vcdPassword" : "password"
}'
Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 180

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  }, {
    "site" : "site2",
    "org" : "org2"
  } ]
}

Extend the Session by Using VMware Cloud Director JWT

To manage replications on remote cloud sites, you must first extend your session to the remote site by providing JWT for the remote VMware Cloud Director.

POST /sessions/extend extends the Cloud Service session by using a JWT for the remote site.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The type of authentication. For authentication with VMware Cloud Director JWT, you must set this field to 'accessToken'.

site

String

The VMware Cloud Director site that you are logging in to.

accessToken

String

A valid jwt for the specified VMware Cloud Director.

context

String

If this token is issued by a VMware Cloud Director instance, different than the local one, this field is used to setup the authorization context header used for Multisite.

Request structure
POST /sessions/extend HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 119

{
  "type" : "accessToken",
  "site" : "site1",
  "accessToken" : "eyJhbGciOiJSUzI1NiJ9....",
  "context" : "acme-dr"
}
Example request
$ curl 'https://localhost:8046/sessions/extend' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "accessToken",
  "site" : "site1",
  "accessToken" : "eyJhbGciOiJSUzI1NiJ9....",
  "context" : "acme-dr"
}'
Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 180

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  }, {
    "site" : "site2",
    "org" : "org2"
  } ]
}

Extend the Session by Using VMware Cloud Director Multisite Authentication

In order to perform replication management operations that involve remote sites, your session can be "extended" using VMware Cloud Director Mulltisite. This assumes that the VMware Cloud Director instances and the respective Organization in each site are already associated.

POST /sessions/extend extends the Cloud Service session using its internally stored Json Web Token that is associated with the current session.

Available since: v2

Required roles: (authentication not required)

Request fields
Path Type Description

type

String

The type of authentication. For authentication with VMware Cloud Director multisite authentication, set 'multisite'.

site

String

The VMware Cloud Director sites to which you are logging in.

org

String

The short name of the remote organization. This field sets up the X-VMWAREVCLOUD-AUTH-CONTEXT header.

Request structure
POST /sessions/extend HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 64

{
  "type" : "multisite",
  "site" : "site1",
  "org" : "org1"
}
Example request
$ curl 'https://localhost:8046/sessions/extend' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "multisite",
  "site" : "site1",
  "org" : "org1"
}'
Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 180

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  }, {
    "site" : "site2",
    "org" : "org2"
  } ]
}

Shrink the Session

DELETE /sessions/{site} forces the Cloud Service to forget the associated authentication for the external site (if any) for the current session.

Available since: v2

Required roles: EVERYONE

Path parameters
/sessions/{site}
Parameter Description

site

The VMware Cloud Director site to exclude from the current session.

Request structure
DELETE /sessions/eu-sof-1 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/sessions/eu-sof-1' -i -X DELETE \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Response structure
Path Type Description

user

String

The currently authenticated user.

roles

Array

Roles granted to the session.

authenticatedSites

Array

VMware Cloud Director sites that the current session is authenticated with. The site specified in the request should be present.

authenticatedSites[].site

String

A site the current session has access to.

authenticatedSites[].org

String

The VMware Cloud Director organization shortname that you authenticated as.

Example response
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 180

{
  "user" : "user1@org1",
  "roles" : [ "EVERYONE" ],
  "authenticatedSites" : [ {
    "site" : "site1",
    "org" : "org1"
  }, {
    "site" : "site2",
    "org" : "org2"
  } ]
}

Terminate the Session

DELETE /sessions invalidates an existing Cloud Service session.

Available since: v2

Required roles: One of EVERYONE, PEER_MONITORING

Request structure
DELETE /sessions HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Example request
$ curl 'https://localhost:8046/sessions' -i -X DELETE \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='
Example response
HTTP/1.1 204 No Content

Replication Policies

Replication policies are a set of rules, which can be applied to multiple organizations.

A policy consists of:

  • Minimum RPO - the minimum Recovery Point Objective (RPO) that the backing virtual data centers can handle. The lower the RPO is, the higher the infrastructure load gets.

  • Maximum number of instances - upper bound for instances per VM replication.

  • Maximum number of replications - controls whether the organizations can be used as replication source and how much incoming replications they can have.

The service has a system policy called "Default Policy". By default it does not allow organizations, associated with it, to be used as replication source / destination.

By default, all organizations without an explicitly assigned policy have the default policy assigned.
By increasing the maximum number of replications for the default policy from zero to a positive value, all organizations without an explicitly assigned policy can use replications.

Get the Details of All the Policies

GET /policies retrieves the details of all policies.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

The local or remote site where the policy is defined. When omitted, the local site is assumed.

Request structure

GET /policies HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/policies' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

[].displayName

String

User-visible policy label, useful for debugging and other UI purposes. The value is unique and case-sensitive.

[].minRpo

Number

The minimum RPO value. Incoming replications cannot be configured when the policy of the destination organization has a minimum RPO that is higher than the minimum RPO in the replication settings.

[].maxInstances

Number

When the replication has a configured max rotated instances, this field controls the maximum number of instances a VM replication can have.

[].maxPinnedInstances

Number

The maximum number of stored instances a VM replication can have.

[].maxIncoming

Number

This value controls how many incoming replications organizations can have. A negative value means unlimited number replications. 0 means the org can not be used as destination. A positive value represents upper bound. This field is ignored if allowIncomingProtections and allowIncomingMigrations are set to false.

[].allowIncomingProtections

Boolean

A boolean flag indicating whether incoming protections are allowed or not.

[].allowOutgoingProtections

Boolean

A boolean flag indicating whether outgoing protections are allowed or not.

[].allowIncomingMigrations

Boolean

A boolean flag indicating whether incoming migrations are allowed or not.

[].allowOutgoingMigrations

Boolean

A boolean flag indicating whether outgoing migrations are allowed or not.

[].onpremDataCap

Number

The maximum bit rate (in Mbit/sec) for replication data traffic from an on-premises appliance to this organization. All on-premises appliances receive the limit when pairing or re-pairing with this site and each on-premises appliance enforces this limit.

[].allowCustomSlaSettings

Boolean

Whether custom SLA settings like RPO, quescing, retention policy, and others can be set when creating or editing a replication, or the organizations are restricted to only use SLA profiles.

[].allowNotificationConfiguration

Boolean

Indicates whether organizations can configure notification settings.

[].orgs

Number

The number of organizations, which have this policy assigned.

[].id

String

Unique policy ID - for manually created policies this is a UUID.The default policy has a hard-coded ID 'default'.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 415

[ {
  "id" : "default",
  "displayName" : "Default Policy",
  "orgs" : -1,
  "minRpo" : 15,
  "maxInstances" : 24,
  "maxPinnedInstances" : 0,
  "maxIncoming" : 0,
  "allowIncomingProtections" : false,
  "allowOutgoingProtections" : false,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : true,
  "onpremDataCap" : 0,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
} ]

Get the Details of a Policy

GET /policies/{id} retrieves the details of a specific policy.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/policies/{policyId}
Parameter Description

policyId

Unique policy ID - the default policy has 'default' for ID. All other policies have UUID for ID.

Request parameters

Parameter Description

site

The local or remote site where the policy is defined. When omitted, the local site is assumed.

Request structure

GET /policies/107102e0-e03b-404e-8e17-0688c657a74b HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/policies/107102e0-e03b-404e-8e17-0688c657a74b' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

displayName

String

User-visible policy label, useful for debugging and other UI purposes. The value is unique and case-sensitive.

minRpo

Number

The minimum RPO value. Incoming replications cannot be configured when the policy of the destination organization has a minimum RPO that is higher than the minimum RPO in the replication settings.

maxInstances

Number

When the replication has a configured max rotated instances, this field controls the maximum number of instances a VM replication can have.

maxPinnedInstances

Number

The maximum number of stored instances a VM replication can have.

maxIncoming

Number

This value controls how many incoming replications organizations can have. A negative value means unlimited number replications. 0 means the org can not be used as destination. A positive value represents upper bound. This field is ignored if allowIncomingProtections and allowIncomingMigrations are set to false.

allowIncomingProtections

Boolean

A boolean flag indicating whether incoming protections are allowed or not.

allowOutgoingProtections

Boolean

A boolean flag indicating whether outgoing protections are allowed or not.

allowIncomingMigrations

Boolean

A boolean flag indicating whether incoming migrations are allowed or not.

allowOutgoingMigrations

Boolean

A boolean flag indicating whether outgoing migrations are allowed or not.

onpremDataCap

Number

The maximum bit rate (in Mbit/sec) for replication data traffic from an on-premises appliance to this organization. All on-premises appliances receive the limit when pairing or re-pairing with this site and each on-premises appliance enforces this limit.

allowCustomSlaSettings

Boolean

Whether custom SLA settings like RPO, quescing, retention policy, and others can be set when creating or editing a replication, or the organizations are restricted to only use SLA profiles.

allowNotificationConfiguration

Boolean

Indicates whether organizations can configure notification settings.

orgs

Number

The number of organizations, which have this policy assigned.

id

String

Unique policy ID - for manually created policies this is a UUID.The default policy has a hard-coded ID 'default'.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 411

{
  "id" : "default",
  "displayName" : "Default Policy",
  "orgs" : -1,
  "minRpo" : 15,
  "maxInstances" : 24,
  "maxPinnedInstances" : 0,
  "maxIncoming" : 0,
  "allowIncomingProtections" : false,
  "allowOutgoingProtections" : false,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : true,
  "onpremDataCap" : 0,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}

Get the Compliance Status of a Policy

GET /policies/{id}/status retrieves the compliance status of a specific policy.

Available since: v3.5

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters

/policies/{policyId}/status
Parameter Description

policyId

Unique policy ID - the default policy has 'default' for ID. All other policies have UUID for ID.

Request structure

GET /policies/52ce9bc4-2563-448d-b8af-9047a03ce5c2/status HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/policies/52ce9bc4-2563-448d-b8af-9047a03ce5c2/status' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

[]

Array

List of statuses for each destination organization.

[].org

String

The VMware Cloud Director destination organization.

[].configuredReplications

Number

The number of configured replications.

[].quotaViolation

Number

When the incoming VM replications quota is exceeded, this property shows by how many.

[].protectionViolation

Number

When the incoming protections are disabled, this property shows how many violate the rule.

[].migrationViolation

Number

When the incoming migrations are disabled, this property shows how many violate the rule.

[].nonRpoCompliant[]

Array

List of VM replication IDs, which have RPO, lower than the policy limit.

[].nonInstancesCompliant[]

Array

List of VM replication IDs, which have more instances than the policy limit.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 281

[ {
  "org" : "org1",
  "configuredReplications" : 2,
  "quotaViolation" : 0,
  "protectionViolation" : 0,
  "migrationViolation" : 0,
  "nonRpoCompliant" : [ "C4-ec991bd5-af9d-446a-8599-5b693842c4a3" ],
  "nonInstancesCompliant" : [ "C4-ec991bd5-af9d-446a-8599-5b693842c4a3" ]
} ]

Create a Policy

POST /policies creates a new policy, that can be assigned to organizations.

Available since: v4

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Request fields

Path Type Description

displayName

String

User-visible policy label, useful for debugging and other UI purposes. The value is unique and case-sensitive.

minRpo

Number

The minimum RPO value. Incoming replications cannot be configured when the policy of the destination organization has a minimum RPO that is higher than the minimum RPO in the replication settings.

maxInstances

Number

When the replication has a configured max rotated instances, this field controls the maximum number of instances a VM replication can have.

maxPinnedInstances

Number

The maximum number of stored instances a VM replication can have.

maxIncoming

Number

This value controls how many incoming replications organizations can have. A negative value means unlimited number replications. 0 means the org can not be used as destination. A positive value represents upper bound. This field is ignored if allowIncomingProtections and allowIncomingMigrations are set to false.

allowIncomingProtections

Boolean

A boolean flag indicating whether incoming protections are allowed or not.

allowOutgoingProtections

Boolean

A boolean flag indicating whether outgoing protections are allowed or not.

allowIncomingMigrations

Boolean

A boolean flag indicating whether incoming migrations are allowed or not.

allowOutgoingMigrations

Boolean

A boolean flag indicating whether outgoing migrations are allowed or not.

onpremDataCap

Number

The maximum bit rate (in Mbit/sec) for replication data traffic from an on-premises appliance to this organization. All on-premises appliances receive the limit when pairing or re-pairing with this site and each on-premises appliance enforces this limit.

allowCustomSlaSettings

Boolean

Whether custom SLA settings like RPO, quescing, retention policy, and others can be set when creating or editing a replication, or the organizations are restricted to only use SLA profiles.

allowNotificationConfiguration

Boolean

Indicates whether organizations can configure notification settings.

Request structure

POST /policies HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 377

{
  "displayName" : "Golden Policy",
  "minRpo" : 5,
  "maxInstances" : 24,
  "maxPinnedInstances" : 24,
  "maxIncoming" : -1,
  "allowIncomingProtections" : true,
  "allowOutgoingProtections" : false,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : false,
  "onpremDataCap" : 50,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}

Example request

$ curl 'https://localhost:8046/policies' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "displayName" : "Golden Policy",
  "minRpo" : 5,
  "maxInstances" : 24,
  "maxPinnedInstances" : 24,
  "maxIncoming" : -1,
  "allowIncomingProtections" : true,
  "allowOutgoingProtections" : false,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : false,
  "onpremDataCap" : 50,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}'

Response structure

Path Type Description

displayName

String

User-visible policy label, useful for debugging and other UI purposes. The value is unique and case-sensitive.

minRpo

Number

The minimum RPO value. Incoming replications cannot be configured when the policy of the destination organization has a minimum RPO that is higher than the minimum RPO in the replication settings.

maxInstances

Number

When the replication has a configured max rotated instances, this field controls the maximum number of instances a VM replication can have.

maxPinnedInstances

Number

The maximum number of stored instances a VM replication can have.

maxIncoming

Number

This value controls how many incoming replications organizations can have. A negative value means unlimited number replications. 0 means the org can not be used as destination. A positive value represents upper bound. This field is ignored if allowIncomingProtections and allowIncomingMigrations are set to false.

allowIncomingProtections

Boolean

A boolean flag indicating whether incoming protections are allowed or not.

allowOutgoingProtections

Boolean

A boolean flag indicating whether outgoing protections are allowed or not.

allowIncomingMigrations

Boolean

A boolean flag indicating whether incoming migrations are allowed or not.

allowOutgoingMigrations

Boolean

A boolean flag indicating whether outgoing migrations are allowed or not.

onpremDataCap

Number

The maximum bit rate (in Mbit/sec) for replication data traffic from an on-premises appliance to this organization. All on-premises appliances receive the limit when pairing or re-pairing with this site and each on-premises appliance enforces this limit.

allowCustomSlaSettings

Boolean

Whether custom SLA settings like RPO, quescing, retention policy, and others can be set when creating or editing a replication, or the organizations are restricted to only use SLA profiles.

allowNotificationConfiguration

Boolean

Indicates whether organizations can configure notification settings.

orgs

Number

The number of organizations, which have this policy assigned.

id

String

Unique policy ID - for manually created policies this is a UUID.The default policy has a hard-coded ID 'default'.

Example response

HTTP/1.1 201 Created
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 438

{
  "id" : "107102e0-e03b-404e-8e17-0688c657a74b",
  "displayName" : "Golden Policy",
  "orgs" : 5,
  "minRpo" : 5,
  "maxInstances" : 24,
  "maxPinnedInstances" : 24,
  "maxIncoming" : -1,
  "allowIncomingProtections" : true,
  "allowOutgoingProtections" : true,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : true,
  "onpremDataCap" : 50,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}

Delete a Policy

DELETE /policies/{id} deletes the specified policy when no organizations are associated with the policy.

The default policy cannot be deleted.

Available since: v3.5

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters

/policies/{policyId}
Parameter Description

policyId

The unique policy ID.

Request structure

DELETE /policies/107102e0-e03b-404e-8e17-0688c657a74b HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/policies/107102e0-e03b-404e-8e17-0688c657a74b' -i -X DELETE \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Example response

HTTP/1.1 204 No Content

Update a Policy

PUT /policies/{id} overwrites the policy properties with the provided ones.

Updating the policy configuration does not affect the ongoing replications. If there are any replications that violate the policy constraints, they have to be handled manually.

Available since: v4

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters

/policies/{policyId}
Parameter Description

policyId

The unique policy ID.

Request fields

Path Type Description

displayName

String

User-visible policy label, useful for debugging and other UI purposes. The value is unique and case-sensitive.

minRpo

Number

The minimum RPO value. Incoming replications cannot be configured when the policy of the destination organization has a minimum RPO that is higher than the minimum RPO in the replication settings.

maxInstances

Number

When the replication has a configured max rotated instances, this field controls the maximum number of instances a VM replication can have.

maxPinnedInstances

Number

The maximum number of stored instances a VM replication can have.

maxIncoming

Number

This value controls how many incoming replications organizations can have. A negative value means unlimited number replications. 0 means the org can not be used as destination. A positive value represents upper bound. This field is ignored if allowIncomingProtections and allowIncomingMigrations are set to false.

allowIncomingProtections

Boolean

A boolean flag indicating whether incoming protections are allowed or not.

allowOutgoingProtections

Boolean

A boolean flag indicating whether outgoing protections are allowed or not.

allowIncomingMigrations

Boolean

A boolean flag indicating whether incoming migrations are allowed or not.

allowOutgoingMigrations

Boolean

A boolean flag indicating whether outgoing migrations are allowed or not.

onpremDataCap

Number

The maximum bit rate (in Mbit/sec) for replication data traffic from an on-premises appliance to this organization. All on-premises appliances receive the limit when pairing or re-pairing with this site and each on-premises appliance enforces this limit.

allowCustomSlaSettings

Boolean

Whether custom SLA settings like RPO, quescing, retention policy, and others can be set when creating or editing a replication, or the organizations are restricted to only use SLA profiles.

allowNotificationConfiguration

Boolean

Indicates whether organizations can configure notification settings.

Request structure

PUT /policies/107102e0-e03b-404e-8e17-0688c657a74b HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 377

{
  "displayName" : "Golden Policy",
  "minRpo" : 5,
  "maxInstances" : 24,
  "maxPinnedInstances" : 24,
  "maxIncoming" : -1,
  "allowIncomingProtections" : true,
  "allowOutgoingProtections" : false,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : false,
  "onpremDataCap" : 50,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}

Example request

$ curl 'https://localhost:8046/policies/107102e0-e03b-404e-8e17-0688c657a74b' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "displayName" : "Golden Policy",
  "minRpo" : 5,
  "maxInstances" : 24,
  "maxPinnedInstances" : 24,
  "maxIncoming" : -1,
  "allowIncomingProtections" : true,
  "allowOutgoingProtections" : false,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : false,
  "onpremDataCap" : 50,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}'

Response structure

Path Type Description

displayName

String

User-visible policy label, useful for debugging and other UI purposes. The value is unique and case-sensitive.

minRpo

Number

The minimum RPO value. Incoming replications cannot be configured when the policy of the destination organization has a minimum RPO that is higher than the minimum RPO in the replication settings.

maxInstances

Number

When the replication has a configured max rotated instances, this field controls the maximum number of instances a VM replication can have.

maxPinnedInstances

Number

The maximum number of stored instances a VM replication can have.

maxIncoming

Number

This value controls how many incoming replications organizations can have. A negative value means unlimited number replications. 0 means the org can not be used as destination. A positive value represents upper bound. This field is ignored if allowIncomingProtections and allowIncomingMigrations are set to false.

allowIncomingProtections

Boolean

A boolean flag indicating whether incoming protections are allowed or not.

allowOutgoingProtections

Boolean

A boolean flag indicating whether outgoing protections are allowed or not.

allowIncomingMigrations

Boolean

A boolean flag indicating whether incoming migrations are allowed or not.

allowOutgoingMigrations

Boolean

A boolean flag indicating whether outgoing migrations are allowed or not.

onpremDataCap

Number

The maximum bit rate (in Mbit/sec) for replication data traffic from an on-premises appliance to this organization. All on-premises appliances receive the limit when pairing or re-pairing with this site and each on-premises appliance enforces this limit.

allowCustomSlaSettings

Boolean

Whether custom SLA settings like RPO, quescing, retention policy, and others can be set when creating or editing a replication, or the organizations are restricted to only use SLA profiles.

allowNotificationConfiguration

Boolean

Indicates whether organizations can configure notification settings.

orgs

Number

The number of organizations, which have this policy assigned.

id

String

Unique policy ID - for manually created policies this is a UUID.The default policy has a hard-coded ID 'default'.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 438

{
  "id" : "107102e0-e03b-404e-8e17-0688c657a74b",
  "displayName" : "Golden Policy",
  "orgs" : 5,
  "minRpo" : 5,
  "maxInstances" : 24,
  "maxPinnedInstances" : 24,
  "maxIncoming" : -1,
  "allowIncomingProtections" : true,
  "allowOutgoingProtections" : true,
  "allowIncomingMigrations" : true,
  "allowOutgoingMigrations" : true,
  "onpremDataCap" : 50,
  "allowCustomSlaSettings" : true,
  "allowNotificationConfiguration" : true
}

Assign a Policy to an Organization

PATCH /policies/{id}/orgs/{org} assigns the given policy to the local VMware Cloud Director organization.

All future configure and reconfigure replication requests that violate the policy constraints are rejected.

If the organization has an assigned policy, it is overwritten.
Assigning a policy does not affect the ongoing replications. If there are any replications that violate the policy constraints, they have to be handled manually.

Available since: v3.5

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Path parameters

/policies/{policyId}/orgs/{org}
Parameter Description

policyId

The unique policy ID.

org

The short name of the local VMware Cloud Director organization.

Request structure

PATCH /policies/107102e0-e03b-404e-8e17-0688c657a74b/orgs/org2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/policies/107102e0-e03b-404e-8e17-0688c657a74b/orgs/org2' -i -X PATCH \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Example response

HTTP/1.1 202 Accepted

Synchronize the Policies

POST /policies/sync assigns the default policy to all organizations that do not have an assigned policy, for example, after creating an organization.

This request also cleans mappings that are leftover, for example, after deleting an organization.

The Cloud Service automatically executes this request periodically. Use this request to update the mappings momentarily.

Available since: v3.5

Required roles: One of ADMINISTRATORS, VRADMINISTRATORS

Request structure

POST /policies/sync HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/policies/sync' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

String

The task has no result.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 445

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "sync",
    "resourceType" : "policies",
    "resourceId" : null,
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : null,
  "result" : null,
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Replications

Use the replications requests to create, manage, and monitor replications.

Start New VM Replication

POST /vm-replications starts a new replication. If the task is successfull and the VM is powered on, the VM starts syncronizing. After the initial synchronization completes, a new instance is created, that allows performing a failover.

If the VM is turned off or suspended, you must perform the initial synchronization manually, otherwise no new instances are created.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

source

Object

Source VM location and ID.

source.type

String

Type of the source. Set to 'vm'.

source.site

String

VMware Cloud Director site shortname.

source.vmId

String

Source VM ID in VMware Cloud Director.

source.excludedDisks

Array

A list of device keys of the excluded disks.

destination

Object

Destination location.

destination.type

String

Destination type. Set to 'vcloud' for this operation.

destination.site

String

VMware Cloud Director site shortname.

destination.vdc

String

The virtual data center in VMware Cloud Director in the destination site.

destination.storageProfile

String

Optional storage profile to use to determine placement of replicated files.

description

String

User-supplied description of this replication.

rpo

Number

Recovery Point Objective.

dataConnectionType

String

Lightweight Delta Protocol traffic configuration. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED]. Defaults to ENCRYPTED_COMPRESSED.

quiesced

Boolean

Whether to attempt to quiesce the Guest OS. Requires Guest Tools to be installed and running in the replicated VM. Defaults to true (quesce the Guest OS).

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

targetDiskType

String

Optional type of virtual disks created on DR site. Possible values are: [THIN, PREALLOCATED, PREALLOCATED_ZEROS]. Default value is: THIN.

initialSyncTime

Number

Replication initial sync time. If in the past, 0 or negative, the sync will start immediately. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfileId

String

ID of SLA profile to use for the settings.

Request structure

POST /vm-replications?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 656

{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vcloud",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vcloud",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3274

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "start",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Start New VM Replication with Seed

POST /vm-replications starts a new replication and an offline copy can be used as seed. The seed VM is identified by its ID in VMware Cloud Director.

To use the seed VM as offline copy, the seed VM must be powered off.
The seed VM is destroyed and only its disks are used to replicate the source data to.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

source

Object

Source VM location and ID.

source.type

String

Type of the source. Set to 'vm'.

source.site

String

VMware Cloud Director site shortname.

source.vmId

String

Source VM ID in VMware Cloud Director.

source.excludedDisks

Array

A list of device keys of the excluded disks.

destination

Object

Destination location.

destination.type

String

Destination type. Set to 'vm' for this operation.

destination.site

String

VMware Cloud Director site shortname.

destination.vdc

String

The virtual data center in VMware Cloud Director in the destination site.

destination.storageProfile

String

Optional storage profile to use to determine placement of replicated files.

destination.seedVmId

String

Destination VM ID in VMware Cloud Director, to be used as offline copy. Note: the seed VM will get deleted from VMware Cloud Director and only its disks will be used to replicate the source VM there. All Disks of the source VM should match the ones in the seed VM in order to succeed.

description

String

User-supplied description of this replication.

rpo

Number

Recovery Point Objective.

dataConnectionType

String

Lightweight Delta Protocol traffic configuration. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED]. Defaults to ENCRYPTED_COMPRESSED.

quiesced

Boolean

Whether to attempt to quiesce the Guest OS. Requires Guest Tools to be installed and running in the replicated VM. Defaults to true (quesce the Guest OS).

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

targetDiskType

String

Optional type of virtual disks created on DR site. Possible values are: [THIN, PREALLOCATED, PREALLOCATED_ZEROS]. Default value is: THIN.

initialSyncTime

Number

Replication initial sync time. If in the past, 0 or negative, the sync will start immediately. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfileId

String

ID of SLA profile to use for the settings.

Request structure

POST /vm-replications?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 709

{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vm",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*",
    "seedVmId" : "107102e0-e03b-404e-8e17-0688c657a74b"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vm",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*",
    "seedVmId" : "107102e0-e03b-404e-8e17-0688c657a74b"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3274

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "start",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Start New VM Replication from On-Premises

POST /vm-replications starts a new replication. By using source type 'vcVm' starts a VM replication from an on-premises site to a cloud site. If the task is successfull and the VM is powered on, the VM starts syncronizing. After the initial synchronization completes, a new instance is created, that allows performing a failover.

If the VM is turned off or suspended, you must perform the initial synchronization manually, otherwise no new instances are created.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

source

Object

Source VM location and ID.

source.type

String

Discriminator property, should be set to 'vcVm' in this case.

source.site

String

VMware Cloud Director site shortname.

source.vcUuid

String

The UUID of the source vCenter Server, in which the source VM is registered.

source.vmId

String

Source VM managed object ID in vCenter.

source.excludedDisks

Array

A list of device keys of the excluded disks.

destination

Object

Destination location.

destination.type

String

Destination type. Set to 'vcloud' for this operation.

destination.site

String

VMware Cloud Director site shortname.

destination.vdc

String

The virtual data center in VMware Cloud Director in the destination site.

destination.storageProfile

String

Optional storage profile to use to determine placement of replicated files.

description

String

User-supplied description of this replication.

rpo

Number

Recovery Point Objective.

dataConnectionType

String

Lightweight Delta Protocol traffic configuration. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED]. Defaults to ENCRYPTED_COMPRESSED.

quiesced

Boolean

Whether to attempt to quiesce the Guest OS. Requires Guest Tools to be installed and running in the replicated VM. Defaults to true (quesce the Guest OS).

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

targetDiskType

String

Optional type of virtual disks created on DR site. Possible values are: [THIN, PREALLOCATED, PREALLOCATED_ZEROS]. Default value is: THIN.

initialSyncTime

Number

Replication initial sync time. If in the past, 0 or negative, the sync will start immediately. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfileId

String

ID of SLA profile to use for the settings.

Request structure

POST /vm-replications?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 682

{
  "source" : {
    "type" : "vcVm",
    "site" : "site1",
    "vcUuid" : "9664de13-6150-4315-9f59-2d85eb4c302f",
    "vmId" : "vm-42",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vcloud",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "source" : {
    "type" : "vcVm",
    "site" : "site1",
    "vcUuid" : "9664de13-6150-4315-9f59-2d85eb4c302f",
    "vmId" : "vm-42",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vcloud",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3274

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "start",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Start New VM Replication with Seed from On-Premises

POST /vm-replications starts a new replication. By using source type 'vcVm' starts a VM replication from an on-premises site to a cloud site and an offline copy of the VM is used as seed. The seed VM is identified by its ID in VMware Cloud Director.

To use the seed VM as offline copy, the seed VM must be powered off.
The seed VM is destroyed and only its disks are used to replicate the source data to.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

source

Object

Source VM location and ID.

source.type

String

Discriminator property, should be set to 'vcVm' in this case.

source.site

String

VMware Cloud Director site shortname.

source.vcUuid

String

The UUID of the source vCenter Server, in which the source VM is registered.

source.vmId

String

Source VM managed object ID in vCenter.

source.excludedDisks

Array

A list of device keys of the excluded disks.

destination

Object

Destination location.

destination.type

String

Destination type. Set to 'vm' for this operation.

destination.site

String

VMware Cloud Director site shortname.

destination.vdc

String

The virtual data center in VMware Cloud Director in the destination site.

destination.storageProfile

String

Optional storage profile to use to determine placement of replicated files.

destination.seedVmId

String

Destination VM ID in VMware Cloud Director, to be used as offline copy. Note: the seed VM will get deleted from VMware Cloud Director and only its disks will be used to replicate the source VM there. All Disks of the source VM should match the ones in the seed VM in order to succeed.

description

String

User-supplied description of this replication.

rpo

Number

Recovery Point Objective.

dataConnectionType

String

Lightweight Delta Protocol traffic configuration. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED]. Defaults to ENCRYPTED_COMPRESSED.

quiesced

Boolean

Whether to attempt to quiesce the Guest OS. Requires Guest Tools to be installed and running in the replicated VM. Defaults to true (quesce the Guest OS).

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

targetDiskType

String

Optional type of virtual disks created on DR site. Possible values are: [THIN, PREALLOCATED, PREALLOCATED_ZEROS]. Default value is: THIN.

initialSyncTime

Number

Replication initial sync time. If in the past, 0 or negative, the sync will start immediately. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfileId

String

ID of SLA profile to use for the settings.

Request structure

POST /vm-replications?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 735

{
  "source" : {
    "type" : "vcVm",
    "site" : "site1",
    "vcUuid" : "9664de13-6150-4315-9f59-2d85eb4c302f",
    "vmId" : "vm-42",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vm",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*",
    "seedVmId" : "107102e0-e03b-404e-8e17-0688c657a74b"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "source" : {
    "type" : "vcVm",
    "site" : "site1",
    "vcUuid" : "9664de13-6150-4315-9f59-2d85eb4c302f",
    "vmId" : "vm-42",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vm",
    "site" : "site2",
    "vdc" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "storageProfile" : "*",
    "seedVmId" : "107102e0-e03b-404e-8e17-0688c657a74b"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3274

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "start",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Start New VM Replication to On-Premises

POST /vm-replications starts a new replication. By using source type 'vm' and destination type 'vc' starts a VM replication from a cloud site to an on-premises site.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

source

Object

Source VM location and ID.

source.type

String

Type of the source. Set to 'vm'.

source.site

String

VMware Cloud Director site shortname.

source.vmId

String

Source VM ID in VMware Cloud Director.

source.excludedDisks

Array

A list of device keys of the excluded disks.

destination

Object

Destination location.

destination.type

String

Destination type. Set to 'vc' for this operation.

destination.site

String

The shortname of the on-premises site.

description

String

User-supplied description of this replication.

rpo

Number

Recovery Point Objective.

dataConnectionType

String

Lightweight Delta Protocol traffic configuration. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED]. Defaults to ENCRYPTED_COMPRESSED.

quiesced

Boolean

Whether to attempt to quiesce the Guest OS. Requires Guest Tools to be installed and running in the replicated VM. Defaults to true (quesce the Guest OS).

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

targetDiskType

String

Optional type of virtual disks created on DR site. Possible values are: [THIN, PREALLOCATED, PREALLOCATED_ZEROS]. Default value is: THIN.

initialSyncTime

Number

Replication initial sync time. If in the past, 0 or negative, the sync will start immediately. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfileId

String

ID of SLA profile to use for the settings.

Request structure

POST /vm-replications HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 574

{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vc",
    "site" : "onprem1"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vc",
    "site" : "onprem1"
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3274

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "start",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Start New VM Replication with Seed to On-Premises

POST /vm-replications starts a new replication. By using source type 'vm' and destination type 'vc' starts a VM replication from a cloud site to an on-premises site and an offline copy of the VM is used as seed. The seed VM is identified by its managed object ID in vCenter Server.

To use the seed VM as offline copy, the seed VM must be powered off.
The seed VM is destroyed and only its disks are used to replicate the source data to.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

source

Object

Source VM location and ID.

source.type

String

Type of the source. Set to 'vm'.

source.site

String

VMware Cloud Director site shortname.

source.vmId

String

Source VM ID in VMware Cloud Director.

source.excludedDisks

Array

A list of device keys of the excluded disks.

destination

Object

Destination location.

destination.type

String

Destination type. Set to 'vcVapp' for this operation.

destination.site

String

The shortname of the on-premises site.

destination.seedVm

Object

Ids of the VMs to use as offline copy. Note: the VMs will be deleted, and only their disks will be used as seed.

destination.seedVm.vcId

String

ID of the target VC.

destination.seedVm.moId

String

MOREF of the target VM.

description

String

User-supplied description of this replication.

rpo

Number

Recovery Point Objective.

dataConnectionType

String

Lightweight Delta Protocol traffic configuration. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED]. Defaults to ENCRYPTED_COMPRESSED.

quiesced

Boolean

Whether to attempt to quiesce the Guest OS. Requires Guest Tools to be installed and running in the replicated VM. Defaults to true (quesce the Guest OS).

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

targetDiskType

String

Optional type of virtual disks created on DR site. Possible values are: [THIN, PREALLOCATED, PREALLOCATED_ZEROS]. Default value is: THIN.

initialSyncTime

Number

Replication initial sync time. If in the past, 0 or negative, the sync will start immediately. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfileId

String

ID of SLA profile to use for the settings.

Request structure

POST /vm-replications HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 642

{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vcVm",
    "site" : "site",
    "seedVm" : {
      "vcId" : "vcId",
      "moId" : "moId"
    }
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "source" : {
    "type" : "vm",
    "site" : "site1",
    "vmId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "excludedDisks" : [ 1000 ]
  },
  "destination" : {
    "type" : "vcVm",
    "site" : "site",
    "seedVm" : {
      "vcId" : "vcId",
      "moId" : "moId"
    }
  },
  "description" : "A Protected Workload",
  "rpo" : 5,
  "dataConnectionType" : "ENCRYPTED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 3,
      "distance" : 60
    } ]
  },
  "targetDiskType" : "THIN",
  "initialSyncTime" : 0,
  "isMigration" : false,
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3274

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "start",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : null
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Get the VM Replications

GET /vm-replications lists the configured VM-level replications.

Available since: v4

Required roles: One of EVERYONE, PEER_MONITORING

Request parameters

Parameter Description

owner

When present, returned replications are filtered by replication owner. Filtering option available only to admins.

sourceSite

When present, returned replications will be source site short name. Local site filtering is not supported.

sourceSiteType

When present, returned replications are filtered by source site type (e.g. vcloud/vcenter).

sourceVdcId

When present, returned replications are filtered by source vDC ID.

sourceVdcName

When present, returned replications are filtered by source vDC name.

sourceOrg

When present, returned replications are filtered by VMware Cloud Director source org.

sourceVimServerUuid

When present, the administrators can filter by source vCenter Server instance ID.

vmId

When present, returned replications are filtered by source source VM ID.

vmName

When present, returned replications are filtered by Virtual Machine name. The VM name must contain the provided value.

storageProfile

When present, returned replications will storage profile.

destinationOrg

When present, returned replications are filtered by destination org.

destinationVdcId

When present, returned replications are filtered by destination vDC ID.

destinationVdcName

When present, returned replications are filtered by destination vDC name.

destinationSiteType

When present, returned replications are filtered by destination site type (e.g. vcloud/vcenter).

recoveredVmId

When present, returned replications are filtered by destination recovered vAppId.

vimServerInstanceUuid

When present, admins can filter by vCenter instance ID.

datastoreMoref

When present, admins can filter by datastore moid. vimServerInstanceUuid is required.

isMigration

When present, returned replications are filtered by replication type: migration or protection.

slaProfileId

When present, the SLA Profile to use instead of the custom rpo/dataConnectionType/retentionPolicy settings.

slaProfileDisplayName

When present, the displayName of the SLA Profile used by a replication.

lastUpdatedBefore

When present, less-than filtering will be applied.

lastUpdatedAfter

When present, greater-than filtering will be applied.

overallHealth

When present, returned replications are filtered by their overall health.

dataConnectionState

When present, returned replications are filtered by their data connection state.

ids

When present, returned replications are filtered by source VMware Cloud Director org shortname. Comma-separated Cloud replication ids are expected.

sort

An optional list of comma-separated fields, used to sort the result.The default sorting direction is ascending. When a field finishes with a hyphen, the direction for this field will be descending. This allows chaining e.g. col,col2-,col3 will result in sorting by col (asc), then by col2 (desc) and finally by col3 (asc). Supported fields: [vmName, sourceSite, sourceOrg, sourceVdcName, site, destinationOrg, destinationVdcName, owner, lastUpdated]. If this field is omitted, the result is sorted by start time in descending order.

offset

Number of items skipped before retrieving the items. By default, 0 if skipped.

limit

Query limit - maximum number of items this query should retrieve. When omitted or higher than the server’s limits, defaults to 100.

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

GET /vm-replications?vmName=my&sourceSite=site1&sourceOrg=org1&site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications?vmName=my&sourceSite=site1&sourceOrg=org1&site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

total

Number

The total number of items in the database of the Cloud Service.

offset

Number

Number of items skipped before retrieving the items.

limit

Number

The maximum number of items that this query retrieves.

items

Array

A list of VM-level replications.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 2837

{
  "items" : [ {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  } ],
  "total" : 1,
  "offset" : 0,
  "limit" : 100
}

Get the VM Replications for an SLA Profile

GET /vm-replications?slaProfileDisplayName=<sla-profile-display-name> lists all configured VM-level replications that are all assigned a given SLA Profile.

Available since: v4

Required roles: One of EVERYONE, PEER_MONITORING

Request parameters

Parameter Description

owner

When present, returned replications are filtered by replication owner. Filtering option available only to admins.

sourceSite

When present, returned replications will be source site short name. Local site filtering is not supported.

sourceSiteType

When present, returned replications are filtered by source site type (e.g. vcloud/vcenter).

sourceVdcId

When present, returned replications are filtered by source vDC ID.

sourceVdcName

When present, returned replications are filtered by source vDC name.

sourceOrg

When present, returned replications are filtered by VMware Cloud Director source org.

sourceVimServerUuid

When present, the administrators can filter by source vCenter Server instance ID.

vmId

When present, returned replications are filtered by source source VM ID.

vmName

When present, returned replications are filtered by Virtual Machine name. The VM name must contain the provided value.

storageProfile

When present, returned replications will storage profile.

destinationOrg

When present, returned replications are filtered by destination org.

destinationVdcId

When present, returned replications are filtered by destination vDC ID.

destinationVdcName

When present, returned replications are filtered by destination vDC name.

destinationSiteType

When present, returned replications are filtered by destination site type (e.g. vcloud/vcenter).

recoveredVmId

When present, returned replications are filtered by destination recovered vAppId.

vimServerInstanceUuid

When present, admins can filter by vCenter instance ID.

datastoreMoref

When present, admins can filter by datastore moid. vimServerInstanceUuid is required.

isMigration

When present, returned replications are filtered by replication type: migration or protection.

slaProfileId

When present, the SLA Profile to use instead of the custom rpo/dataConnectionType/retentionPolicy settings.

slaProfileDisplayName

When present, the displayName of the SLA Profile used by a replication.

lastUpdatedBefore

When present, less-than filtering will be applied.

lastUpdatedAfter

When present, greater-than filtering will be applied.

overallHealth

When present, returned replications are filtered by their overall health.

dataConnectionState

When present, returned replications are filtered by their data connection state.

ids

When present, returned replications are filtered by source VMware Cloud Director org shortname. Comma-separated Cloud replication ids are expected.

sort

An optional list of comma-separated fields, used to sort the result.The default sorting direction is ascending. When a field finishes with a hyphen, the direction for this field will be descending. This allows chaining e.g. col,col2-,col3 will result in sorting by col (asc), then by col2 (desc) and finally by col3 (asc). Supported fields: [vmName, sourceSite, sourceOrg, sourceVdcName, site, destinationOrg, destinationVdcName, owner, lastUpdated]. If this field is omitted, the result is sorted by start time in descending order.

offset

Number of items skipped before retrieving the items. By default, 0 if skipped.

limit

Query limit - maximum number of items this query should retrieve. When omitted or higher than the server’s limits, defaults to 100.

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

GET /vm-replications?slaProfileDisplayName=Gold HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications?slaProfileDisplayName=Gold' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

total

Number

The total number of items in the database of the Cloud Service.

offset

Number

Number of items skipped before retrieving the items.

limit

Number

The maximum number of items that this query retrieves.

items

Array

A list of VM-level replications.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 2816

{
  "items" : [ {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : null,
    "vmDescription" : null,
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  } ],
  "total" : 1,
  "offset" : 0,
  "limit" : 100
}

Get the Details of a VM Replication

GET /vm-replications/{replicationId} returns the details for an individual VM replication.

Available since: v3.5

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/vm-replications/{replicationId}
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

GET /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3?site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

The Cloud VM-level replication ID.

vmId

String

VMware Cloud Director VM ID.

vmName

String

VMware Cloud Director VM name.

storageProfile

String

Destination storage profile.

storageProfileName

String

Destination storage profile display name.

vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

vimLocation.vimServer

String

The vCenter Server instance.

vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

isPaused

Boolean

Indicates whether the underlying VM replication is paused.

settings

Object

VM-level replication settings.

startupInfo

Object

VMware Cloud Director startupInfo for the VM.

metadata

Object

VMware Cloud Director metadata for the VM.

sourceState

Object

Source state information.

destinationState

Object

Destination state information.

dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

overallHealth

String

Representation of the replication health suitable for UI purposes.

lastUpdated

Number

The startTime of the latest task associated with this VM replication.

isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

computerName

String

VMware Cloud Director VM computer name.

vmDescription

String

VMware Cloud Director VM description.

isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

slaProfile

Object

The SLA profile applied to this replication.

slaProfile.id

String

The ID of the SLA profile applied to this replication.

slaProfile.displayName

String

The name of the SLA profile applied to this replication.

vappReplicationId

String

ID of the corresponding vApp replication.

owner

String

The ID of the user that owns the replication.

source

Object

Source vApp info.

source.site

String

The shortname of the site that holds the source vApp.

source.org

String

The shortname of the org the source vApp belongs to.

source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

source.vappId

String

Source vApp VMware Cloud Director ID.

source.vappName

String

Source vApp display name.

destination

Object

Replication destination info.

destination.site

String

The shortname of the destination site.

destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

destination.org

String

Destination organization in VMware Cloud Director.

destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 2575

{
  "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
  "owner" : "org1@site1",
  "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
  "vmName" : "my vm 1",
  "source" : {
    "site" : "site1",
    "org" : "org1",
    "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
    "vdcName" : "Virtual DC 1",
    "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
    "vappName" : "my vApp"
  },
  "destination" : {
    "site" : "site2",
    "org" : "s2org",
    "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
    "vdcName" : "Virtual DC 2",
    "recoveredVappId" : "vapp-1"
  },
  "storageProfile" : "*",
  "storageProfileName" : "Default",
  "vimLocation" : {
    "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
    "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
    "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
    "datastoreMoref" : "datastore-12",
    "datastoreName" : "testDatastore"
  },
  "isPaused" : false,
  "settings" : {
    "description" : "A vm replication",
    "rpo" : 5,
    "dataConnectionType" : "ENCRYPTED_COMPRESSED",
    "quiesced" : true,
    "retentionPolicy" : {
      "rules" : [ {
        "numberOfInstances" : 3,
        "distance" : 60
      } ]
    },
    "initialSyncTime" : 4102444800,
    "excludedDiskKeys" : [ ]
  },
  "startupInfo" : {
    "order" : 0,
    "startAction" : "powerOn",
    "startDelay" : 0,
    "stopAction" : "powerOff",
    "stopDelay" : 0
  },
  "metadata" : {
    "val1" : {
      "key" : "val1",
      "access" : "READONLY",
      "type" : "STRING",
      "value" : "Hello, world!"
    }
  },
  "sourceState" : {
    "state" : "syncing",
    "progress" : {
      "progress" : 50,
      "bytesTransferred" : 2048,
      "bytesToTransfer" : 4096,
      "checksumTotalBytes" : 4096,
      "checksumComparedBytes" : 4096
    },
    "stateAge" : 0
  },
  "destinationState" : {
    "currentRpoViolation" : -1,
    "latestInstance" : null,
    "state" : "fullsync",
    "recoveryInfo" : {
      "vAppId" : null,
      "vcdVmId" : null,
      "type" : "vcd",
      "recoveryState" : "NOT_STARTED"
    },
    "lastError" : null,
    "stateAge" : 0,
    "spaceRequirement" : 0,
    "isMovingReplica" : false
  },
  "dataConnectionState" : "OK",
  "overallHealth" : "GREEN",
  "lastUpdated" : 618094800000,
  "isReversed" : false,
  "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
  "computerName" : "computerName",
  "vmDescription" : "vmDescription",
  "isMigration" : false,
  "slaProfile" : {
    "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
    "displayName" : "Gold"
  }
}

Get the Instances of a VM Replication

GET /vm-replications/{replicationId}/instances lists the replication instances for an individual VM-level replication.

Available since: v2

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/vm-replications/{replicationId}/instances
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

GET /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/instances?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/instances?site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

[]

Array

List of replication instances.

[].key

String

The identifier of the replication instance.

[].sequenceNumber

Number

Sequence number of the replication instance in HBR server.

[].isPinned

Boolean

Represents if the instance is pinned or not (not affected by retention policy).

[].timestamp

Number

Timestamp of the replication instance in HBR server. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

[].transferBytes

Number

Amount of data transferred to form the replication instance.

[].transferSeconds

Number

Time taken to transfer the data for the replication instance.

[].quiescedType

String

Type of quiescing mode used for the replication instance.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 236

[ {
  "key" : "replica-52f3e775-a8fa-13e3-e9be-39264ed2dfe2",
  "sequenceNumber" : 11,
  "timestamp" : 1469701818743,
  "transferBytes" : 512000,
  "transferSeconds" : 4,
  "quiescedType" : "fileSystemQuiesced",
  "isPinned" : false
} ]

Get the Details of a VM Replication Instance

GET /vm-replications/{replicationId}/instances/{instanceId} returns the details of a replication instance for an individual VM-level replication.

Available since: v3.5

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/vm-replications/{replicationId}/instances/{instanceId}
Parameter Description

replicationId

Cloud VM-level replication identifier.

instanceId

Instance key.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

GET /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/instances/replica-52f3e775-a8fa-13e3-e9be-39264ed2dfe2?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/instances/replica-52f3e775-a8fa-13e3-e9be-39264ed2dfe2?site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

key

String

The identifier of the replication instance.

sequenceNumber

Number

Sequence number of the replication instance in HBR server.

isPinned

Boolean

Represents if the instance is pinned or not (not affected by retention policy).

timestamp

Number

Timestamp of the replication instance in HBR server. The time is specified as the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.

transferBytes

Number

Amount of data transferred to form the replication instance.

transferSeconds

Number

Time taken to transfer the data for the replication instance.

quiescedType

String

Type of quiescing mode used for the replication instance.

disksInfo

Array

An array of disks included in the instance.

disksInfo[].diskKey

Number

Disk device key.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 280

{
  "key" : "replica-52f3e775-a8fa-13e3-e9be-39264ed2dfe2",
  "sequenceNumber" : 11,
  "timestamp" : 1469701818743,
  "transferBytes" : 512000,
  "transferSeconds" : 4,
  "quiescedType" : "fileSystemQuiesced",
  "disksInfo" : [ {
    "diskKey" : 2000
  } ],
  "isPinned" : false
}

Get the Historical Traffic Statistics of a VM Replication

GET /vm-replications/{replicationId}/traffic returns the historical replication traffic statistics for a VM replication.

Available since: v4

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/vm-replications/{replicationId}/traffic
Parameter Description

replicationId

The VM replication ID.

Request parameters

Parameter Description

interval

The desired interval between the samples. Defaults to 'HOUR'. One of: [FIVE_MINUTES, HOUR, DAY].

start

The timestamp (in msec) of the historical moment from which samples are retrieved. By default, 24 hours ago.

end

The timestamp (in msec) of the moment up to which samples are retrieved. By default, 'now'.

Request structure

GET /vm-replications/C4-09b2917c-bbe9-4693-ae3f-95b43a94b244/traffic?interval=HOUR&start=1563451200000&end=1563458400000 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-09b2917c-bbe9-4693-ae3f-95b43a94b244/traffic?interval=HOUR&start=1563451200000&end=1563458400000' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

label

String

The object for which historic data is collected.

interval

String

The interval between the samples. One of: [FIVE_MINUTES, HOUR, DAY].

start

Number

The timestamp (in msec) of the historical moment from which samples are retrieved.

end

Number

The timestamp (in msec) of the moment up to which samples are retrieved.

samples

Array

The samples.

samples[].timestamp

Number

The timestamp (in msec) of the moment when the sample is collected.

samples[].bytes

Number

The value of the sample at that moment.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 336

{
  "label" : "C4-09b2917c-bbe9-4693-ae3f-95b43a94b244",
  "interval" : "HOUR",
  "start" : 1563451200000,
  "end" : 1563458400000,
  "samples" : [ {
    "timestamp" : 1563451200000,
    "bytes" : 27950.0
  }, {
    "timestamp" : 1563454800000,
    "bytes" : 54023.0
  }, {
    "timestamp" : 1563458400000,
    "bytes" : 52236.0
  } ]
}

Get the Historical Disk Usage Statistics of a VM Replication

GET /vm-replications/{replicationId}/disk-usage returns the historic replication disk isage statistics for a VM replication.

Available since: v4

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/vm-replications/{replicationId}/disk-usage
Parameter Description

replicationId

The VM replication ID.

Request parameters

Parameter Description

interval

The desired interval between the samples. Defaults to 'HOUR'. One of: [FIVE_MINUTES, HOUR, DAY].

start

The timestamp (in msec) of the historical moment from which samples are retrieved. By default, 24 hours ago.

end

The timestamp (in msec) of the moment up to which samples are retrieved. By default, 'now'.

Request structure

GET /vm-replications/C4-09b2917c-bbe9-4693-ae3f-95b43a94b244/disk-usage?interval=HOUR&start=1563451200000&end=1563458400000 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-09b2917c-bbe9-4693-ae3f-95b43a94b244/disk-usage?interval=HOUR&start=1563451200000&end=1563458400000' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

label

String

The object for which historic data is collected.

interval

String

The interval between the samples. One of: [FIVE_MINUTES, HOUR, DAY].

start

Number

The timestamp (in msec) of the historical moment from which samples are retrieved.

end

Number

The timestamp (in msec) of the moment up to which samples are retrieved.

samples

Array

The samples.

samples[].timestamp

Number

The timestamp (in msec) of the moment when the sample is collected.

samples[].bytes

Number

The value of the sample at that moment.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 336

{
  "label" : "C4-09b2917c-bbe9-4693-ae3f-95b43a94b244",
  "interval" : "HOUR",
  "start" : 1563451200000,
  "end" : 1563458400000,
  "samples" : [ {
    "timestamp" : 1563451200000,
    "bytes" : 27950.0
  }, {
    "timestamp" : 1563454800000,
    "bytes" : 54023.0
  }, {
    "timestamp" : 1563458400000,
    "bytes" : 52236.0
  } ]
}

Get the Hardware Information of a Replicated VM

GET /vm-replications/{replicationId}/virtual-hardware returns basic hardware information about the replicated VM.

Available since: v4

Required roles: One of EVERYONE, PEER_MONITORING

Path parameters

/vm-replications/{replicationId}/virtual-hardware
Parameter Description

replicationId

ID of the replication.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

GET /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/virtual-hardware?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/virtual-hardware?site=site2' -i -X GET \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

cpus

Number

Number of virtual CPUs in the VM. When not available, returns -1.

coresPerSocket

Number

Number of virtual CPU cores per socket. When not available, returns 'null'.

memoryMB

Number

VM memory (in megabytes). When not available, returns -1.

storageMB

Number

The sum (in megabytes) of the capacities of each source disk being replicated. When not available, returns 'null'.

Example response

HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 84

{
  "cpus" : 4,
  "coresPerSocket" : 1,
  "memoryMB" : 8192,
  "storageMB" : 10240
}

Stop a VM Replication

DELETE /vm-replications/{replicationId} stops a VM replication and removes all disks associated with the replication.

Available since: v2

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

DELETE /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3?site=site2' -i -X DELETE \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

String

None.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 492

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "stop",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : null,
  "result" : null,
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Synchronize a VM Replication

POST /vm-replications/{replicationId}/sync synchronizes a VM replication.

Available since: v2

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/sync
Parameter Description

replicationId

ID of the replication to pause.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/sync?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Type: application/x-www-form-urlencoded

site=site2

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/sync?site=site2' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

Up-to-date Cloud VM replication info.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3278

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "sync",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Pause a VM Replication

POST /vm-replications/{replicationId}/pause pauses the replication process if it is running.

If the replication process is in an incompatible state, the request fails. If the replication process is already paused, the request succeeds without performing anything.

Until the replication is resumed, the following operations are disabled:

  • automatic sync

  • manual sync

  • test failover with explicit sync

  • planned migration

Available since: v2

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/pause
Parameter Description

replicationId

ID of the replication to pause.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/pause?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Type: application/x-www-form-urlencoded

site=site2

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/pause?site=site2' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

Up-to-date Cloud VM replication info.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3279

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "pause",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Resume a VM Replication

POST /vm-replications/{replicationId}/resume resumes a VM replication.

Available since: v2

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/resume
Parameter Description

replicationId

ID of the replication to resume.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/resume?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Type: application/x-www-form-urlencoded

site=site2

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/resume?site=site2' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

Up-to-date Cloud VM replication info.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3280

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "resume",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

A VM Replication Failover

POST /vm-replications/{replicationId}/failover fails over the VM to the destination site.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/failover
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

type

String

Discriminator property, should be set to 'vcloud' in this case.

instanceId

String

Optional ID of a rotated instance to recover to. By default the latest instance is used.

consolidate

Boolean

Optional parameter to specify whether rotated instances should be consolidated or nothing should happen in the recovered VM. Defaults to false.

powerOn

Boolean

Whether or not the recovered VM should be powered on.

vAppNetworkSettings

Object

Network settings for replication vApp result due to failover/migrate or test failover.

vAppNetworkSettings.networkMappings[]

Array

C2C - If vApp has networks connected to OrgVdcNetwork, the mapping specifies which is the corresponding destination OrgVdcNetwork to use (if any).

vAppNetworkSettings.networkMappings[].sourceNetworkName

String

Name of the vApp network at the source.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork

Object

When present, the source vApp network is isolated one.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork.id

String

UUID of the source org vDC network.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork.name

String

Name of the source org vDC network.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork

Object

When present, the destination vApp network is isolated one.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork.id

String

UUID of the destination org vDC network.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork.name

String

Name of the destination org vDC network.

vAppNetworkSettings.bridgeOrgVdcNetworks[].id

String

OrgVdc Networks which the vApp to bridge to (if it hasn’t already) - ID.

vAppNetworkSettings.bridgeOrgVdcNetworks[].name

String

OrgVdc Networks which the vApp to bridge to (if it hasn’t already) - name.

vAppNetworkSettings.copySourceNetworks

Boolean

C2C - copy source networks.

vAppNetworkSettings.bulkConnectVmNics

Boolean

Shortcut option to connect all VM NICs to single orgVdcNetwork.

vmNetworkSettings

Object

Network Settings for Virtual Machine.

vmNetworkSettings.primaryNicIndex

Number

Primary NIC index.

vmNetworkSettings.nics[].nicIndex

Number

Index of the NIC starting from 0 in a VM.

vmNetworkSettings.nics[].isConnected

Boolean

Indicates whether the NIC should be connected.

vmNetworkSettings.nics[].resetMacAddress

Boolean

Indicates whether the NIC MAC address should be reset (regenerated) or kept as it is.

vmNetworkSettings.nics[].network

String

The name of the network to which the NIC is attached.

vmNetworkSettings.nics[].ipAddress

String

In case MANUAL IpAddressAllocationMode (below) is selected, then this holds the IP address of the NIC.

vmNetworkSettings.nics[].ipAddressAllocationMode

String

Ip Address allocation mode. Can be one of POOL, DHCP, MANUAL, NONE.

vmNetworkSettings.nics[].externalIpAddress

String

If the network that the NIC is connected to has NAT or port mapping, the external address is populated in this element.

vmNetworkSettings.nics[].networkAdapterType

String

NIC Adapter type.

vmNetworkSettings.nics[].needsCustomization

Boolean

Flag to signify if the NIC needs customization.

vmNetworkSettings.nics[].macAddress

String

The MAC address of the NIC.

vmNetworkSettings.copySourceNicSettings

Boolean

Indicates whether the source Vm NIC settings should be copied to the recovered VM.

vmNetworkSettings.computerName

String

Optionally provide computer name.

vmNetworkSettings.enableGuestCustomization

Boolean

Optionally provide whether to enable guest customization.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 1113

{
  "type" : "vcloud",
  "powerOn" : false,
  "consolidate" : false,
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "vAppNetworkSettings" : {
    "networkMappings" : [ {
      "sourceNetworkName" : "sourceNetworkName",
      "sourceOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      },
      "destinationOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      }
    } ],
    "copySourceNetworks" : false,
    "bridgeOrgVdcNetworks" : [ {
      "id" : "id",
      "name" : "name"
    } ],
    "bulkConnectVmNics" : true
  },
  "vmNetworkSettings" : {
    "primaryNicIndex" : 0,
    "nics" : [ {
      "nicIndex" : 0,
      "isConnected" : true,
      "resetMacAddress" : true,
      "network" : "orgVdcNetwork1",
      "ipAddress" : "192.168.0.101",
      "ipAddressAllocationMode" : "DHCP",
      "externalIpAddress" : "10.72.112.4",
      "networkAdapterType" : "type1",
      "needsCustomization" : false,
      "macAddress" : "00:50:56:a9:0c:12"
    } ],
    "copySourceNicSettings" : true,
    "computerName" : "testPc",
    "enableGuestCustomization" : true
  }
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "vcloud",
  "powerOn" : false,
  "consolidate" : false,
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "vAppNetworkSettings" : {
    "networkMappings" : [ {
      "sourceNetworkName" : "sourceNetworkName",
      "sourceOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      },
      "destinationOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      }
    } ],
    "copySourceNetworks" : false,
    "bridgeOrgVdcNetworks" : [ {
      "id" : "id",
      "name" : "name"
    } ],
    "bulkConnectVmNics" : true
  },
  "vmNetworkSettings" : {
    "primaryNicIndex" : 0,
    "nics" : [ {
      "nicIndex" : 0,
      "isConnected" : true,
      "resetMacAddress" : true,
      "network" : "orgVdcNetwork1",
      "ipAddress" : "192.168.0.101",
      "ipAddressAllocationMode" : "DHCP",
      "externalIpAddress" : "10.72.112.4",
      "networkAdapterType" : "type1",
      "needsCustomization" : false,
      "macAddress" : "00:50:56:a9:0c:12"
    } ],
    "copySourceNicSettings" : true,
    "computerName" : "testPc",
    "enableGuestCustomization" : true
  }
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3347

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "failover",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
        "vcdVmId" : "9664de13-6150-4315-9f59-2d85eb4c302f",
        "type" : "vcd",
        "recoveryState" : "COMPLETE"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

A VM Replication Failover to On-Premises

POST /vm-replications/{replicationId}/failover fails over a cloud VM to the destination on-premises site.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/failover
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

type

String

Discriminator property, should be set to 'vcenter' in this case.

instanceId

String

Optional ID of a rotated instance to recover to. By default the latest instance is used.

snapshotOptions

String

Optional parameter to specify whether the existing preceding rotated instances should be exposed as snapshots, whether the rotated instances should be consolidated or nothing should happen in the recovered VM.Can be [DO_NOTHING, EXPOSE_PITS, CONSOLIDATE]. Defaults to EXPOSE_PITS.

powerOn

Boolean

Whether or not the recovered VM should be powered on.

customVirtualHardware

Object

Specifies hw changes to be performed on the recovered VM. This or any of the hw changes are optional.

customVirtualHardware.numCpus

Number

Number of vCPUs of the recovered VM. If not specified it will be the same as the source VM.

customVirtualHardware.numCoresPerSocket

Number

Number of cores per socket. If not specified it will be the same as the source VM.

customVirtualHardware.memoryInMB

Number

Memory in MB. If not specified it will be the same as the source VM.

customVirtualHardware.macAddressPolicy

String

Whether to change the MAC addresses of all network devices. If unset no changes will be performed. If the recovered VM hits instance uuid collision new MAC addresses will be generated by vCenter. Valid values are [DEFAULT, GENERATE_NEW].

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 281

{
  "type" : "vcenter",
  "powerOn" : true,
  "snapshotOptions" : "EXPOSE_PITS",
  "customVirtualHardware" : {
    "numCpus" : 2,
    "numCoresPerSocket" : 4,
    "memoryInMB" : 2048,
    "macAddressPolicy" : "DEFAULT"
  },
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "vcenter",
  "powerOn" : true,
  "snapshotOptions" : "EXPOSE_PITS",
  "customVirtualHardware" : {
    "numCpus" : 2,
    "numCoresPerSocket" : 4,
    "memoryInMB" : 2048,
    "macAddressPolicy" : "DEFAULT"
  },
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3347

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "failover",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
        "vcdVmId" : "9664de13-6150-4315-9f59-2d85eb4c302f",
        "type" : "vcd",
        "recoveryState" : "COMPLETE"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Test a VM Replication Failover

POST /vm-replications/{replicationId}/failover-test tests the VM failover to the destination site.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/failover-test
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

type

String

Discriminator property, should be set to 'vcloud' in this case.

instanceId

String

Optional ID of a rotated instance to recover to. By default the latest instance is used. Cannot be used together with the 'sync' parameter set to true.

sync

Boolean

Whether automatic synchronization should be performed before the failover test. Cannot be set to 'true' if the 'instanceId' parameter is populated.

powerOn

Boolean

Whether or not the recovered VM should be powered on.

vAppNetworkSettings

Object

Network settings for replication vApp result due to failover/migrate or test failover.

vAppNetworkSettings.networkMappings[]

Array

C2C - If vApp has networks connected to OrgVdcNetwork, the mapping specifies which is the corresponding destination OrgVdcNetwork to use (if any).

vAppNetworkSettings.networkMappings[].sourceNetworkName

String

Name of the vApp network at the source.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork

Object

When present, the source vApp network is isolated one.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork.id

String

UUID of the source org vDC network.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork.name

String

Name of the source org vDC network.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork

Object

When present, the destination vApp network is isolated one.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork.id

String

UUID of the destination org vDC network.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork.name

String

Name of the destination org vDC network.

vAppNetworkSettings.bridgeOrgVdcNetworks[].id

String

OrgVdc Networks which the vApp to bridge to (if it hasn’t already) - ID.

vAppNetworkSettings.bridgeOrgVdcNetworks[].name

String

OrgVdc Networks which the vApp to bridge to (if it hasn’t already) - name.

vAppNetworkSettings.copySourceNetworks

Boolean

C2C - copy source networks.

vAppNetworkSettings.bulkConnectVmNics

Boolean

Shortcut option to connect all VM NICs to single orgVdcNetwork.

vmNetworkSettings

Object

Network Settings for Virtual Machine.

vmNetworkSettings.primaryNicIndex

Number

Primary NIC index.

vmNetworkSettings.nics[].nicIndex

Number

Index of the NIC starting from 0 in a VM.

vmNetworkSettings.nics[].isConnected

Boolean

Indicates whether the NIC should be connected.

vmNetworkSettings.nics[].resetMacAddress

Boolean

Indicates whether the NIC MAC address should be reset (regenerated) or kept as it is.

vmNetworkSettings.nics[].network

String

The name of the network to which the NIC is attached.

vmNetworkSettings.nics[].ipAddress

String

In case MANUAL IpAddressAllocationMode (below) is selected, then this holds the IP address of the NIC.

vmNetworkSettings.nics[].ipAddressAllocationMode

String

Ip Address allocation mode. Can be one of POOL, DHCP, MANUAL, NONE.

vmNetworkSettings.nics[].externalIpAddress

String

If the network that the NIC is connected to has NAT or port mapping, the external address is populated in this element.

vmNetworkSettings.nics[].networkAdapterType

String

NIC Adapter type.

vmNetworkSettings.nics[].needsCustomization

Boolean

Flag to signify if the NIC needs customization.

vmNetworkSettings.nics[].macAddress

String

The MAC address of the NIC.

vmNetworkSettings.copySourceNicSettings

Boolean

Indicates whether the source Vm NIC settings should be copied to the recovered VM.

vmNetworkSettings.computerName

String

Optionally provide computer name.

vmNetworkSettings.enableGuestCustomization

Boolean

Optionally provide whether to enable guest customization.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover-test?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 1106

{
  "type" : "vcloud",
  "powerOn" : false,
  "sync" : false,
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "vAppNetworkSettings" : {
    "networkMappings" : [ {
      "sourceNetworkName" : "sourceNetworkName",
      "sourceOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      },
      "destinationOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      }
    } ],
    "copySourceNetworks" : false,
    "bridgeOrgVdcNetworks" : [ {
      "id" : "id",
      "name" : "name"
    } ],
    "bulkConnectVmNics" : true
  },
  "vmNetworkSettings" : {
    "primaryNicIndex" : 0,
    "nics" : [ {
      "nicIndex" : 0,
      "isConnected" : true,
      "resetMacAddress" : true,
      "network" : "orgVdcNetwork1",
      "ipAddress" : "192.168.0.101",
      "ipAddressAllocationMode" : "DHCP",
      "externalIpAddress" : "10.72.112.4",
      "networkAdapterType" : "type1",
      "needsCustomization" : false,
      "macAddress" : "00:50:56:a9:0c:12"
    } ],
    "copySourceNicSettings" : true,
    "computerName" : "testPc",
    "enableGuestCustomization" : true
  }
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover-test?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "vcloud",
  "powerOn" : false,
  "sync" : false,
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "vAppNetworkSettings" : {
    "networkMappings" : [ {
      "sourceNetworkName" : "sourceNetworkName",
      "sourceOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      },
      "destinationOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      }
    } ],
    "copySourceNetworks" : false,
    "bridgeOrgVdcNetworks" : [ {
      "id" : "id",
      "name" : "name"
    } ],
    "bulkConnectVmNics" : true
  },
  "vmNetworkSettings" : {
    "primaryNicIndex" : 0,
    "nics" : [ {
      "nicIndex" : 0,
      "isConnected" : true,
      "resetMacAddress" : true,
      "network" : "orgVdcNetwork1",
      "ipAddress" : "192.168.0.101",
      "ipAddressAllocationMode" : "DHCP",
      "externalIpAddress" : "10.72.112.4",
      "networkAdapterType" : "type1",
      "needsCustomization" : false,
      "macAddress" : "00:50:56:a9:0c:12"
    } ],
    "copySourceNicSettings" : true,
    "computerName" : "testPc",
    "enableGuestCustomization" : true
  }
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3347

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "failoverTest",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
        "vcdVmId" : "9664de13-6150-4315-9f59-2d85eb4c302f",
        "type" : "vcd",
        "recoveryState" : "TEST"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Delete the Test Failover VM Replication

DELETE /vm-replications/{replicationId}/failover-test cleans up the test failover VM.

Available since: v2

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/failover-test
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

DELETE /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover-test?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover-test?site=site2' -i -X DELETE \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3293

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "failoverTestCleanup",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Test a VM Replication Failover to On-Premises

POST /vm-replications/{replicationId}/failover-test tests failing over the VM to the destination on-premises site.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/failover-test
Parameter Description

replicationId

Cloud to-VC replication identifier.

Request fields

Path Type Description

type

String

Discriminator property, should be set to 'vcenter' in this case.

sync

Boolean

Whether automatic synchronization should be performed before the failover test. Cannot be set to 'true' if the 'instanceId' parameter is populated.

instanceId

String

Optional ID of a rotated instance to recover to. By default the latest instance is used. Cannot be used together with the 'sync' parameter set to true.

exposePITsAsSnapshots

Boolean

Optional parameter to specify whether the existing preceding rotated instances should be exposed as snapshots or nothing should happen in the test VM.

powerOn

Boolean

Whether or not the recovered VM should be powered on.

customVirtualHardware

Object

Specifies hw changes to be performed on the recovered VM. This or any of the hw changes are optional.

customVirtualHardware.numCpus

Number

Number of vCPUs of the recovered VM. If not specified it will be the same as the source VM.

customVirtualHardware.numCoresPerSocket

Number

Number of cores per socket. If not specified it will be the same as the source VM.

customVirtualHardware.memoryInMB

Number

Memory in MB. If not specified it will be the same as the source VM.

customVirtualHardware.macAddressPolicy

String

Whether to change the MAC addresses of all network devices. If unset no changes will be performed. If the recovered VM hits instance uuid collision new MAC addresses will be generated by vCenter. Valid values are [DEFAULT, GENERATE_NEW].

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover-test HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 296

{
  "type" : "vcenter",
  "powerOn" : true,
  "exposePITsAsSnapshots" : true,
  "customVirtualHardware" : {
    "numCpus" : 2,
    "numCoresPerSocket" : 4,
    "memoryInMB" : 4096,
    "macAddressPolicy" : "DEFAULT"
  },
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "sync" : false
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/failover-test' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "vcenter",
  "powerOn" : true,
  "exposePITsAsSnapshots" : true,
  "customVirtualHardware" : {
    "numCpus" : 2,
    "numCoresPerSocket" : 4,
    "memoryInMB" : 4096,
    "macAddressPolicy" : "DEFAULT"
  },
  "instanceId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
  "sync" : false
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3347

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "failoverTest",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
        "vcdVmId" : "9664de13-6150-4315-9f59-2d85eb4c302f",
        "type" : "vcd",
        "recoveryState" : "TEST"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Migrate a VM Replication

POST /vm-replications/{replicationId}/migrate performs a planned migration for the specified replication.

The planned migration attempts to synchronize the latest changes of the source VM and then powers off the source VM. The source site must be available for the planned migration to succeed. If the source site is unavailable, try performing a failover instead.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/migrate
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

type

String

Discriminator property, should be set to 'vcloud' in this case.

consolidate

Boolean

Optional parameter to specify whether rotated instances should be consolidated or nothing should happen in the recovered VM. Defaults to false.

powerOn

Boolean

Whether or not the recovered VM should be powered on.

vAppNetworkSettings

Object

Network settings for replication vApp result due to failover/migrate or test failover.

vAppNetworkSettings.networkMappings[]

Array

C2C - If vApp has networks connected to OrgVdcNetwork, the mapping specifies which is the corresponding destination OrgVdcNetwork to use (if any).

vAppNetworkSettings.networkMappings[].sourceNetworkName

String

Name of the vApp network at the source.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork

Object

When present, the source vApp network is isolated one.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork.id

String

UUID of the source org vDC network.

vAppNetworkSettings.networkMappings[].sourceOrgVdcNetwork.name

String

Name of the source org vDC network.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork

Object

When present, the destination vApp network is isolated one.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork.id

String

UUID of the destination org vDC network.

vAppNetworkSettings.networkMappings[].destinationOrgVdcNetwork.name

String

Name of the destination org vDC network.

vAppNetworkSettings.bridgeOrgVdcNetworks[].id

String

OrgVdc Networks which the vApp to bridge to (if it hasn’t already) - ID.

vAppNetworkSettings.bridgeOrgVdcNetworks[].name

String

OrgVdc Networks which the vApp to bridge to (if it hasn’t already) - name.

vAppNetworkSettings.copySourceNetworks

Boolean

C2C - copy source networks.

vAppNetworkSettings.bulkConnectVmNics

Boolean

Shortcut option to connect all VM NICs to single orgVdcNetwork.

vmNetworkSettings

Object

Network Settings for Virtual Machine.

vmNetworkSettings.primaryNicIndex

Number

Primary NIC index.

vmNetworkSettings.nics[].nicIndex

Number

Index of the NIC starting from 0 in a VM.

vmNetworkSettings.nics[].isConnected

Boolean

Indicates whether the NIC should be connected.

vmNetworkSettings.nics[].resetMacAddress

Boolean

Indicates whether the NIC MAC address should be reset (regenerated) or kept as it is.

vmNetworkSettings.nics[].network

String

The name of the network to which the NIC is attached.

vmNetworkSettings.nics[].ipAddress

String

In case MANUAL IpAddressAllocationMode (below) is selected, then this holds the IP address of the NIC.

vmNetworkSettings.nics[].ipAddressAllocationMode

String

Ip Address allocation mode. Can be one of POOL, DHCP, MANUAL, NONE.

vmNetworkSettings.nics[].externalIpAddress

String

If the network that the NIC is connected to has NAT or port mapping, the external address is populated in this element.

vmNetworkSettings.nics[].networkAdapterType

String

NIC Adapter type.

vmNetworkSettings.nics[].needsCustomization

Boolean

Flag to signify if the NIC needs customization.

vmNetworkSettings.nics[].macAddress

String

The MAC address of the NIC.

vmNetworkSettings.copySourceNicSettings

Boolean

Indicates whether the source Vm NIC settings should be copied to the recovered VM.

vmNetworkSettings.computerName

String

Optionally provide computer name.

vmNetworkSettings.enableGuestCustomization

Boolean

Optionally provide whether to enable guest customization.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/migrate?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 1056

{
  "type" : "vcloud",
  "powerOn" : false,
  "consolidate" : false,
  "vAppNetworkSettings" : {
    "networkMappings" : [ {
      "sourceNetworkName" : "sourceNetworkName",
      "sourceOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      },
      "destinationOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      }
    } ],
    "copySourceNetworks" : false,
    "bridgeOrgVdcNetworks" : [ {
      "id" : "id",
      "name" : "name"
    } ],
    "bulkConnectVmNics" : true
  },
  "vmNetworkSettings" : {
    "primaryNicIndex" : 0,
    "nics" : [ {
      "nicIndex" : 0,
      "isConnected" : true,
      "resetMacAddress" : true,
      "network" : "orgVdcNetwork1",
      "ipAddress" : "192.168.0.101",
      "ipAddressAllocationMode" : "DHCP",
      "externalIpAddress" : "10.72.112.4",
      "networkAdapterType" : "type1",
      "needsCustomization" : false,
      "macAddress" : "00:50:56:a9:0c:12"
    } ],
    "copySourceNicSettings" : true,
    "computerName" : "testPc",
    "enableGuestCustomization" : true
  }
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/migrate?site=site2' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "vcloud",
  "powerOn" : false,
  "consolidate" : false,
  "vAppNetworkSettings" : {
    "networkMappings" : [ {
      "sourceNetworkName" : "sourceNetworkName",
      "sourceOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      },
      "destinationOrgVdcNetwork" : {
        "id" : "id",
        "name" : "name"
      }
    } ],
    "copySourceNetworks" : false,
    "bridgeOrgVdcNetworks" : [ {
      "id" : "id",
      "name" : "name"
    } ],
    "bulkConnectVmNics" : true
  },
  "vmNetworkSettings" : {
    "primaryNicIndex" : 0,
    "nics" : [ {
      "nicIndex" : 0,
      "isConnected" : true,
      "resetMacAddress" : true,
      "network" : "orgVdcNetwork1",
      "ipAddress" : "192.168.0.101",
      "ipAddressAllocationMode" : "DHCP",
      "externalIpAddress" : "10.72.112.4",
      "networkAdapterType" : "type1",
      "needsCustomization" : false,
      "macAddress" : "00:50:56:a9:0c:12"
    } ],
    "copySourceNicSettings" : true,
    "computerName" : "testPc",
    "enableGuestCustomization" : true
  }
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3342

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "migrate",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
        "vcdVmId" : "9664de13-6150-4315-9f59-2d85eb4c302f",
        "type" : "vcd",
        "recoveryState" : "TEST"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Migrate a VM Replication to On-Premises

POST /vm-replications/{replicationId}/migrate performs a planned migration for the specified replication.

The planned migration attempts to synchronize the latest changes of the source VM and then powers off the source VM. The source site must be available for the planned migration to succeed. If the source site is unavailable, try performing a failover instead.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/migrate
Parameter Description

replicationId

Cloud VM-level replication identifier.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

type

String

Discriminator property, should be set to 'vcenter' in this case.

snapshotOptions

String

Optional parameter to specify whether the existing preceding rotated instances should be exposed as snapshots, whether the rotated instances should be consolidated or nothing should happen in the recovered VM.Can be [DO_NOTHING, EXPOSE_PITS, CONSOLIDATE]. Defaults to EXPOSE_PITS.

powerOn

Boolean

Whether or not the recovered VM should be powered on.

customVirtualHardware

Object

Specifies hw changes to be performed on the recovered VM. This or any of the hw changes are optional.

customVirtualHardware.numCpus

Number

Number of vCPUs of the recovered VM. If not specified it will be the same as the source VM.

customVirtualHardware.numCoresPerSocket

Number

Number of cores per socket. If not specified it will be the same as the source VM.

customVirtualHardware.memoryInMB

Number

Memory in MB. If not specified it will be the same as the source VM.

customVirtualHardware.macAddressPolicy

String

Whether to change the MAC addresses of all network devices. If unset no changes will be performed. If the recovered VM hits instance uuid collision new MAC addresses will be generated by vCenter. Valid values are [DEFAULT, GENERATE_NEW].

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/migrate HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 224

{
  "type" : "vcenter",
  "powerOn" : true,
  "snapshotOptions" : "CONSOLIDATE",
  "customVirtualHardware" : {
    "numCpus" : 2,
    "numCoresPerSocket" : 4,
    "memoryInMB" : 4096,
    "macAddressPolicy" : "DEFAULT"
  }
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/migrate' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "type" : "vcenter",
  "powerOn" : true,
  "snapshotOptions" : "CONSOLIDATE",
  "customVirtualHardware" : {
    "numCpus" : 2,
    "numCoresPerSocket" : 4,
    "memoryInMB" : 4096,
    "macAddressPolicy" : "DEFAULT"
  }
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result.id

String

The Cloud VM-level replication ID.

result.vmId

String

VMware Cloud Director VM ID.

result.vmName

String

VMware Cloud Director VM name.

result.storageProfile

String

Destination storage profile.

result.storageProfileName

String

Destination storage profile display name.

result.vimLocation

Object

Provides vCenter Server coordinates for an ongoing destination replication to admin users.

result.vimLocation.vimServer

String

The vCenter Server instance.

result.vimLocation.vimServerInstanceUuid

String

The instance UUID of the vCenter Server where the replica files are located.

result.vimLocation.datastore

String

VMware Cloud Director datastore identifier for the datastore on which the replication resides. This datastore resides in the vCenter Server. Only visible to administrator users.

result.vimLocation.datastoreMoref

String

The vCenter Server managed object ID of the datastore the replication resides on. Only visible for administrator users.

result.vimLocation.datastoreName

String

The name of the datastore the replication resides on. This datastore exists within vCenter Server. Only visible for administrator users.

result.isPaused

Boolean

Indicates whether the underlying VM replication is paused.

result.settings

Object

VM-level replication settings.

result.startupInfo

Object

VMware Cloud Director startupInfo for the VM.

result.metadata

Object

VMware Cloud Director metadata for the VM.

result.sourceState

Object

Source state information.

result.destinationState

Object

Destination state information.

result.dataConnectionState

String

Shows the replication traffic (data) connection health. Possible values: [SYNCING, INITIAL_SYNCING, OK, PAUSED, POWERED_OFF, PRUNING, FINISHED, UNKNOWN, ERROR].

result.overallHealth

String

Representation of the replication health suitable for UI purposes.

result.lastUpdated

Number

The startTime of the latest task associated with this VM replication.

result.isReversed

Boolean

Whether the replication is reversed. Note this flag gets inverted on each reverse, so only the odd reversed replication will show 'true'.

result.computerName

String

VMware Cloud Director VM computer name.

result.vmDescription

String

VMware Cloud Director VM description.

result.isMigration

Boolean

True when the VM replication is a migration. False when the replication is a protection.

result.slaProfile

Object

The SLA profile applied to this replication.

result.slaProfile.id

String

The ID of the SLA profile applied to this replication.

result.slaProfile.displayName

String

The name of the SLA profile applied to this replication.

result.vappReplicationId

String

ID of the corresponding vApp replication.

result.owner

String

The ID of the user that owns the replication.

result.source

Object

Source vApp info.

result.source.site

String

The shortname of the site that holds the source vApp.

result.source.org

String

The shortname of the org the source vApp belongs to.

result.source.vdcId

String

The VMware Cloud Director virtual data center ID where the source vApp resides.

result.source.vdcName

String

The VMware Cloud Director virtual data center name where the source vApp resides.

result.source.vappId

String

Source vApp VMware Cloud Director ID.

result.source.vappName

String

Source vApp display name.

result.destination

Object

Replication destination info.

result.destination.site

String

The shortname of the destination site.

result.destination.vdcId

String

VMware Cloud Director virtual data center ID in the destination site.

result.destination.vdcName

String

VMware Cloud Director virtual data center Name in the destination site.

result.destination.org

String

Destination organization in VMware Cloud Director.

result.destination.recoveredVappId

String

The VMware Cloud Director vApp on the destination site that holds the recovered VM (only populated if one or more VMs belonging to the same source vApp are recovered on the destination site).

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3346

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "migrate",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
        "vcdVmId" : "9664de13-6150-4315-9f59-2d85eb4c302f",
        "type" : "vcd",
        "recoveryState" : "COMPLETE"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Reverse a VM Replication

POST /vm-replications/{replicationId}/reverse reverses the VM replication.

By using a failover or a planned migration, the reversed replication needs to be recovered. A new VM replication is created in the oposite direction. The disks of the original source VM are used as seeds. The original source VM is removed. The vApp of the original source VM is powered off and left intact without the VM.

Available since: v2

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/reverse
Parameter Description

replicationId

ID of the replication to reverse.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request structure

POST /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/reverse?site=site2 HTTP/1.1
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Type: application/x-www-form-urlencoded

site=site2

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/reverse?site=site2' -i -X POST \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI='

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

Replication info of the reversed replication.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3281

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "reverse",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Configure the Settings of a VM Replication

PATCH /vm-replications/{replicationId} reconfigures the VM replication settings.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}
Parameter Description

replicationId

ID of the replication to pause.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

description

String

The description of the replication.

rpo

Number

Recovery point objective in minutes - if empty/omitted no change will be applied.

dataConnectionType

String

What Lightweight Delta Protocol traffic mode is supported. Can be [PLAIN, ENCRYPTED, ENCRYPTED_COMPRESSED].

quiesced

Boolean

Replicated image guest quiescing - if empty/omitted no change will be applied.

retentionPolicy

Object

Replication instance retention policy - the number of instances and for how long to store them.

retentionPolicy.rules[]

Array

The set of rules building up the retention policy.

retentionPolicy.rules[].numberOfInstances

Number

The number of instances to store.

retentionPolicy.rules[].distance

Number

Time (in min) between each two consequent stored instances.

sourceReconfigure

Object

Settings for reconfiguring the source.

sourceReconfigure.type

String

Either 'vcVappReconfigure' or 'vcVmReconfigure'.

sourceReconfigure.vappName

String

The name of the vApp into which the replicated VMs will be imported.

sourceReconfigure.vmStartupInfo

Object

VMware Cloud Director startupInfo for the VM.

sourceReconfigure.vmStartupInfo.order

Number

Boot order number of the VM.

sourceReconfigure.vmStartupInfo.startAction

String

Start action of the VM.

sourceReconfigure.vmStartupInfo.startDelay

Number

Start delay for the VM in milliseconds.

sourceReconfigure.vmStartupInfo.stopAction

String

Stop action of the VM.

sourceReconfigure.vmStartupInfo.stopDelay

Number

Stop delay for the VM in milliseconds.

slaProfileId

String

When omitted old SLA profile ID will be used (if any) or if rpo, dataConnectionType, quiesced or retentionPolicy are specified old SLA profile will be discarded and custom settings will be used.

Request structure

PATCH /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 541

{
  "description" : "new description",
  "rpo" : 15,
  "dataConnectionType" : "ENCRYPTED_COMPRESSED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 1,
      "distance" : 5
    } ]
  },
  "sourceReconfigure" : {
    "type" : "vcVmReconfigure",
    "vappName" : "vapName",
    "vmStartupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    }
  },
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3?site=site2' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '{
  "description" : "new description",
  "rpo" : 15,
  "dataConnectionType" : "ENCRYPTED_COMPRESSED",
  "quiesced" : true,
  "retentionPolicy" : {
    "rules" : [ {
      "numberOfInstances" : 1,
      "distance" : 5
    } ]
  },
  "sourceReconfigure" : {
    "type" : "vcVmReconfigure",
    "vappName" : "vapName",
    "vmStartupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    }
  },
  "slaProfileId" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba"
}'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String

Name of the resource associated with the task. Not all resources have a name.

progress

Number

Percentage-based progress of the task.

lastUpdated

Number

Timestamp (in msec) of the last task status update.

startTime

Number

Timestamp (in msec) of the time the task is created.

endTime

Number

Timestamp in (msec) of the time the task completed. A value of -1 indicates that the task is not yet complete.

resultType

String

Indicates the type of the result for tasks that completed with a result.

warnings

ResultWarning[]

Warnings, which occurred during the task execution.

error

ApiError

Error field that is populated if the task execution fails.

result

Object

Up-to-date Cloud VM replication info.

site

String

The site name where the task runs.

Example response

HTTP/1.1 202 Accepted
Content-Type: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
Content-Length: 3285

{
  "id" : "52ce9bc4-2563-448d-b8af-9047a03ce5c2",
  "user" : "org2@site2",
  "workflowInfo" : {
    "type" : "reconfigure",
    "resourceType" : "vmReplication",
    "resourceId" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "resourceName" : "my vm 1"
  },
  "progress" : 100,
  "state" : "SUCCEEDED",
  "lastUpdated" : 1499929558827,
  "startTime" : 1499929548951,
  "endTime" : 1499929558827,
  "resultType" : "SingleVmReplicationInfo",
  "result" : {
    "id" : "C4-ec991bd5-af9d-446a-8599-5b693842c4a3",
    "owner" : "org1@site1",
    "vmId" : "4e7fa4b1-e8d9-45bd-a91d-852c46b7a0da",
    "vmName" : "my vm 1",
    "source" : {
      "site" : "site1",
      "org" : "org1",
      "vdcId" : "f61d60d2-698a-46dc-a266-88df27644956",
      "vdcName" : "Virtual DC 1",
      "vappId" : "d6977f40-4d90-46b2-a34e-5077e8648eda",
      "vappName" : "my vApp"
    },
    "destination" : {
      "site" : "site2",
      "org" : "s2org",
      "vdcId" : "5ee9224f-305d-46f6-865f-b605e70acef8",
      "vdcName" : "Virtual DC 2",
      "recoveredVappId" : "vapp-1"
    },
    "storageProfile" : "*",
    "storageProfileName" : "Default",
    "vimLocation" : {
      "vimServer" : "c3ebbf62-c7ff-4c70-b783-7b6074d770e4",
      "vimServerInstanceUuid" : "318d06a5-b126-4a8d-8150-dc90d3e385cd",
      "datastore" : "69f9e569-30f1-46a7-a754-969a2fa5b955",
      "datastoreMoref" : "datastore-12",
      "datastoreName" : "testDatastore"
    },
    "isPaused" : false,
    "settings" : {
      "description" : "A vm replication",
      "rpo" : 5,
      "dataConnectionType" : "ENCRYPTED_COMPRESSED",
      "quiesced" : true,
      "retentionPolicy" : {
        "rules" : [ {
          "numberOfInstances" : 3,
          "distance" : 60
        } ]
      },
      "initialSyncTime" : 4102444800,
      "excludedDiskKeys" : [ ]
    },
    "startupInfo" : {
      "order" : 0,
      "startAction" : "powerOn",
      "startDelay" : 0,
      "stopAction" : "powerOff",
      "stopDelay" : 0
    },
    "metadata" : {
      "val1" : {
        "key" : "val1",
        "access" : "READONLY",
        "type" : "STRING",
        "value" : "Hello, world!"
      }
    },
    "sourceState" : {
      "state" : "syncing",
      "progress" : {
        "progress" : 50,
        "bytesTransferred" : 2048,
        "bytesToTransfer" : 4096,
        "checksumTotalBytes" : 4096,
        "checksumComparedBytes" : 4096
      },
      "stateAge" : 0
    },
    "destinationState" : {
      "currentRpoViolation" : -1,
      "latestInstance" : null,
      "state" : "fullsync",
      "recoveryInfo" : {
        "vAppId" : null,
        "vcdVmId" : null,
        "type" : "vcd",
        "recoveryState" : "NOT_STARTED"
      },
      "lastError" : null,
      "stateAge" : 0,
      "spaceRequirement" : 0,
      "isMovingReplica" : false
    },
    "dataConnectionState" : "OK",
    "overallHealth" : "GREEN",
    "lastUpdated" : 618094800000,
    "isReversed" : false,
    "vappReplicationId" : "C4VAPP-ccbe771e-b685-46c7-8c7a-4ed36915d963",
    "computerName" : "computerName",
    "vmDescription" : "vmDescription",
    "isMigration" : false,
    "slaProfile" : {
      "id" : "2bfb7696-3aa1-49d3-bb40-d9e97df1baba",
      "displayName" : "Gold"
    }
  },
  "error" : null,
  "warnings" : [ ],
  "site" : "site2"
}

Configure the Disks of a VM Replication

PATCH /vm-replications/{replicationId}/disks reconfigures the set of replicated VM disks.

Available since: v3.5

Required roles: One of EVERYONE, PEER_IMPERSONATING

Path parameters

/vm-replications/{replicationId}/disks
Parameter Description

replicationId

ID of the replication to pause.

Request parameters

Parameter Description

site

Optional site to run the operation on. When omitted, defaults to the local site.

Request fields

Path Type Description

[]

Array

The new set of excluded disk device keys.

Request structure

PATCH /vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/disks?site=site2 HTTP/1.1
Content-Type: application/json
Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8
X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=
Host: localhost:8046
Content-Length: 8

[ 2000 ]

Example request

$ curl 'https://localhost:8046/vm-replications/C4-ec991bd5-af9d-446a-8599-5b693842c4a3/disks?site=site2' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.vmware.h4-v4.1+json;charset=UTF-8' \
    -H 'X-VCAV-Auth: PV8CplzIzWIe9BD9ayirWT6JNgI=' \
    -d '[ 2000 ]'

Response structure

Path Type Description

id

String

A unique identifier of the long-running task, that can be used for monitoring.

user

String

The user who started the task.

state

String

The current state of the task. States: [RUNNING, SUCCEEDED, FAILED].

workflowInfo

Object

Workflow information about the task.

workflowInfo.type

String

The workflow type.

workflowInfo.resourceType

String

Type of the resource associated with the task.

workflowInfo.resourceId

String

Identifier of the resource associated with the task. Not all tasks have resourceId.

workflowInfo.resourceName

String