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.
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
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.
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 |
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, |
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.
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.
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. |
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. |