Modify an Entity

This API enables you to modify a Chargeback entity's name and description in the Chargeback hierarchy. You cannot modify the root entity or a vCenter Server entity in a Chargeback hierarchy.

Syntax

The syntax for calling this method is:

PUT <Base_Url>/hierarchy/{hierarchyId}/entity/{entityId}

A sample API call is as follows:

PUT https://123.123.123.123/vCenter-CB/api/hierarchy/1/entity/100

User Privilege

To call this API, you must have a role with Read privilege on the hierarchy and Update privilege on the entity.

Request Body Parameters

The API takes a request XML in which you can provide the following body parameters.

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy to which the entity belongs.

Hierarchies/Hierarchy/@id

xs:int

0

1

ID of the hierarchy.

Hierarchies/Hierarchy/Entities/Entity

 

1

1

Represents the entity you want to modify.

Hierarchies/Hierarchy/Entities/Entity/@id

xs:int

0

1

ID of the entity.

Hierarchies/Hierarchy/Entities/Entity/Name

xs:string

0

1

Name of the entity. The character limit for the entity name is 255 characters. The entity names are not case sensitive.

Hierarchies/Hierarchy/Entities/Entity/Description

xs:string

0

1

Description for the entity. The character limit for the description is 512 characters.

A sample request XML is provided here.

API Response

If the operation is successful, the API returns an XML response with the following details.

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy element to which entity belongs.

Hierarchies/Hierarchy/@id

xs:int

1

1

ID of the hierarchy.

Hierarchies/Hierarchy/Name

xs:string

1

1

Name of the hierarchy.

Hierarchies/Hierarchy/Description

xs:string

1

1

Description provided for the hierarchy.

Hierarchies/Hierarchy/CreatedOn

xs:long

1

1

Time, in milliseconds, when the hierarchy was created.

Hierarchies/Hierarchy/InSync

xs:boolean

1

1

Indicates if the Chargeback hierarchy is synchronized with the vCenter Server hierarchy. Because the synchronization cannot be turned off, this value is always set to true.

Hierarchies/Hierarchy/LastUpdatedTime

xs:long

1

1

Indicates the time when the Chargeback hierarchy was last updated.

Hierarchies/Hierarchy/LastUpdatedUser

xs:string

1

1

Indicates the user who last updated the Chargeback hierarchy. If the hierarchy is automatically updated because of changes in the vCenter Server hierarchy, the user name is 'CBM Server'.

Hierarchies/Hierarchy/Entities/Entity

 

1

1

Represents the entity element.

Hierarchies/Hierarchy/Entities/Entity/@id

xs:int

1

1

The ID of the entity in the hierarchy.

Hierarchies/Hierarchy/Entities/Entity/Name

xs:string

1

1

Name of the entity.

Hierarchies/Hierarchy/Entities/Entity/Description

xs:string

1

1

Description provided for the entity.

Hierarchies/Hierarchy/Entities/Entity/Type

xs:int

1

1

Type of the entity. For more information, refer Chargeback EntityTypes.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share

 

1

1

Represents the share of the entity element.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share/Percentage

xs:int

1

1

The shared percentage of the entity.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share/Parent/@id

xs:int

1

1

The ID of the parent entity.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share/StartTime

xs:long

1

1

Time, in milliseconds, when the entity was added to the parent.

A sample response is provided here.

Error Response

The following table explains the error codes returned by the API.

Error code

Description

VCB_ERR_INVALID_ENTITY_ID

Returned if a specified entity is not found in the hierarchy.

VCB_ERR_INVALID_ENTITY_NAME

Returned if an empty entity name is specified, or the entity name exceeds 255 characters.

VCB_ERR_INVALID_ENTITY_DESCRIPTION

Returned if the hierarchy description exceeds 512 characters.

VCB_ERR_ENTITY_NAME_ALREADY_EXISTS

Returned if an entity with the same name exists under the parent.

VCB_ERR_ROOT_ENTITY

Returned if an entity is a root entity.

VCB_ERR_VC_ENTITY

Returned when trying to rename an entity, which is a vCenter entity.