Use the get operation to get information about a role.
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.
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 (common.xsd
).
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 (role.xsd
).
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="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>