Add Entity

This API helps create a new Chargeback entity (folder) under a specified parent entity or enables you to add a new vCenter server entity under a specified parent entity in the Chargeback hierarchy.

For a vCenter Server entity that has child entities, the API returns the ID of the newly added entity with its immediate children. For a Chargeback entity, the API returns the new empty entity.

This API also takes multiple entities. It adds all the entities or none. If there is a problem with adding even one entity, the operation fails.

To add a new vCenter server entity, this API takes one of the following:

If a vCenter server entity or its children already exist in the Chargeback hierarchy, you cannot add that entity again to the Chargeback hierarchy. If you want to share an entity in the hierarchy, see Share an Entity.

Note: You can add entities either from Hosts & Clusters view or from the VMs & Templates view. You cannot added entities from both the views of a vCenter Server to the same chargeback hierarchy. For multiple vCenter Servers, you can add entities from both the views.

Syntax

The syntax for calling this method is:

POST <Base URL>/hierarchy/{hierarchyId}/entity/{parentEntityId}

A sample API call is as follows:

POST https://123.123.123.123/vCenter-CB/api/hierarchy/1/entity/51

User Privilege

To call this API, you must have a role with Update privilege on the hierarchy and the parent entity. If you are adding a vCenter Server entity, you must have a Read privilege on that entity.

URL Parameters


Name

Data Type

Required/Optional

Description

Sample Value

importVCenterAttributes

Integer

Optional

Whether to import vCenter attributes or not. The default value is false.

True

startTime

Long

Optional

Time of creation of the entity (in milliseconds; from January 1, 1970 GMT 00:00). If not specified, the value defaults to the server time at which the request is processed.

Note: An entity can be added at a past time only once. if it is added and deleted, then it cannot be added in the past again.

1232562600000


 

 

 

 

 

 

 

 

 

Request Body Parameters

To add a Chargeback entity, create a a request XML with the following body parameters.

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy where the entity needs to be added.

Hierarchies/Hierarchy/@id

xs:int

0

1

ID of the hierarchy.

Hierarchies/Hierarchy/Entities/Entity

 

1

1

Represents the entity element that is to be added.

Hierarchies/Hierarchy/Entities/Entity/@id

xs:int

0

1

ID of the parent entity.

Hierarchies/Hierarchy/Entities/Entity/Name

xs:string

1

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

An optional description for the entity. The character limit for the description is 512 characters.

Hierarchies/Hierarchy/Entities/Entity/Type

xs:int

1

1

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

A sample request XML to add a Chargeback entity is provided here.

To add a vCenter Server entity, you must create a request XML with the following information.

XPath

Type

Min Occurs

Max Occurs

Description

VCenterServers/VCenterServer

 

1

1

Represents the vCenter Server from which you want to retrieve the hierarchy.

VCenterServers/VCenterServer/@id

xs:int

1

1

ID of the vCenter Server.

VCenterServers/VCenterServer/VCenterServerView/@id

xs:int

1

1

Integer to select either Hosts and Clusters view,
or Virtual Machines and Templates view.

VCenterServers/VCenterServer/Entities/Entity

 

0

unbounded

Represents each entity in the vCenter hierarchy.

VCenterServers/VCenterServer/Entities/Entity/@id

xs:int

0

1

ID of the vCenter Server entity. To add an entity, you can specify either Entity ID or MoID.

VCenterServers/VCenterServer/Entities/Entity/MoId

xs:string

0

1

MoID (managed object ID) of the entity as defined in the vCenter Server.

A sample request XML to add a vCenter Server entity is provided here.

API Response

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

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy element that is created.

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

unbounded

Represents each entity element that is created. If you are adding a Chargeback entity, the response contains only the entity that is created. If you are adding a vCenter Server entity, the response contains the entity and its children.

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 of the entity.

Hierarchies/Hierarchy/Entities/Entity/Type

xs:int

1

1

Type of the entity. For more information, see Chargeback Entity Types.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share

 

1

1

Represents the share of the entity element with its parent.

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. If this is a root entity, it will not not have a parent and hence, the value is always -1.

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 for adding a chargeback entity is provided here.

A sample response for adding a vCenter server entity is provided here.

Error Response

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

Error code

Description

VCB_ERR_INVALID_ENTITY_ID

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

VCB_ERR_INVALID_ENTITY_NAME

Returned if an empty entity name is specified.

VCB_ERR_INVALID_ENTITY_DESCRIPTION

Returned if the hierarchy description exceeds 512 characters.

VCB_ERR_INVALID_ENTITY_TYPE

Returned if a specified entity type is invalid.

VCB_ERR_ENTITY_NAME_ALREADY_EXISTS

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

VCB_ERR_VC_ENTITY

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

VCB_ERR_INVALID_VCENTER_SERVER_ID

Returned if an invalid vCenter identifier is specified.

VCB_ERR_INVALID_VCENTER_ENTITY

Returned if an invalid vCenter entity identifier is specified.
Or
Returned if a vCenter entity is not found while retrieving custom attributes for a vCenter entity.

VCB_ERR_VCENTER_ENTITY_ALREADY_EXISTS

Returned if vCenter server entity exists in the hierarchy either directly or indirectly because of its parent's addition. This occurs, if a parent vCenter entity is added first and the child is added subsequently.

VCB_ERR_ VCENTER_SERVER_HIERARCHY_NOT_FOUND

Returned if a vCenter hierarchy is not found for the specified vCenter identifier.

VCENTER_COMMON_ERR_UNABLE_TO_CONNECT_TO_VCENTER_SERVER

Returned if unable to connect to vCenter server during fetching of custom attributes for a vCenter entity.

VCENTER_COMMON_ERR_INVALID_VCENTER_SERVER_URL

Returned if the vCenter server URL is invalid while retrieving custom attributes for a vCenter entity.

VCB_ERR_RETRIEVING_CUSTOM_ATTRIBUTES

Returned if any error occurs from vCenter during the retrieval of custom attributes for a vCenter entity.

VCB_ERR_INVALID_VC_VIEW_TYPE

Returned if the vCenter server view type is invalid.