Share an Entity

This API enables you to share an entity among multiple parent entities. The total share percentage of all the parent entities should be equal to 100.

For example, when you add an entity to parent 1, the default share is 100%. If you want to share 50% of the same entity with parent 2, you must call this API with 50% to parent 1 and 50% to parent 2. This adds a new relation with 50% attribution percentage for parent 2. This also reduces the parent 1 attribution percentage to 50%. If you want to remove the sharing of the entity with parent 2, set the value to 0% for that entity under parent 2 and the remaining 100% to the parent 1.

To modify the share percentage of any parent of an entity, you should first get the existing share percentage of all the parents of that entity and then set the new share percentage such that the total percentage is equal to 100. You cannot modify the share percentage of only a few parents of an entity.

Note: Currently, only virtual machine entities directly added to a parent Chargeback entity can be shared.

Syntax

The syntax for calling this method is:

PUT <Base_Url>/hierarchy/{hierarchyId}/entity/{entityId}/share

A sample API call is as follows:

PUT https://123.123.123.123/vCenter-CB/api/hierarchy/1/entity/51/share

User Privilege

To call this API, you must have a role with Update privilege on the hierarchy, the entity and all the specified parent entities.

Request Body Parameters

The API takes a request XML in which you can provide the following body parameters.

XPath

Type

Min Occurs

Max Occurs

Description

Hierarchies/Hierarchy

 

1

1

Represents the hierarchy to which the entity belongs.

Hierarchies/Hierarchy/@id

xs:int

0

1

ID of the hierarchy.

Hierarchies/Hierarchy/Entities/Entity

 

1

1

Represents each entity element that is being shared.

Hierarchies/Hierarchy/Entities/Entity/@id

xs:int

0

1

The ID of the entity.

Hierarchies/Hierarchy/Entities/Entity/Shares/Share

 

1

unbounded

Represents the share of the entity element with its parent.

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

xs:int

1

1

Percent of sharing the entity for the parent entity in the hierarchy.

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

xs:int

1

1

The ID of the parent entity.

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 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. Currently, only the virtual machine entities are shared. So the value of type is always 0. For more information on entity types, see Chargeback Entity Types.

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/ParentPath

xs:string

1 1

The path from the root entity to the parent of this entity. The root entity path is indicated by /.

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

Returned if the specified entity is not found in the hierarchy.

VCB_ERR_ENTITY_NOT_VM

Returned if the specified entity is not a Virtual Machine

VCB_ERR_INVALID_PARENT_ENTITY_ID

Returned if any of the specified parent entities are not found in the hierarchy.

VCB_ERR_INVALID_SHARED_PERCENTAGE

Returned if any of the specified percentage values are invalid (i.e. less than 0 and greater than 100) or if
the total of attribution percentage of all the parents do not add up to 100%.