Browse Entity

This API is used to browse the hierarchy one entity level at a time. This is generally used as an alternate to loading the entire hierarchy if there are memory limitations. This API call returns basic information about an entity and its immediate children. If further information about an entity is needed, you can use the Get Entity API.

Syntax

GET <Base URL>/hierarchy/{hierarchyId}/entity/{entityId}/browse

A sample API call is as follows:

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

User Privilege

To call this API, you should have a role with Read privilege on the hierarchy and the entity.

URL Parameters

Parameter

Data Type

Required/Optional

Description

Sample Value

numbeOfChildren

Integer

Optional

Use this to specify the number of immediate child entities the API should return. If this parameter is not specified, the API returns the entire list of immediate child entities.

If value is 0, the API does not return any children. If the value is more than the actual number of remaining children, the API returns only the actual number of remaining children.

1

fromIndex

Integer

Optional

Indicates the index from which the API should return the details. For example, if you specify 5, the API returns the entities starting from the fifth index.

If this parameter is not specified, the API gives the children starting from the first index.

2

lastHierarchyRefreshTime

Integer

Optional

Time when the hierarchy was changed last. You can get this time from a previous call of this API or the Browse Hierarchy API.

If the hierarchy has changed in between, and if the value of IgnoreChanges is false, the API displays an error.

1275034498970

IgnoreChanges

Boolean

Optional

Specify true if you want ignore any changes to the hierarchy since the last hierarchy refresh time. Default value is false. If the hierarchy has changed in between, and if the value of IgnoreChanges is false, the API displays an error.

false

 

API Response

If the operation is successful, the API returns an XML response with the following details. The API filters out all entities on which you have No Access role.

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy element to which entity belongs.

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

1

Represents the entity element.

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 provided for the entity.

Hierarchies/Hierarchy/Entities/Entity/Type

xs:int

1

1

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

Hierarchies/Hierarchy/Entities/Entity/ChildrenCount

xs:int

1

1

Indicates the number of immediate child entities.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share

 

1

1

Represents the share of the entity element.

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.

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 is provided here.

Error Response

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

Error Code

Description

VCB_ERR_INVALID_ENTITY_ID

Entity is not found

VCB_ERR_HIERARCHY_MODIFIED

Hierarchy has been modified since the last hierarchy refresh time.