View or Modify Role Template Linkage

Each predefined role in your organization is initially linked to a template that specifies the set of rights in the role. An organization administrator can unlink a role from its template to prevent the role from being affected if a system administrator modifies the predefined role.

Role templates are system objects that, while they cannot be directly modified, are affected when a system administrator updates a predefined role to add or remove rights. As long as a role in your organization is linked to its template, any changes that the system administrator makes to the set of rights in a predefined role affect the template itself and all roles that link to it.

Roles that you create in your organization are never linked to a template.

Use the unlinkFromTemplate and relinkToTemplate action links in a Role object to manage the linkage between a predefined role in your organization and the template from which it was derived.

Important: Some vCloud APIs for managing rights and roles are under accelerated deprecation. See vCloud API Programming Guide for Service Providers.

vCloud Director 9.5 introduces OpenAPIs for managing rights and roles. You can examine the vCloud OpenAPI documentation at https://vCloud_Director_IP_address_or_host_name/docs.

Prerequisites

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

Procedure

Retrieve the list of roles in your organization.

See the RoleReferences element of your organization. This element contains a reference to local instance of each predefined role. It also contains references to roles created in the organization.

GET https://vcloud.example.com/api/admin/org/26
...
<AdminOrg ... >
   ...
   <RoleReferences>
      <RoleReference
         href="https://vcloud.example.com/api/admin/org/26/role/29971497-38da-3974-98d6-e39bbd5b482f"
         name="Defer to Identity Provider"
         type="application/vnd.vmware.admin.role+xml" />
      <RoleReference
         href="https://vcloud.example.com/api/admin/org/26/role/2e4ad538-67f5-4d4d-ad51-2dcd512a30f6"
         name="Console Access Only"
         type="application/vnd.vmware.admin.role+xml" />
      ...
      <RoleReference
         href="https://vcloud.example.com/api/admin/org/26/role/13a69c14-e64c-409f-800f-0ecc470ea42d"
         name="vApp Author"
         type="application/vnd.vmware.admin.role+xml" />
   </RoleReferences>
</AdminOrg>

Retrieve a role to view the state of its template linkage.

In this example the role is linked to its template, so the representation of the role includes an unlinkFromTemplate action.

GET https://vcloud.example.com/api/admin/org/26/role/13a69c14-e64c-409f-800f-0ecc470ea42d
...
<?xml version="1.0" encoding="UTF-8"?>
<Role name="vApp Author" .>
   ...
   <Link
      rel="unlinkFromTemplate"
      href="https://vcloud.example.com/api/admin/org/26/role/190c565b-4f54-4275-aafb-2d22ed4f0c73/action/unlinkFromTemplate"
      type="application/vnd.vmware.admin.role+xml" />

   <Description>Rights given to a user who uses catalogs and
      creates
      vApps
   </Description>
   <RightReferences>
      ...
   </RightReferences>
</Role>

Unlink the role.
Make a POST request to the href in the Link that implements the unlinkFromTemplate action.
```
POST https://vcloud.example.com/api/admin/org/26/role/190c565b-4f54-4275-aafb-2d22ed4f0c73/action/unlinkFromTemplate
      ...
204 No Content
```
When you retrieve the role after this operation completes the unlinkFromTemplate action is replaced by a relinkToTemplate action.
```
GET https://vcloud.example.com/api/admin/org/26/role/13a69c14-e64c-409f-800f-0ecc470ea42d
...
<?xml version="1.0" encoding="UTF-8"?>
<Role name="vApp Author" .>
   ...
   <Link
      rel="relinkToTemplate"
      href="https://vcloud.example.com/api/admin/org/26/role/190c565b-4f54-4275-aafb-2d22ed4f0c73/action/relinkToTemplate"
      type="application/vnd.vmware.admin.role+xml" />

   ...
</Role>
```
When you re-link a role in your organization to its template, the set of rights in the role is the intersection of the set of rights in your organization and the set of rights in the template. If the template has been modified to include rights that have not been granted to your organization, the role will not have those rights until a system administrator grants them to your organization. If the template has been modified to remove rights, re-linking the role to its template removes those rights fromthe role.