The API enables you to populate a hierarchy using the entities in CSV format. This includes all the custom Chargeback entities to define the organizational structure, which can be complemented by adding vCenter entities.
The syntax for calling this method is:
POST <Base URL>/hierarchy/{hierarchyId}/populate
A sample API call is as follows:
POST https://123.123.123.123/vCenter-CB/api/hierarchy/{hierarchyId}/populate
You must have a role with the Update privilege on the hierarchy you want to populate and Read privilege on all the vCenter Server entities specified in the CSV request.
Lines beginning with a hash (#) are treated as comments. However, the line beginning with #version is treated as the version field of the csv file. This field is of the format:
#version <version>, where <version> is 1.5.0 for the vCenter Chargeback 1.5 release.
Each record in the CSV file should be in the following format:
{<UniqueId>,<ChildName>,<ParentId>,<ChildEntityType>[[,<description>][,<VC IPAddress/DNS Name>, <vcEntityMoId>, vCenterViewId(Specify 1 (Hosts & Clusters) | 2 (VMs & Templates)]]}
Where
Optional fields:
If you want to add vCenter entity to the hierarchy, you must provide the following information:
Blank lines in the file are skipped.
A sample CSV request is provided here.
If the operation is successful, the API returns details of the populated hierarchy. However, for each hierarchy it returns only the immediate children of the root entity.
The response XML includes 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. |
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, refer 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 is added to the parent. Will always be zero for the root entity. |
A sample response is provided here.
The following table explains the error codes displayed by the API.
Error code |
Description |
VCENTER_COMMON_ERR_INVALID_CSV_VERSION |
If CSV version is not in the specified format. |
VCENTER_COMMON_ERR_INVALID_CSV_FORMAT |
Returned if CSV format is empty or invalid such as insufficient columns and invalid order of columns |
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 entity description exceeds 512 characters. |
VCB_ERR_ENTITY_NAME_ALREADY_EXISTS |
Returned if an entity with the same name exists under the parent. |
VCB_ERR_INVALID_ENTITY_ID |
Returned if a specified parent entity in CSV is not found in the hierarchy. |
VCB_ERR_INVALID_ENTITY_TYPE |
Returned if a specified entity type in CSV is invalid. |
VCB_ERR_INVALID_VCENTER_SERVER |
Returned if an invalid vCenter IP Address/DNS name is specified in the CSV string. |
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_INVALID_VCENTER_ENTITY |
Returned if an invalid vCenter moid entity is specified in the CSV string. |
VCB_ERR_VCENTER_SERVER_HIERARCHY_NOT_FOUND |
Returned if a vCenter hierarchy is not found for the specified vCenter identifier in the CSV string. |
VCB_ERR_VC_ENTITY |
Returned when trying to add an entity to a parent entity, which is a vCenter entity. |
VCB_ERR_INVALID_VC_VIEW_TYPE |
Returned if the vCenter server view type is invalid. |