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:
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.
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:
It wraps the result of the requested operation. It can be missing if some error occurs before the validation starts. Data type: resultType (
It returns the execution status of the operation. Data type: string. Allowed values: ok | error.
It is used to return the error code when the operation fails. Data type: unsignedInt.
It contains the error message if the operation fails. Data type: string.
If supported, it is always present and contains the filtering rule parameter specified in a request packet. Data type: anySimple.
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.
It contains a collection of requested role settings if the operation succeeds. Data type: RoleGetOutputData (
The data node of the response get packet is structured as follows:
It defines a role name. Data type: string.
It specifies the GUID of a role owner (a customer or the Administrator). Data type: string.
If a role is the Admin or Accountant, the node value is true. Otherwise, it is false. Data type: boolean.
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.
A request packet to get the information about the role with ID 1 looks as follows:
<packet version="126.96.36.199"> <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="188.8.131.52"> <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>