Getting Information About a Role
Use the get operation to get information about a role.
Request Packet Structure
A request XML packet getting information about specified roles includes the get operation node:
<packet>
<role>
<get>
...
</get>
</role>
</packet>
The get node is nested within the RoleGetInput type (role.xsd
). This node has the following graphics representation:
-
filter, required
It specifies the filtering rule to match roles the information on which will be provided. Data type: RoleSelectionFilter (
role.xsd
). To see the structure of this node, proceed to section Available Filters. -
owner-guid, optional
It specifies the GUID of a role owner (a customer or the Administrator). If you do not specify this node, the role owner will be the request packet sender. Data type: string. For details on how to get a customer GUID, see the Getting Information About Client Accounts section.
Important: When creating request packets, put nodes and elements in the order they follow in the packet structure.
Response Packet Structure
The get node of the response packet is structured as follows:
-
result, optional
It wraps the result of the requested operation. It can be missing if some error occurs before the validation starts. Data type: resultType (
common.xsd
). -
status, required
It returns the execution status of the operation. Data type: string. Allowed values: ok | error.
-
errcode, optional
It is used to return the error code when the operation fails. Data type: unsignedInt.
-
errtext, optional
It contains the error message if the operation fails. Data type: string.
-
filter-id, optional
If supported, it is always present and contains the filtering rule parameter specified in a request packet. Data type: anySimple.
-
id, optional
The node is missing if the request packet fails before the validation on the server side. If present, it returns the ID of the retrieved role. Data type: integer.
-
data, optional
It contains a collection of requested role settings if the operation succeeds. Data type: RoleGetOutputData (
role.xsd
).
The data node of the response get packet is structured as follows:
-
name, required
It defines a role name. Data type: string.
-
owner-guid, required
It specifies the GUID of a role owner (a customer or the Administrator). Data type: string.
-
is-built-in, required
If a role is the Admin or Accountant, the node value is true. Otherwise, it is false. Data type: boolean.
-
permissions, required
It specifies a collection of permissions granted to a role. Data type: RolePermissions (
role.xsd
). See the structure of this node in the Permissions Granted to Roles section.
Samples
A request packet to get the information about the role with ID 1 looks as follows:
<packet version="1.6.3.0">
<role>
<get>
<filter>
<id>1</id>
</filter>
</get>
</role>
</packet>
A response packet that includes the information about the role with ID 57 (reduced) can look as follows:
<packet version="1.6.3.0">
<role>
<get>
<result>
<status>ok</status>
<filter-id>1</filter-id>
<id>1</id>
<data>
<name>Admin</name>
<owner-guid>58bb9092-4c8b-4110-ba3d-c40bdad3b178</owner-guid>
<is-build-in>true</is-build-in>
<permissions>
<permission>
<name>userManagement</name>
<value>true</value>
</permission>
...
</permissions>
</data>
</result>
</get>
</role>
</packet>