Add Hierarchy

The API enables you to create a hierarchy with the specified name and description. If successful, the API returns the details of the new hierarchy.

Syntax

The syntax for calling this method is:

POST <Base URL>/hierarchy

A sample API call is as follows:

POST https://123.123.123.123/vCenter-CB/api/hierarchy

User Privilege

You must have a role with the Create privilege for the hierarchy resource type.

Request Body Parameters

The API takes a request XML that captures the following body parameters.

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy element to be added.

Hierarchies/Hierarchy/Name

xs:string

1

1

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

Hierarchies/Hierarchy/Description

xs:string

0

1

An optional description for the hierarchy. 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 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 added.

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 of 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 root entity element that is created.

Hierarchies/Hierarchy/Entities/Entity/@id

xs:int

1

1

The ID of the root 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 on various entity types, refer Chargeback EntityTypes.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share

 

1

1

Represents the share of the root entity element.

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

xs:int

1

1

The root element is never shared. Hence, the sharing percentage is always 100%.

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

xs:int

1

1

The root entity does not have a parent. 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

VCB_ERR_INVALID_HIERARCHY_NAME

  • An empty hierarchy name is specified
  • Hierarchy name exceeds 255 characters

VCB_ERR_INVALID_HIERARCHY_DESCRIPTION

Hierarchy description exceeds 512 characters

VCB_ERR_HIERARCHY_NAME_ALREADY_EXISTS

A hierarchy with the given name exists

VCB_ERR_HIERARCHY_ROOT_ENTITY_TYPE_NOT_FOUND

Chargeback root entity type identifier is not found in the database. This generally indicates a corrupted vCenter Chargeback Manager databse.