Populate Hierarchy

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.

Syntax

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

User Privilege

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.

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:

Blank lines in the file are skipped.

A sample CSV request is provided here.

API Response

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.

Error Response

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.
Valid version values:
“#version 1.5.0”.

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.