Class: role

Last published : Oct 01, 2026
A set of permissions associated with a subject
Related information
XenServer 8.4 Management API

Fields for class: role

Field Type Qualifier Description
is_internal bool RO/runtime Indicates whether the role is only to be assigned internally by xapi, or can be used by clients
name_description string RO/constructor what this role is for
name_label string RO/constructor a short user-friendly name for the role
subroles role ref set RO/constructor a list of pointers to other roles or permissions
uuid string RO/runtime Unique identifier/object reference

RPCs associated with class: role

RPC name: getall

Overview:
Return a list of all the roles known to the system.
Signature:
role ref set get_all (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: role ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of role references to role records for all roles known to the system.
Signature:
(role ref -> role record) map get_all_records (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: (role ref -> role record) map
records of all objects

RPC name: getbynamelabel

Overview:
Get all the role instances with the given label.
Signature:
role ref set get_by_name_label (session ref session_ref, string label)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return
Minimum Role: read-only
Return Type: role ref set
references to objects with matching names

RPC name: getbypermission

Overview:
This call returns a list of roles given a permission
Signature:
role ref set get_by_permission (session ref session_ref, role ref permission)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref permission a reference to a permission
Minimum Role: read-only
Return Type: role ref set
a list of references to roles

RPC name: getbypermissionnamelabel

Overview:
This call returns a list of roles given a permission name
Signature:
role ref set get_by_permission_name_label (session ref session_ref, string label)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label The short friendly name of the role
Minimum Role: read-only
Return Type: role ref set
a list of references to roles

RPC name: getbyuuid

Overview:
Get a reference to the role instance with the specified UUID.
Signature:
role ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: role ref
reference to the object

RPC name: getisinternal

Overview:
Get the isinternal field of the given role.
Signature:
bool get_is_internal (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self reference to the object
Minimum Role: read-only
Return Type: bool
value of the field

RPC name: getnamedescription

Overview:
Get the name/description field of the given role.
Signature:
string get_name_description (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getnamelabel

Overview:
Get the name/label field of the given role.
Signature:
string get_name_label (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getpermissions

Overview:
This call returns a list of permissions given a role
Signature:
role ref set get_permissions (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self a reference to a role
Minimum Role: read-only
Return Type: role ref set
a list of permissions

RPC name: getpermissionsnamelabel

Overview:
This call returns a list of permission names given a role
Signature:
string set get_permissions_name_label (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self a reference to a role
Minimum Role: read-only
Return Type: string set
a list of permission names

RPC name: getrecord

Overview:
Get a record containing the current state of the given role.
Signature:
role record get_record (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self reference to the object
Minimum Role: read-only
Return Type: role record
all fields from the object

RPC name: getsubroles

Overview:
Get the subroles field of the given role.
Signature:
role ref set get_subroles (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self reference to the object
Minimum Role: read-only
Return Type: role ref set
value of the field

RPC name: getuuid

Overview:
Get the uuid field of the given role.
Signature:
string get_uuid (session ref session_ref, role ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
role ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field