A system administrator can use the vCloud Director Web Console or the vCloud API to create or update role objects in any organization in the system. Organization administrators can use the vCloud API to create or update role objects in the organizations they administer.

Role and right objects are local to an organization. An organization is initially granted a set of rights derived from the rights contained in the predefined roles, and includes a copy of each predefined role. A system administrator can grant additional rights to an organization. See Edit Organization Rights.

Organization administrators can create or update roles in organizations they administer by aggregating a set of rights in a Role element and POSTing it to the organization's add URL for roles. Roles created in this way are local to a specific organization.

Important

An organization administrator cannot modify a predefined role or create a new role that has the same name as a predefined role.

Prerequisites

This operation requires the rights included in the predefined Organization Administrator role or an equivalent set of rights.

Procedure
1

Retrieve the set of rights available to your organization.

To get the RightReference objects that populate the Role, use a request like this one: 

GET https://vcloud.example.com/api/admin/org/id/rights

The OrgRights element returned by this request includes a RightReference element for each right granted to the organization by the system administrator.

2

Create a Role element that defines the role with a name and a set of rights.

See the request portion of Example: Create a Role.

3

POST the Role element to the organization's add URL for roles.

The system creates the role in your organization and returns its representation, a Role element, in the response.

Example: Create a Role

This example adds a role named vAppWrangler to the organization with id 21. The new role is created in this organization, but not in any other organizations in the system. You must be a system administrator or an administrator of this organization to make this request. The rights associated with this new role are less comprehensive than those associated with the built-in vApp Author role, but still include rights to perform many common vApp operations. This example uses href attributes that contain actual UUID values for specific rights, since these are invariant across vCloud Director installations and releases.

Request: 

POST https://vcloud.example.com/api/admin/org/21/roles
Accept: application/*;version=27.0
Content-Type: application/vnd.vmware.admin.role+xml
...
<?xml version="1.0" encoding="UTF-8"?>
<Role
   name="vAppWrangler"
   xmlns="http://www.vmware.com/vcloud/v1.5">
   <Description>Create and manage vApps</Description>
   <RightReferences>
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Copy"
         href="https://vcloud.example.com/api/admin/right/4965b0e7-9ed8-371d-8b08-fc716d20bf4b" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Create / Reconfigure"
         href="https://vcloud.example.com/api/admin/right/2dc8abec-2e0d-3789-a5f9-ce0453160b53" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Delete"
         href="https://vcloud.example.com/api/admin/right/df05c07f-c537-3777-8d9b-a9cfe8d49014" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Edit Properties"
         href="https://vcloud.example.com/api/admin/right/c2a29357-1b2a-3f9d-9cd6-de3d525d49f3" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Edit VM CPU"
         href="https://vcloud.example.com/api/admin/right/729a3828-8b63-31b2-88db-f56612a06722" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Edit VM Hard Disk"
         href="https://vcloud.example.com/api/admin/right/cd02b5f8-c54a-334a-b782-5d31a1d77d85" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Edit VM Memory"
         href="https://vcloud.example.com/api/admin/right/c6c827dc-fc42-33a8-844f-8ab5a91f8a6c" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Edit VM Network"
         href="https://vcloud.example.com/api/admin/right/f24fffde-f953-3976-9f2b-8b355b25881d" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Edit VM Properties"
         href="https://vcloud.example.com/api/admin/right/5250ab79-8f50-33f9-8af5-015cb39c380b" />
      <RightReference
         type="application/vnd.vmware.admin.right+xml"
         name="vApp: Power Operations"
         href="https://vcloud.example.com/api/admin/right/580860cd-55bc-322d-ac39-4f9d8e3e1cd2" />
   </RightReferences>
</Role>

The response is a Role element, most of which does not appear in this excerpt. The response includes links that an administrator can use to edit or remove the role.

Response: 

201 Created
Content-Type: application/vnd.vmware.admin.role+xml
...
<Role
   name="vAppWrangler"
   ...
   href="https://vcloud.example.com/api/admin/org/21/role/102" ...>
   <Link
      rel="edit"
      type="application/vnd.vmware.admin.role+xml"
      href="https://vcloud.example.com/api/admin/org/26/role/102"/>
   <Link
      rel="remove"
      href="https://vcloud.example.com/api/admin/org/26/role/102"/>
   <Description>Create and manage vApps</Description>
   <RightReferences>
      ...
   </RightReferences>
</Role>