Migrate Defined Entities Of Type

Attempts to migrate Defined Entity instances of a Defined Entity Type (source entity type) to another version (upgrade/downgrade) of the Defined Entity Type (target entity type). Depending on potential concurrent updates, this operation might, or might not process all instances. If you seek to migrate all instances, you have a few options:

run this operation, or individual RDE updates multiple times, as many as required (inspecting state after each run)
make sure not to perform any upgrade/downgrade operations on Defined Entity instances of the source entity type while the migrate task is in progress. Only those Defined Entity instances which the user has modify access to are affected by the mass migrate operation.

Essentially the mass migrate operation is a batch update operation on the Defined Entity instances of the source entity type (each instance is updated with changing the "entityType" property to the target entity type). However, the underlying update operation on each Defined Entity instance is limited in terms of functionality compared to the API update operation on a Defined Entity instance. First of all, you can only update the "entityType" property of the Defined Entity instance. Also you cannot make use of the OCC functionality when executing a mass migrate - Defined Entity instances will be updated regardless of their current state. And lastly, a PostUpdate hook, defined in the target entity type, will not be executed on the Defined Entity instances after a mass migrate operation.

The mass migrate operation may also change the entityState of the Defined Entity instances:

If an instance is in PRE_CREATED entityState before the migration - the instance will remain in PRE_CREATED entityState after the migration
If an instance is in RESOLUTION_ERROR entityState before the migration - the instance will move into PRE_CREATED entityState after the migration
If an instance is in IN_DELETION entityState before the migration - the instance will remain in IN_DELETION entityState after the migration
If an instance is in RESOLVED entityState before the migration - the migration operation will try to resolve the instance after upgrading it to the target type's version. If the instance's entity contents validate against the target version's schema, the instance will remain in RESOLVED entityState. If the instance's entity contents cannot validate against the target version's schema, the instance will either remain unchanged (migration will be rolled back) or it will move into RESOLUTION_ERROR entityState depending on the value of the "forceMigrate" property (part of the body of the request). The default behavior is to roll back the migration. Generally in this case (when the instance's entity contents are incompatible with the target version's schema), the user must then individually update each of the incompatible instances according to their business logic.

A RDE modify event is emitted for each instance which is migrated with the 'definedEntity.type' and 'definedEntity.was.type' additional properties having different values (the same RDE modify event is emitted with the Defined Entity instance update operation).

The mass migrate operation is suitable for use when there are a lot of instances of a Defined Entity type which need to be migrated and a small fraction of them is expected to be incompatible with the target entity type's schema. In all other cases, the usual update Defined Entity instance operation is more appropriate.

Request

URI

POST

https://{api_host}/cloudapi/1.0.0/entityTypes/{typeId}/migrateEntities

COPY

Path Parameters

string

typeId

Required

The source type URN. It can be:

full type URN (e.g. urn:vcloud:type:vmware:test:1.0.0) - all Defined Entity instances of type version "1.0.0" will be migrated to the target version
classification type URN (e.g. urn:vcloud:type:vmware:test) - all Defined Entity instances of the type will be migrated to the target version
type urn with partial version (e.g. urn:vcloud:type:vmware:test:1.0) - all Defined Entity instances of the type with version starting with "1.0" will be migrated to the target version

Request Body

DefinedEntitiesVersionMigrate of type(s) application/json

Required

{
    "targetEntityType": "urn:vcloud:type:vmware:vspheresddc:1.0.0",
    "forceMigrate": false
}

string

targetEntityType

Optional

The full URN of the Defined Entity Type which the Defined Entity instances will migrate to.

boolean

forceMigrate

Optional

If a Defined Entity instance is in RESOLVED entityState before the migration, the migration operation will try to resolve the entity after migrating it to the new type's version. If the instance's entity contents cannot validate against the target version's schema:

forceMigrate = false - Defined Entity instance will not be migrated and will remain unchanged
forceMigrate = true - Defined Entity instance will be migrated and it will move into RESOLUTION_ERROR entityState

Authentication

This operation uses the following authentication methods.

ApiKeyAuth

Responses

202

The request have been accepted and the task to monitor the request is in the Location header.

Operation doesn't return any data structure

Availability

Added in 38.0

On This Page

Description

Request