An organization administrator can create a role by aggregating a set of rights in a Role element and POSTing it to the organization's add URL for roles.

Verify that you are logged in to the vCloud API as an organization administrator or system administrator.

1

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

To get the RightReference objects that populate the Role, retrieve the administrative view of the cloud, using a request like this one:

GET https://vcloud.example.com/api/admin

The VCloud element returned by this request includes a RightReferences element that contains RightReference elements that show the name and href for each right defined in the cloud. For example:

<RightReference
   type="application/vnd.vmware.admin.right+xml"
   name="vApp: Copy"
   href="https://vcloud.example.com/api/admin/right/4965b0e7-9ed8-371d-8b08-fc716d20bf4b" />
2

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

See the request portion of Example: Create a Role.

The server creates a Role element and returns its representation to the client.

This example adds a role named vAppWrangler to the organization created in Example: Create an Organization. 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.

Note

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/roles
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"
   id="urn:vcloud:role:102"
   xmlns="http://www.vmware.com/vcloud/v1.5"
   href="https://vcloud.example.com/api/admin/role/102" ...>
   <Link
      rel="edit"
      type="application/vnd.vmware.admin.role+xml"
      href="https://vcloud.example.com/api/admin/role/102"/>
   <Link
      rel="remove"
      href="https://vcloud.example.com/api/admin/role/102"/>
   <Description>Create and manage vApps</Description>
   <RightReferences>
      ...
   </RightReferences>
</Role>